Contrôler le widget
Vous pouvez contrôler le widget par programmation depuis votre propre interface : ouvrir des sections spécifiques, réagir aux événements, configurer les annonces de mises à jour ou remplacer entièrement le lanceur par défaut.
Ouvrir le widget
Appeler uj.open() sans argument ouvre le widget là où l’utilisateur l’a laissé :
uj.open();Indiquez une cible pour ouvrir une section spécifique :
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' });Options de liens profonds pour des cibles spécifiques :
// 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' });Masquez ou affichez le widget à tout moment :
uj.close();
uj.toggle();La cible messages nécessite que Conversations soit activé ; sinon, elle renvoie CONVERSATIONS_DISABLED via l’événement error et ouvre l’accueil. La cible help nécessite que votre centre d’aide soit en ligne (article et collection utilisent le slug de l’URL) ; sinon, elle renvoie HELP_DISABLED et ouvre l’accueil.
Écouter les événements
Abonnez-vous avec uj.on(event, listener), qui renvoie une fonction de désabonnement :
const unsubscribe = uj.on('open', () => {
console.log('widget opened');
});
unsubscribe();Événement | Déclenchement |
|---|---|
| Le SDK a fini de se charger. Se déclenche immédiatement s’il est déjà chargé. |
| Le widget est devenu visible. |
| Le widget a été masqué. |
| L’identité a changé, y compris lors de la déconnexion. |
| Le nombre d’éléments non lus a changé. La charge utile est |
| La disponibilité de l’équipe a changé. La charge utile est |
| Une partie quelconque de l’état du widget a changé. |
| Une erreur s’est produite. La charge utile est l’objet d’erreur. |
Lire l’état
uj.getState() renvoie un instantané de l’état actuel du 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 nullCréer votre propre lanceur
Masquez le lanceur par défaut pour piloter le widget depuis un élément de navigation ou un bouton de votre choix :
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: false }
});Masquer le lanceur supprime le bouton par défaut tout en laissant actives les notifications discrètes dans le coin (voir la section Notifications discrètes ci-dessous pour les décaler ou les désactiver).
Configurez votre bouton, votre badge d’éléments non lus et, en option, un indicateur de disponibilité de l’équipe :
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' signifie que le SDK ne peut pas confirmer qu’un opérateur est actuellement en ligne ; masquez donc l’indicateur au lieu d’afficher une étiquette « hors ligne ». Lorsque le widget est fermé, la présence est actualisée au chargement de la page, lorsque l’onglet reprend le focus et toutes les quelques minutes ; lorsque le widget est ouvert, elle est mise à jour en temps réel.
Dans le lanceur par défaut, l’indicateur de non-lus a priorité sur la pastille verte de présence en ligne. Le nombre d’éléments non lus regroupe les réponses aux conversations, les publications du journal des modifications et les notifications de commentaires. Lorsque des éléments non lus sont en attente, cliquer sur le lanceur par défaut redirige, par ordre de priorité, vers Messages (réponses non lues aux conversations), puis vers Notifications (notifications de commentaires non consultées), puis vers la dernière Mise à jour non consultée.
Pour associer directement le comportement du lanceur par défaut à un élément existant de votre page, indiquez un sélecteur CSS :
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: { selector: '#feedback-button' } }
});Notifications discrètes
Les notifications furtives sont de brèves notifications cliquables qui apparaissent dans un coin pour signaler les réponses non lues aux conversations de l’équipe, les notifications de commentaires et les nouvelles publications du journal des modifications. Elles sont affichées dans cet ordre de priorité : d’abord les réponses non lues aux conversations, puis les notifications de commentaires et de réponses, puis les autres notifications, et enfin les mises à jour du journal des modifications. Pour protéger la confidentialité, les notifications furtives de conversation affichent uniquement l’avatar du coéquipier et <Name> replied (jamais le texte du message) ; cliquer dessus ouvre Messages.
Fraîcheur et temporisation : seules les activités créées ou publiées au cours des 14 derniers jours déclenchent une notification furtive. Le widget attend une activité réelle de l’utilisateur, 4 secondes sur la page, 1,2 seconde d’inactivité et au moins 30 secondes depuis la notification furtive précédente. Les notifications furtives n’interrompent jamais l’utilisateur lorsqu’il saisit du texte dans un champ de saisie, une zone de texte, une liste déroulante ou un champ modifiable, ni dans les navigateurs automatisés.
Limites de répétition et délais de relance : chaque élément peut déclencher au maximum 3 notifications considérées comme diffusées (une visibilité attentive de 1,5 seconde étant nécessaire pour qu’une notification soit considérée comme diffusée), avec des délais de relance de 30 minutes, 24 heures et 3 jours pour les mises à jour, ou de 30 minutes, 1 heure et 24 heures pour les notifications et les réponses aux conversations.
Avec ou sans le lanceur par défaut : les notifications furtives sont indépendantes du lanceur. Avec le lanceur par défaut, elles se déploient depuis le bouton ; avec
launcher: falseou un lanceur basé sur un sélecteur, elles apparaissent seules dans un coin et, après expiration, se replient en un cercle cliquable qui reste visible pendant 60 secondes avant de disparaître.
Déplacez les notifications discrètes pour les éloigner de votre interface avec offset :
uj.init('YOUR_PROJECT_ID', {
widget: {
launcher: false,
offset: { bottom: 84 } // pixels from the bottom edge; `side` works too
}
});Vous pouvez aussi désactiver complètement les notifications furtives (pour les conversations, les commentaires et les mises à jour par défaut) :
uj.init('YOUR_PROJECT_ID', {
widget: { launcher: false, whispers: false }
});Lorsque les deux sont désactivés et qu’aucun mode de mise à jour n’est spécifié, le widget n’affiche rien jusqu’à ce que vous appeliez uj.open(), tandis que les abonnements unread et presence continuent d’être actualisés en arrière-plan.
Annonces de mise à jour
Contrôlez la façon dont le widget annonce la dernière entrée du journal des modifications qui n’a pas encore été vue avec widget.notifications.updates :
uj.init('YOUR_PROJECT_ID', {
widget: {
notifications: { updates: 'full' }
}
});Mode | Comportement |
|---|---|
| Annonce la mise à jour dans une notification affichée dans un coin, avec une limite de répétitions. |
| Ouvre directement la mise à jour dans le lecteur du widget, avec son image de couverture et l’intégralité de son contenu. |
| Désactive les annonces de mise à jour tout en laissant actifs l’onglet Mises à jour et le badge d’éléments non lus. |
Si cette option est omise, les mises à jour sont définies par défaut sur 'whisper' (ou sur 'none' lorsque whispers: false). La définition explicite de widget.notifications.updates remplace whispers uniquement pour les mises à jour du journal des modifications ; les notifications furtives de conversation et de commentaires continuent de suivre whispers.
Le mode complet fonctionne même si le lanceur est masqué et qu’aucun écouteur d’événements n’est configuré. Lors d’une première visite, le mode complet peut ouvrir la dernière mise à jour publiée, même si elle est plus ancienne. Le SDK tente au maximum une ouverture automatique par visite d’initialisation (une ouverture manuelle, une bascule, une fermeture ou une tentative échouée consomme cette possibilité ; recharger la page ou appeler init() démarre une nouvelle visite, contrairement aux changements d’identité ou à la navigation dans une SPA). L’ouverture automatique nécessite que la page soit visible et ait le focus, et que le widget soit fermé ; elle est désactivée lorsque widget: false.
Une mise à jour est marquée comme vue dès que son contenu s’affiche dans le widget ouvert sur une page visible qui a le focus. L’état « vue » est stocké localement dans le navigateur pour chaque projet et origine. Les mises à jour sont détectées à l’initialisation, lorsque l’onglet reprend le focus et environ toutes les cinq minutes lorsque le widget est fermé.
Changer de langue
Si locale est omis, le widget choisit une langue dans l’ordre suivant :
Une option
localeexplicite transmise àuj.init(...)ouuj.setLocale(...).La langue du navigateur du visiteur, si elle correspond à l’une des langues activées dans votre espace de travail sous Paramètres → Langues.
La langue par défaut de votre espace de travail.
Le widget prend en charge les 14 langues de UserJot (voir Langues). Remplacez la langue à l’initialisation ou à l’exécution, sans recharger la page :
uj.init('YOUR_PROJECT_ID', { locale: 'es-MX' });
// Change later at runtime
await uj.setLocale('pt-BR');