Controlando o widget

Shayan TaslimAtualizado

Você pode controlar o widget programaticamente pela sua própria interface: abrir seções específicas, reagir a eventos, configurar anúncios de atualizações ou substituir completamente o iniciador padrão.

Abrindo o widget

Chamar uj.open() sem argumentos abre o widget no ponto em que o usuário parou:

JavaScript
uj.open();

Passe um destino para abrir uma seçã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 links diretos 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 a exibição do widget a qualquer momento:

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

O destino messages exige que Conversas esteja ativado; caso contrário, ele informa CONVERSATIONS_DISABLED pelo evento error e abre a página inicial. O destino help exige que sua Central de Ajuda esteja publicada (article e collection usam o slug do URL); caso contrário, ele informa HELP_DISABLED e abre a página inicial.

Ouvindo eventos

Inscreva-se com uj.on(event, listener), que retorna uma função para cancelar a inscrição:

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

unsubscribe();

Evento

Quando é disparado

ready

O SDK terminou de carregar. É disparado imediatamente se já tiver carregado.

open

O widget ficou visível.

close

O widget foi ocultado.

identify

A identidade mudou, incluindo o logout.

unread

A contagem de itens não lidos foi alterada. O payload é { count }. Reproduz o evento imediatamente se o widget já estiver pronto.

presence

A disponibilidade da equipe foi alterada. O payload é { availability: 'online' | 'neutral' }. Reproduz o evento imediatamente se o widget já estiver pronto.

statechange

Qualquer parte do estado do widget mudou.

error

Algo deu errado. O payload é o objeto de erro.

Lendo o estado

uj.getState() retorna um instantâneo 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

Criando seu próprio botão de abertura

Oculte o iniciador padrão para controlar o widget pelo seu próprio item de navegação ou botão:

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

Ocultar o iniciador remove o botão padrão, mas mantém ativos no canto os avisos de notificação (consulte a seção Avisos abaixo para reposicioná-los ou desativá-los).

Configure seu botão, o indicador de itens não lidos e, opcionalmente, o indicador de disponibilidade da equipe:

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 se há um atendente online no momento. Portanto, oculte o indicador em vez de exibir um rótulo de indisponibilidade. Enquanto o widget estiver fechado, a presença será atualizada ao carregar a página, quando a aba receber foco e a cada poucos minutos. Enquanto estiver aberto, ela será atualizada em tempo real.

No iniciador padrão, o indicador de itens não lidos tem prioridade sobre o ponto verde de presença online. A contagem de itens não lidos reúne respostas de conversas, publicações de changelog e notificações de feedback. Ao clicar no iniciador padrão enquanto houver itens não lidos, você será direcionado nesta ordem de prioridade: Mensagens (respostas de conversas não lidas), depois Notificações (notificações de feedback não visualizadas) e, por fim, a Atualização mais recente ainda não visualizada.

Para associar diretamente o comportamento do iniciador padrão a um elemento existente na sua página, passe um seletor CSS:

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

Whispers

Os avisos são notificações breves e clicáveis no canto da tela, que anunciam respostas não lidas de conversas da equipe, notificações de feedback e novas publicações de changelog. A prioridade segue esta ordem: primeiro, respostas não lidas de conversas; depois, notificações de comentários ou respostas de feedback; em seguida, outras notificações; e, por último, atualizações do changelog. Para preservar a privacidade, os avisos de conversa mostram apenas o avatar do colega de equipe e <Name> replied (nunca o texto da mensagem). Ao clicar neles, você abre Mensagens.

  • Recência e intervalo: Só geram avisos os itens criados ou publicados nos últimos 14 dias. O widget aguarda atividade real do usuário, 4 segundos na página, 1,2 segundo sem movimento e pelo menos 30 segundos desde o aviso anterior. Os avisos nunca interrompem o usuário enquanto ele digita em um campo de entrada, área de texto, menu suspenso ou campo editável, nem aparecem em navegadores automatizados.

  • Limites de repetição e intervalos crescentes: Cada item gera no máximo 3 avisos entregues (é necessário que fique visível e receba atenção por 1,5 segundo para ser considerado entregue), 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 de conversas.

  • Com ou sem o iniciador padrão: Os avisos funcionam independentemente do iniciador. Com o iniciador padrão, eles se expandem a partir do botão. Com launcher: false ou um iniciador por seletor, aparecem sozinhos no canto da tela e, após expirarem, se recolhem em um círculo clicável que permanece por 60 segundos antes de desaparecer.

Reposicione os avisos para que não se sobreponham à sua interface usando offset:

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

Ou desative completamente os avisos (suprimindo os avisos de conversas, feedback e atualizações padrão):

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

Com ambos desativados e sem um modo de atualização especificado, o widget não exibe nada até que você chame uj.open(). As inscrições em unread e presence, porém, continuam sendo atualizadas em segundo plano.

Anúncios de atualizações

Controle como o widget anuncia a entrada mais recente do changelog que ainda não foi vista usando widget.notifications.updates:

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

Modo

Comportamento

'whisper'

Anuncia a atualização em uma notificação 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, mas mantém ativa a aba Atualizações e o indicador de itens não lidos.

Se omitido, as atualizações usam 'whisper' por padrão (ou 'none' quando whispers: false). Definir widget.notifications.updates explicitamente substitui whispers apenas para as atualizações do changelog; os avisos de conversas e feedback continuam seguindo whispers.

O modo completo funciona mesmo com o iniciador oculto e sem ouvintes de eventos. Na primeira visita, ele pode abrir a atualização publicada mais recente, mesmo que ela seja antiga. O SDK tenta abrir automaticamente no máximo uma vez por visita de inicialização (uma abertura manual, alternância, fechamento ou tentativa malsucedida consome essa tentativa; recarregar ou chamar init() inicia uma nova visita, mas mudanças de identidade ou navegação em um SPA não). A abertura automática exige que a página esteja visível e em foco e que o widget esteja fechado. Ela fica desativada quando widget: false.

Uma atualização é marcada como vista quando seu conteúdo é montado no widget exibido em uma página visível e em foco. O estado de visualização é armazenado localmente no navegador, por projeto e origem. As atualizações são detectadas na inicialização, quando a aba recebe foco e aproximadamente a cada cinco minutos enquanto o widget está fechado.

Alterar o idioma

Quando locale não é especificado, o widget escolhe um idioma nesta ordem:

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

  2. O idioma do navegador do visitante, se corresponder a um dos idiomas ativados no seu workspace em Configurações → Idiomas.

  3. O idioma padrão do seu workspace.

O widget oferece suporte aos 14 idiomas do UserJot (consulte Idiomas). Altere 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');

Isso respondeu à sua pergunta?