Controllare il widget
Puoi controllare il widget a livello di codice dalla tua interfaccia: aprire sezioni specifiche, reagire agli eventi, configurare gli annunci degli aggiornamenti o sostituire completamente il launcher predefinito.
Aprire il widget
Chiamando uj.open() senza argomenti, il widget si apre nella sezione in cui l'utente si era fermato:
uj.open();Passa una destinazione per aprire una sezione specifica:
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' });Opzioni di deep link per destinazioni specifiche:
// 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' });Nascondi o attiva e disattiva il widget in qualsiasi momento:
uj.close();
uj.toggle();La destinazione messages richiede che Conversations sia abilitato; in caso contrario, viene segnalato CONVERSATIONS_DISABLED tramite l'evento error e si apre Home. La destinazione help richiede che il tuo Centro assistenza sia attivo (article e collection usano lo slug dell'URL); in caso contrario, viene segnalato HELP_DISABLED e si apre Home.
Ascoltare gli eventi
Iscriviti con uj.on(event, listener), che restituisce una funzione per annullare l'iscrizione:
const unsubscribe = uj.on('open', () => {
console.log('widget opened');
});
unsubscribe();Evento | Quando viene attivato |
|---|---|
| L'SDK ha terminato il caricamento. Viene attivato immediatamente se il caricamento è già completato. |
| Il widget è diventato visibile. |
| Il widget è stato nascosto. |
| L'identità è cambiata, anche in caso di disconnessione. |
| Il conteggio dei messaggi non letti è cambiato. Il payload è |
| La disponibilità del team è cambiata. Il payload è |
| È cambiata una qualsiasi parte dello stato del widget. |
| Si è verificato un errore. Il payload è l'oggetto dell'errore. |
Leggere lo stato
uj.getState() restituisce uno snapshot dello stato attuale del 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 nullCreare il proprio pulsante di avvio
Nascondi il launcher predefinito per controllare il widget dalla voce di navigazione o dal pulsante della tua interfaccia:
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: false }
});Nascondere il launcher rimuove il pulsante predefinito, ma mantiene attive nell'angolo le notifiche a comparsa (consulta la sezione Notifiche a comparsa qui sotto per spostarle o disattivarle).
Collega il tuo pulsante, il badge dei messaggi non letti e, facoltativamente, l'indicatore di disponibilità del team:
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 che l'SDK non può confermare che un operatore sia attualmente online. Nascondi quindi l'indicatore anziché mostrare un'etichetta che indica che è offline. Quando il widget è chiuso, la presenza viene aggiornata al caricamento della pagina, quando la scheda torna attiva e ogni pochi minuti; quando è aperto, viene aggiornata in tempo reale.
Nel launcher predefinito, l’indicatore dei messaggi non letti ha la precedenza sul pallino verde che segnala la presenza online. Il conteggio dei messaggi non letti include le risposte alle conversazioni, i post del changelog e le notifiche di feedback. Se ci sono elementi non letti, facendo clic sul launcher predefinito si viene indirizzati, in questo ordine di priorità, a: Messaggi (risposte non lette alle conversazioni), poi Notifiche (notifiche di feedback non visualizzate) e infine l’ultimo Aggiornamento non visualizzato.
Per associare direttamente il comportamento predefinito del launcher a un elemento già presente nella pagina, passa un selettore CSS:
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: { selector: '#feedback-button' } }
});Whispers
I whisper sono brevi notifiche toast, cliccabili e visualizzate nell’angolo, che segnalano risposte non lette alle conversazioni del team, notifiche di feedback e nuovi post del changelog. L’ordine di priorità è il seguente: prima le risposte non lette alle conversazioni, poi le notifiche di commenti o risposte al feedback, poi le altre notifiche e infine gli aggiornamenti del changelog. Per tutelare la privacy, i whisper delle conversazioni mostrano solo l’avatar del membro del team e <Name> replied (mai il testo del messaggio); facendo clic si apre Messaggi.
Attualità e tempistiche: vengono mostrati whisper solo per gli elementi creati o pubblicati negli ultimi 14 giorni. Il widget attende che l’utente compia un’azione effettiva, che resti 4 secondi sulla pagina, che rimanga inattivo per 1,2 secondi e che siano trascorsi almeno 30 secondi dal whisper precedente. I whisper non interrompono mai l’utente mentre digita in un campo input, textarea, select o modificabile, né vengono mostrati nei browser automatizzati.
Limiti di ripetizione e intervalli crescenti: ogni elemento viene mostrato al massimo 3 volte (perché venga conteggiato come visualizzato, deve rimanere visibile per 1,5 secondi mentre l’utente presta attenzione), con intervalli di 30 minuti, 24 ore e 3 giorni per gli aggiornamenti, oppure di 30 minuti, 1 ora e 24 ore per le notifiche e le risposte alle conversazioni.
Con o senza il launcher predefinito: i whisper sono indipendenti dal launcher. Con il launcher predefinito, si espandono a partire dal pulsante; con
launcher: falseo un launcher basato su selettore, vengono visualizzati autonomamente nell’angolo e, dopo la scadenza, si richiudono in un cerchio cliccabile che rimane visibile per 60 secondi prima di scomparire.
Sposta le notifiche a comparsa per evitare che si sovrappongano alla tua interfaccia con offset:
uj.init('YOUR_PROJECT_ID', {
widget: {
launcher: false,
offset: { bottom: 84 } // pixels from the bottom edge; `side` works too
}
});In alternativa, disattiva completamente i whisper (escludendo quelli relativi alle conversazioni, al feedback e agli aggiornamenti predefiniti):
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: false, whispers: false }
});Se entrambe sono disattivate e non è specificata una modalità di aggiornamento, il widget non mostra nulla finché non chiami uj.open(). Le iscrizioni a unread e presence continuano ad aggiornarsi in background.
Annunci degli aggiornamenti
Controlla come il widget annuncia l'ultima voce del changelog non ancora vista con widget.notifications.updates:
uj.init('YOUR_PROJECT_ID', {
widget: {
notifications: { updates: 'full' }
}
});Modalità | Comportamento |
|---|---|
| Annuncia l'aggiornamento con una notifica a comparsa nell'angolo, con limiti di ripetizione. |
| Apre direttamente l'aggiornamento nel lettore del widget, mostrando l'immagine di copertina e il contenuto completo. |
| Sopprime gli annunci degli aggiornamenti, mantenendo attive la scheda Aggiornamenti e il badge dei messaggi non letti. |
Se omesso, il valore predefinito per gli aggiornamenti è 'whisper' (oppure 'none' quando whispers: false). L’impostazione esplicita di widget.notifications.updates sostituisce whispers solo per gli aggiornamenti del changelog; i whisper delle conversazioni e del feedback continuano a seguire whispers.
La modalità completa funziona anche con il launcher nascosto e senza listener di eventi. Alla prima visita, la modalità completa può aprire l'ultimo aggiornamento pubblicato anche se è meno recente. L'SDK tenta al massimo un'apertura automatica per visita di inizializzazione (un'apertura manuale, un'attivazione o disattivazione, una chiusura o un tentativo non riuscito consuma questa possibilità; ricaricare la pagina o chiamare init() avvia una nuova visita, mentre le modifiche di identità o la navigazione SPA non lo fanno). L'apertura automatica richiede che la pagina sia visibile e attiva e che il widget sia chiuso; è disabilitata quando widget: false.
Un aggiornamento viene contrassegnato come visualizzato quando il suo contenuto viene caricato nel widget aperto su una pagina visibile e attiva. Lo stato di visualizzazione viene memorizzato localmente nel browser per progetto e origine. Gli aggiornamenti vengono rilevati all'inizializzazione, quando la scheda torna attiva e all'incirca ogni cinque minuti mentre il widget è chiuso.
Cambiare la lingua
Se locale viene omesso, il widget sceglie una lingua seguendo questo ordine:
Un'opzione
localeesplicita passata auj.init(...)ouj.setLocale(...).La lingua del browser del visitatore, se corrisponde a una delle lingue abilitate nel tuo spazio di lavoro in Impostazioni → Lingue.
La lingua predefinita del tuo spazio di lavoro.
Il widget supporta tutte le 14 lingue di UserJot (vedi Lingue). Puoi cambiarla all'inizializzazione o durante l'esecuzione senza ricaricare la pagina:
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });
// Change later at runtime
await uj.setLocale('pt-BR');