Controlar o widget

Shayan TaslimAtualizado

Pode controlar o widget programaticamente a partir da sua própria interface: abrir secções específicas, reagir a eventos, configurar anúncios de atualizações ou substituir totalmente o launcher predefinido.

Abrir o widget

Chamar uj.open() sem argumentos abre o widget no ponto onde o utilizador o deixou:

JavaScript
uj.open();

Indique um destino para abrir uma secção específica:

JavaScript
uj.open({ to: 'home' });
uj.open({ to: 'feedback' });
uj.open({ to: 'roadmap' });
uj.open({ to: 'updates' });
uj.open({ to: 'messages' });
uj.open({ to: 'notifications' });
uj.open({ to: 'help' });

Opções de ligação direta para destinos específicos:

JavaScript
// Open the feedback submission form directly
uj.open({ to: 'feedback', compose: true });

// Open a specific feedback post
uj.open({ to: 'feedback', submissionId: 'POST_ID' });

// Open a specific changelog update
uj.open({ to: 'updates', updateId: 'UPDATE_ID' });

// Start a message with prefilled text
uj.open({ to: 'messages', compose: { text: 'I need help with...' } });

// Open a help article, collection, or search results
uj.open({ to: 'help', article: 'reset-password' });
uj.open({ to: 'help', collection: 'billing' });
uj.open({ to: 'help', query: 'invoices' });

Oculte ou alterne o widget a qualquer momento:

JavaScript
uj.close();
uj.toggle();

O destino messages requer que a funcionalidade Conversations esteja ativada; caso contrário, comunica CONVERSATIONS_DISABLED através do evento error e abre Início. O destino help requer que o seu Centro de Ajuda esteja ativo (article e collection recebem o slug do URL); caso contrário, comunica HELP_DISABLED e abre Início.

Escutar eventos

Subscreva com uj.on(event, listener), que devolve uma função para cancelar a subscrição:

JavaScript
const unsubscribe = uj.on('open', () => {
  console.log('widget opened');
});

unsubscribe();

Evento

Quando é acionado

ready

O SDK terminou de carregar. É acionado imediatamente se já estiver carregado.

open

O widget ficou visível.

close

O widget foi ocultado.

identify

A identidade foi alterada, incluindo ao terminar sessão.

unread

O número de itens por ler foi alterado. O payload é { count }. Se já estiver pronto, reproduz o evento imediatamente.

presence

A disponibilidade da equipa foi alterada. O payload é { availability: 'online' | 'neutral' }. Se já estiver pronto, reproduz o evento imediatamente.

statechange

Qualquer parte do estado do widget foi alterada.

error

Ocorreu um erro. O payload é o objeto de erro.

Ler o estado

uj.getState() devolve uma captura do estado atual do widget:

JavaScript
const state = uj.getState();

state.status;          // 'ready' once the SDK is loaded
state.widget.open;     // whether the widget is visible
state.unreadCount;     // number, or null before the first fetch
state.presence;        // 'online' or 'neutral'
state.session.status;  // 'anonymous', 'identifying', or 'identified'
state.session.viewer;  // the identified user, or null

Criar o seu próprio botão de início

Oculte o launcher predefinido para controlar o widget a partir de um item de navegação ou botão próprio:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: false }
});

Ocultar o launcher remove o botão predefinido, mantendo ativas no canto as notificações discretas (consulte a secção Notificações discretas abaixo para as reposicionar ou desativar).

Configure o seu botão, o indicador de itens por ler e, opcionalmente, um indicador de disponibilidade da equipa:

JavaScript
const button = document.querySelector('#feedback-button');
const badge = document.querySelector('#feedback-badge');
const dot = document.querySelector('#feedback-online-dot');

button.addEventListener('click', () => uj.toggle());

uj.on('unread', ({ count }) => {
  badge.textContent = count > 0 ? String(count) : '';
});

uj.on('presence', ({ availability }) => {
  dot.hidden = availability !== 'online';
});

'neutral' significa que o SDK não consegue confirmar que há um agente online neste momento; por isso, oculte o indicador em vez de apresentar um estado offline. Enquanto o widget estiver fechado, a presença é atualizada ao carregar a página, ao focar o separador e de poucos em poucos minutos; enquanto estiver aberto, é atualizada em tempo real.

No botão de abertura predefinido, o indicador de itens por ler tem prioridade sobre o ponto verde de presença online. A contagem de itens por ler inclui respostas a conversas, publicações do registo de alterações e notificações de feedback. Se clicar no botão de abertura predefinido enquanto houver itens por ler, será encaminhado por esta ordem de prioridade: Mensagens (respostas a conversas por ler), depois Notificações (notificações de feedback não vistas) e, por fim, a Atualização mais recente que ainda não tenha visto.

