Controlar o widget
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:
uj.open();Indique um destino para abrir uma secção específica:
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:
// 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:
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:
const unsubscribe = uj.on('open', () => {
console.log('widget opened');
});
unsubscribe();Evento | Quando é acionado |
|---|---|
| O SDK terminou de carregar. É acionado imediatamente se já estiver carregado. |
| O widget ficou visível. |
| O widget foi ocultado. |
| A identidade foi alterada, incluindo ao terminar sessão. |
| O número de itens por ler foi alterado. O payload é |
| A disponibilidade da equipa foi alterada. O payload é |
| Qualquer parte do estado do widget foi alterada. |
| Ocorreu um erro. O payload é o objeto de erro. |
Ler o estado
uj.getState() devolve uma captura do estado atual do widget:
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 nullCriar 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:
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:
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:
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: falseou 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:
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):
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:
uj.init('YOUR_PROJECT_ID', {
widget: {
notifications: { updates: 'full' }
}
});Modo | Comportamento |
|---|---|
| Anuncia a atualização num aviso no canto, com limites de repetição. |
| Abre a atualização diretamente no leitor do widget, com a imagem de capa e o conteúdo completo. |
| 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:
Uma opção
localeexplícita passada auj.init(...)ouuj.setLocale(...).O idioma do browser do visitante, se corresponder a um dos idiomas ativados no seu espaço de trabalho em Definições → Idiomas.
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:
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });
// Change later at runtime
await uj.setLocale('pt-BR');