Référence du SDK

Shayan TaslimMis à jour

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é.

JavaScript
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

widget

true

true affiche le widget avec les paramètres par défaut. false le désactive. Un objet permet de le configurer.

widget.launcher

true

false masque le bouton par défaut. { selector } associe le widget à votre propre élément.

widget.whispers

true

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 false. Un mode de notification des mises à jour explicite remplace ce comportement pour les annonces du journal des modifications uniquement. Voir Contrôler le widget.

widget.notifications.updates

'whisper', ou 'none' lorsque whispers: false

'whisper' signale les mises à jour dans une notification toast ; 'full' ouvre la dernière nouveauté non consultée dans le lecteur du widget ; 'none' désactive les annonces de mise à jour tout en conservant le statut non lu. Les valeurs explicites remplacent whispers pour les mises à jour uniquement.

widget.position

'right'

Côté de l’écran où s’ouvre le widget.

widget.offset

{ bottom: 20, side: 20 }

Distance en pixels entre le lanceur et les bords de la fenêtre d’affichage.

widget.theme

'auto'

Suivre les paramètres du système ou imposer le thème clair ou sombre.

locale

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 es-MX sont ramenées à leur langue.

pageContext

'origin'

La quantité de l’URL de la page actuelle partagée avec votre équipe dans les conversations et les visiteurs en direct. 'origin' n’envoie que le nom d’hôte, 'path' inclut le chemin (les chaînes de requête et #fragments étant supprimées), 'none' n’envoie rien.

onReady

Appelé lorsque le SDK est prêt.

onError

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.

JavaScript
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.

JavaScript
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 :

JavaScript
{
  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

field

Signification

RESERVED_TRAIT_KEY_IGNORED

La clé de l’attribut

La clé est réservée par UserJot et a été ignorée.

UNSIGNED_COMPANY_IGNORED

L’entreprise id

L’espace de travail exige une appartenance signée à l’entreprise, mais cette entreprise ne figurait pas dans le jeton.

PRIVILEGED_PROFILE_IGNORED

firstName, lastName, avatar ou email

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.

JavaScript
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.

JavaScript
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.

JavaScript
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 :

JavaScript
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 :

JavaScript
{
  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

ready

state

Chargement terminé. L’événement est rejoué immédiatement si le chargement est déjà terminé.

statechange

state

À chaque changement d’état.

open

state

Le widget est devenu visible.

close

state

Le widget a été masqué.

identify

{ viewer, identityTrust }

L’identité a changé, y compris lors de la déconnexion.

unread

{ count }

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.

presence

{ availability }

La disponibilité de l’équipe est passée de 'online' à 'neutral', ou inversement. L’événement est rejoué immédiatement si le SDK est déjà prêt.

error

error

Toute erreur du SDK.

destroy

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 :

JavaScript
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

data-userjot-capture-ignore

Exclut complètement l’élément de la capture d’écran.

data-userjot-capture-mask

Masque le contenu visible de l’élément dans la capture d’écran.

data-userjot-sensitive

Masque automatiquement les champs <textarea> sensibles.

Erreurs

Les erreurs ont la forme { code, message, recoverable, cause? }.

Code

Signification

INVALID_PROJECT_ID

init a été appelé avec un ID de projet vide.

INVALID_OPTIONS

init, setLocale ou setTheme a reçu des options non valides.

INVALID_NAVIGATION

open a reçu une cible inconnue ou non valide.

INVALID_IDENTIFY

Il manque à l’entrée identify à la fois token et user.id.

IDENTIFY_FAILED

Le serveur a rejeté l’appel identify (par exemple, jeton invalide, signature manquante en mode strict, conflit 409, limite de débit atteinte ou membre supprimé).

BOOTSTRAP_FAILED

Le SDK n’a pas pu se charger. Vérifiez l’ID du projet, les règles CSP et le réseau.

NOT_READY

Un appel a été exécuté alors que le SDK était en état d’échec.

WIDGET_DISABLED

open a été appelé alors que le widget est désactivé.

CONVERSATIONS_DISABLED

Les messages sont désactivés pour cet espace de travail. Le widget ouvre la page d’accueil à la place.

HELP_DISABLED

Le centre d’aide n’est pas publié pour cet espace de travail. Le widget ouvre la page d’accueil à la place.

LAUNCHER_NOT_FOUND

L’élément launcher.selector n’existe pas.

SIDEBAR_LOAD_FAILED

L’interface du widget n’a pas pu se charger.

EMBED_CONTAINER_NOT_FOUND

Le conteneur intégré n’existe pas.

DESTROYED

Un appel a été exécuté après destroy().

UNKNOWN

Tout le reste.

Cet article a-t-il répondu à votre question ?