Référence du SDK
Le SDK est exposé sous la forme window.uj. Les appels sans réponse effectués via le proxy inline de préchargement (init, open, close, toggle, identify, logout, setLocale, setTheme, destroy) sont mis en file d’attente et rejoués une fois que uj.js est chargé. Les appels qui renvoient des valeurs ou des promesses (await uj.identify(...), uj.createEmbed(...), uj.on(...), uj.getState(), uj.version) nécessitent que le script du SDK soit chargé au préalable.
uj.version
La chaîne de version du SDK, par exemple 1.0.0.
uj.init(projectId, options?)
Initialise le SDK. Renvoie une promesse qui se résout avec l’état du SDK une fois le chargement terminé.
const state = await uj.init('YOUR_PROJECT_ID', {
widget: {
launcher: true, // boolean or { selector: string }
whispers: true, // default whisper behavior
notifications: { updates: 'whisper' }, // 'whisper', 'full', or 'none'
position: 'right', // 'left' or 'right'
offset: { bottom: 20 }, // corner distance in pixels: { bottom, side }
theme: 'auto' // 'auto', 'light', or 'dark'
},
locale: 'es-MX', // optional language override
pageContext: 'origin', // 'origin', 'path', or 'none'
onReady: () => {},
onError: (error) => {}
});Option | Par défaut | Description |
|---|---|---|
|
|
|
|
|
|
|
| Notifications éphémères affichées dans un toast au coin du widget. Elles sont indépendantes du bouton de lancement : elles continuent d’apparaître même si le bouton est masqué, sauf si la valeur est définie sur |
|
|
|
|
| Côté de l’écran où s’ouvre le widget. |
|
| Distance en pixels entre le lanceur et les bords de la fenêtre d’affichage. |
|
| Suivre les paramètres du système ou imposer le thème clair ou sombre. |
| navigateur → langue par défaut de l’espace de travail | Remplacement de la langue. Si cette option est omise, la langue du navigateur du visiteur est comparée aux langues activées dans votre espace de travail, puis la langue par défaut de l’espace de travail est utilisée en dernier recours. Prend en charge les 14 langues de UserJot ; les balises régionales telles que |
|
| La quantité de l’URL de la page actuelle partagée avec votre équipe dans les conversations et les visiteurs en direct. |
| Appelé lorsque le SDK est prêt. | |
| Appelé en cas d’erreur du SDK. |
La promesse renvoyée n’est pas rejetée en cas de problème réseau (vérifiez state.status === 'ready'). Elle est rejetée uniquement en cas d’erreurs de programmation, par exemple un ID de projet vide ou des options mal formées (INVALID_OPTIONS, recoverable: false).
Le mode de mise à jour complète fonctionne sans lanceur, whispers ni abonnements de l’hôte. Consultez Annonces de mise à jour pour connaître les règles précises de visibilité, de focus et de stockage des éléments consultés.
uj.ready()
Renvoie la même promesse que init. Utile lorsque le code qui a besoin du SDK est séparé de son initialisation.
const state = await uj.ready();uj.identify(input)
Identifie l’utilisateur actuel. Renvoie une promesse contenant le résultat. Voir Identifier les utilisateurs et Identité signée.
const result = await uj.identify({
token: 'OPTIONAL_JWT_FROM_YOUR_SERVER',
user: {
id: 'user-123', // required if no token is given
email: 'ada@example.com',
firstName: 'Ada',
lastName: 'Lovelace',
avatar: 'https://example.com/avatar.jpg',
traits: { plan: 'pro' }
},
companies: [
{
id: 'acme',
name: 'ACME Inc.',
domain: 'acme.com',
logo: 'https://acme.com/logo.png',
traits: { plan: 'enterprise' }
}
]
});
result.viewer; // the identified user, or null
result.identityTrust; // 'signed', 'unsigned', or null
result.warnings; // [{ code, message, field? }]viewer a la forme suivante :
{
id: 'mem_...', // UserJot's member ID, not the user.id you sent
firstName: 'Ada', // string or null
lastName: 'Lovelace', // string or null
avatar: { url: 'https://...', blurhash: '...' } // or null; blurhash optional
}Avertissements et clés de propriétés réservées
Code |
| Signification |
|---|---|---|
| La clé de l’attribut | La clé est réservée par UserJot et a été ignorée. |
| L’entreprise | L’espace de travail exige une appartenance signée à l’entreprise, mais cette entreprise ne figurait pas dans le jeton. |
|
| L’utilisateur est administrateur ou propriétaire d’un espace de travail. Ses attributs et ses entreprises s’appliquent ; son nom, son avatar et son adresse e-mail sont gérés dans le tableau de bord. |
Les clés de propriétés suivantes sont réservées et ignorées (avec émission de RESERVED_TRAIT_KEY_IGNORED) : id, externalId, external_id, email, name, firstName, first_name, lastName, last_name, avatar, avatarUrl, avatar_url, role, type, companies, company, companyId, company_id, createdAt, created_at, updatedAt, updated_at, deletedAt, deleted_at et __proto__.
Au moins un des éléments token ou user.id est requis. Rappeler identify avec la même entrée ne fait rien tant que la session est toujours active ; une fois expirée, la même entrée envoie une nouvelle requête. Une nouvelle entrée remplace la session. Si plusieurs appels se chevauchent, le dernier l’emporte. identify est la seule méthode qui rejette la promesse en cas d’erreurs à l’exécution (IDENTIFY_FAILED), et impose un délai de temporisation local après les réponses HTTP 429 (en respectant Retry-After, limité entre 1 seconde et 1 heure, et de 60 secondes par défaut).
uj.logout()
Efface l’identité actuelle et rétablit une session anonyme.
await uj.logout();uj.open(target?)
Ouvre le widget. Sans argument, le widget s’ouvre à l’endroit où l’utilisateur en était resté. La promesse est résolue lorsque le widget est visible.
await uj.open();
await uj.open({ to: 'home' });
await uj.open({ to: 'feedback' });
await uj.open({ to: 'feedback', compose: true });
await uj.open({ to: 'feedback', submissionId: 'POST_ID' });
await uj.open({ to: 'roadmap' });
await uj.open({ to: 'updates' });
await uj.open({ to: 'updates', updateId: 'UPDATE_ID' });
await uj.open({ to: 'messages' });
await uj.open({ to: 'messages', compose: { text: 'Prefilled message' } });
await uj.open({ to: 'notifications' });
await uj.open({ to: 'help' });
await uj.open({ to: 'help', article: 'ARTICLE_SLUG' });
await uj.open({ to: 'help', collection: 'COLLECTION_SLUG' });
await uj.open({ to: 'help', query: 'Search text' });La cible help accepte au plus l’un de ces paramètres : article, collection ou query. article et collection attendent le slug de l’URL ; les anciens slugs redirigent vers la page déplacée. La promesse est rejetée avec INVALID_NAVIGATION en cas de cible inconnue ou de combinaison non valide.
uj.close()
Masque le widget. Cette opération est synchrone et peut être appelée sans risque à tout moment.
uj.toggle()
Ouvre le widget s’il est fermé, et le ferme s’il est ouvert.
uj.createEmbed(options?)
Affiche une page UserJot dans un conteneur de votre page. Renvoie un contrôleur. Voir Intégrer des pages directement dans une page.
const embed = uj.createEmbed({
container: '[data-userjot-embed]',
path: '/',
basePath: '/feedback',
theme: 'auto',
onReady: () => {},
onError: (error) => {}
});
embed.navigate('/roadmap');
embed.destroy();uj.setLocale(locale)
Modifie la langue du widget à l’exécution :
await uj.setLocale('pt-BR');uj.setTheme(theme)
Modifie le thème du widget de manière synchrone ('auto', 'light' ou 'dark'). Les valeurs non valides déclenchent INVALID_OPTIONS via l’événement error. Comme init applique toujours son propre thème (avec 'auto' comme valeur par défaut), transmettez votre thème initial dans init au lieu d’appeler setTheme avant init.
uj.getState()
Renvoie un instantané en lecture seule de l’état du SDK :
{
status: 'ready', // 'idle' | 'initializing' | 'ready' | 'error' | 'destroyed'
projectId: 'proj_...',
locale: 'en-US',
unreadCount: 3, // number, or null before the first fetch
presence: 'online', // 'online' | 'neutral'
lastError: null,
widget: {
enabled: true,
open: false,
position: 'right',
theme: 'auto'
},
session: {
status: 'identified', // 'anonymous' | 'identifying' | 'identified'
identityTrust: 'signed',
viewer: { id: 'mem_...', firstName: 'Ada', lastName: 'Lovelace', avatar: null }
}
}uj.on(event, listener)
S’abonne à un événement et renvoie une fonction de désabonnement. Les écouteurs restent actifs après destroy().
Événement | Charge utile | Déclenchement |
|---|---|---|
| state | Chargement terminé. L’événement est rejoué immédiatement si le chargement est déjà terminé. |
| state | À chaque changement d’état. |
| state | Le widget est devenu visible. |
| state | 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é. L’événement est rejoué immédiatement si le SDK est déjà prêt et que les données ont été récupérées. |
|
| La disponibilité de l’équipe est passée de |
| error | Toute erreur du SDK. |
| state | Le SDK a été détruit. |
S’abonner à unread ou presence maintient les deux valeurs à jour en arrière-plan, même lorsque le lanceur par défaut est masqué.
uj.destroy(options?)
Supprime le widget, tous les éléments intégrés et la session de la page :
uj.destroy();
uj.destroy({ clearConversationData: true });clearConversationData efface également les autorisations locales de conversation anonyme, les brouillons et les coordonnées mémorisées (utile sur les appareils partagés).
Attributs DOM pour la capture de captures d’écran
Lorsqu’un utilisateur capture une capture d’écran de la page depuis le composeur de commentaires du widget (solution de repli par capture DOM), UserJot masque automatiquement les éléments du widget et masque input[type="password"], input[type="email"], input[type="tel"], input[name*="token" i] et input[name*="secret" i]. Vous pouvez également contrôler la capture sur des éléments spécifiques à l’aide d’attributs HTML :
Attribut | Effet lors de la capture d’une capture d’écran de la page |
|---|---|
| Exclut complètement l’élément de la capture d’écran. |
| Masque le contenu visible de l’élément dans la capture d’écran. |
| Masque automatiquement les champs |
Erreurs
Les erreurs ont la forme { code, message, recoverable, cause? }.
Code | Signification |
|---|---|
|
|
|
|
|
|
| Il manque à l’entrée |
| Le serveur a rejeté l’appel identify (par exemple, jeton invalide, signature manquante en mode strict, conflit |
| Le SDK n’a pas pu se charger. Vérifiez l’ID du projet, les règles CSP et le réseau. |
| Un appel a été exécuté alors que le SDK était en état d’échec. |
|
|
| Les messages sont désactivés pour cet espace de travail. Le widget ouvre la page d’accueil à la place. |
| Le centre d’aide n’est pas publié pour cet espace de travail. Le widget ouvre la page d’accueil à la place. |
| L’élément |
| L’interface du widget n’a pas pu se charger. |
| Le conteneur intégré n’existe pas. |
| Un appel a été exécuté après |
| Tout le reste. |