Intégrer le SDK du widget web DobroDesk

Installer le package publié

Le package navigateur est publié à l'adresse https://www.npmjs.com/package/@dobrodesk/widget/v/0.3.1. Conservez sa version dans votre lockfile et copiez l'Integration ID publique depuis Admin > Channels > Website widgets.

npm install @dobrodesk/widget@0.3.1

Configurer et présenter le widget

Après l'installation, copiez l'Integration ID publique depuis Admin > Channels > Website widgets et configurez le widget dans votre application.

Utilisez launcher: hidden lorsque votre application possède le bouton. Le launcher intégré se masque pendant l'ouverture du panneau et restitue le focus à la fermeture. Omettez l'override reduceMotion afin que le widget suive la préférence système actuelle, y compris les changements de prefers-reduced-motion en cours de session.

import { createDobroDeskWidget } from "@dobrodesk/widget";

const widget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  locale: "auto",
  launcher: "hidden",
});

await widget.ready;
widget.open();

Utiliser un déclencheur personnalisé ou une surface intégrée

Utilisez launcher: hidden lorsque votre application contrôle le déclencheur. Pour une surface intégrée, définissez une largeur et une hauteur stables avant le montage afin d'éviter les changements de mise en page pendant le chargement.

Le bouton personnalisé doit rester accessible au clavier et exposer aria-controls ainsi que aria-expanded. Lors d'un nouveau montage, réutilisez le même client, la même session et le même brouillon.

import { createDobroDeskWidget } from "@dobrodesk/widget";

const supportSlot = document.querySelector("#support-slot");
const helpButton = document.querySelector("#help-button");
if (!(supportSlot instanceof HTMLElement) || !(helpButton instanceof HTMLButtonElement)) {
  throw new Error("Support widget host elements are missing");
}

const widget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  launcher: "hidden",
  container: supportSlot,
});

helpButton.addEventListener("click", () => widget.toggle());
widget.onStateChange((state) => {
  helpButton.setAttribute("aria-expanded", String(state.visible));
});
await widget.ready;

Gérer le chargement et l'identité signée

Le frame du widget possède les indicateurs de chargement visibles par le client. Utilisez onLoadingChange pour l'état de la page, par exemple pour désactiver une action de checkout voisine. Les phases comprennent l'initialisation, le chargement du contenu et de la session, la livraison du message, l'attente de l'assistant, l'exécution d'une action et la reconnexion.

Les sessions web anonymes sont prises en charge. Pour un client signé, votre backend doit émettre un JWT d'identité HS256 de courte durée et le navigateur peut l'envoyer avec l'adresse e-mail connue. Ne placez jamais le signing secret ni un support API token dans le code navigateur. Appelez logout avant la fin de la session authentifiée de l'hôte ou avant qu'un autre client utilise le navigateur.

const stopLoading = widget.onLoadingChange((loading) => {
  checkoutButton.disabled = loading.active;
});

// The token is returned by your backend. This function belongs to your app.
widget.setIdentityToken(await loadIdentityTokenFromYourBackend());
widget.prefill({ email: currentUser.email, name: currentUser.name });

Gérer le chargement, la visibilité et l'accessibilité

Utilisez les hooks de chargement ou les événements typés pour l'état de l'écran hôte. La surface affiche elle-même le chargement des messages, l'attente et les nouvelles tentatives afin d'éviter un second indicateur sur le champ de saisie.

Masquez ou affichez la surface lors d'une navigation temporaire en conservant le client. Le widget respecte les préférences système de réduction des mouvements. Le retrait ou la fermeture ne supprime ni la session ni le brouillon.

1. Lors du nouveau montage, réutilisez le même client et des dimensions stables pour le conteneur.
2. Utilisez la fonction de visibilité pour un masquage temporaire, sans réinitialiser la session.
3. Terminez la session uniquement lors de la déconnexion ou d'un changement de compte volontaire.

Vérifier l'intégration

1. Ouvrez la page depuis un origin autorisé et vérifiez que le panneau s'ouvre une seule fois et que le launcher masqué reste masqué.
2. Envoyez un message de test depuis une session privée du navigateur, puis confirmez qu'il atteint l'Inbox configurée sans créer de seconde conversation.
3. Désactivez brièvement le réseau et attendez l'état de reconnexion du widget. Laissez le frame réessayer son opération en attente. Ne soumettez pas le même message depuis un second contrôle tant que la première requête n'a pas de résultat.
4. Modifiez le réglage système de réduction des mouvements lorsque le widget est ouvert et vérifiez que les transitions suivantes respectent la nouvelle préférence.