Para associar diretamente o comportamento do launcher predefinido a um elemento existente na sua página, indique um seletor CSS:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: { selector: '#feedback-button' } }
});

Notificações sussurradas

Os avisos discretos são notificações breves e clicáveis no canto do ecrã que anunciam respostas por ler a conversas da equipa, notificações de feedback e novas publicações no registo de alterações. A prioridade segue esta ordem: primeiro, respostas a conversas por ler; depois, notificações de comentários/respostas de feedback; em seguida, outras notificações; e, por fim, atualizações do registo de alterações. Para proteger a privacidade, os avisos de conversas mostram apenas o avatar do colega de equipa e <Name> replied (nunca o texto da mensagem), e, ao clicar, abrem Mensagens.

  • Atualidade e temporização: Só geram avisos os itens criados ou publicados nos últimos 14 dias. O widget aguarda por atividade real do utilizador, 4 segundos na página, 1,2 segundos de imobilidade e pelo menos 30 segundos desde o aviso anterior. Os avisos nunca interrompem o utilizador enquanto este escreve num campo de entrada, numa área de texto, numa lista de seleção ou num campo editável, nem são apresentados em navegadores automatizados.

  • Limites de repetição e intervalos crescentes: Cada item gera no máximo 3 avisos apresentados (é necessário que esteja visível e a receber atenção durante 1,5 segundos para contar como apresentado), com intervalos crescentes de 30 minutos, 24 horas e 3 dias para atualizações, ou de 30 minutos, 1 hora e 24 horas para notificações e respostas a conversas.

  • Com ou sem o botão de abertura predefinido: Os avisos são independentes do botão de abertura. Com o botão de abertura predefinido, expandem-se a partir do botão; com launcher: false ou um botão de abertura definido por seletor, aparecem no canto por si só e, após expirarem, recolhem-se num círculo clicável que permanece visível durante 60 segundos antes de desaparecer.

Afaste as notificações discretas da sua própria interface com offset:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    launcher: false,
    offset: { bottom: 84 } // pixels from the bottom edge; `side` works too
  }
});

Também pode desativar completamente os avisos (suprimindo os avisos de conversas, de feedback e de atualizações predefinidos):

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: { launcher: false, whispers: false }
});

Com ambos desativados e sem um modo de atualização explícito, o widget não apresenta nada até chamar uj.open(), enquanto as subscrições unread e presence continuam a ser atualizadas em segundo plano.

Anúncios de atualizações

Controle a forma como o widget anuncia a entrada mais recente do registo de alterações ainda não vista com widget.notifications.updates:

JavaScript
uj.init('YOUR_PROJECT_ID', {
  widget: {
    notifications: { updates: 'full' }
  }
});

Modo

Comportamento

'whisper'

Anuncia a atualização num aviso no canto, com limites de repetição.

'full'

Abre a atualização diretamente no leitor do widget, com a imagem de capa e o conteúdo completo.

'none'

Suprime os anúncios de atualizações, mantendo ativos o separador Atualizações e o indicador de itens por ler.

Se não for especificado, as atualizações usam 'whisper' por predefinição (ou 'none' quando whispers: false). Definir widget.notifications.updates explicitamente substitui whispers apenas para as atualizações do registo de alterações; os avisos de conversas e de feedback continuam a seguir whispers.

O modo completo funciona mesmo com o launcher oculto e sem ouvintes de eventos. Na primeira visita, o modo completo pode abrir a atualização publicada mais recente, mesmo que seja antiga. O SDK tenta abrir automaticamente no máximo uma vez por visita de inicialização (uma abertura manual, alternância, fecho ou tentativa falhada consome essa possibilidade; recarregar a página ou chamar init() inicia uma nova visita, mas as alterações de identidade ou a navegação numa SPA não o fazem). A abertura automática requer que a página esteja visível e focada e que o widget esteja fechado; é desativada quando widget: false.

Uma atualização é marcada como vista assim que o seu conteúdo é apresentado no widget aberto, numa página visível e focada. O estado de visualização é guardado localmente no armazenamento do browser, por projeto e origem. As atualizações são detetadas na inicialização, quando o separador recebe o foco e aproximadamente de cinco em cinco minutos enquanto o widget está fechado.

Alterar o idioma

Se locale não for especificado, o widget escolhe um idioma pela seguinte ordem:

  1. Uma opção locale explícita passada a uj.init(...) ou uj.setLocale(...).

  2. O idioma do browser do visitante, se corresponder a um dos idiomas ativados no seu espaço de trabalho em Definições → Idiomas.

  3. O idioma predefinido do seu espaço de trabalho.

O widget suporta os 14 idiomas do UserJot (consulte Idiomas). Substitua o idioma na inicialização ou em tempo de execução, sem recarregar a página:

JavaScript
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });

// Change later at runtime
await uj.setLocale('pt-BR');

Isto respondeu à sua pergunta?