Initialiser le widget DobroDesk par le code

Choisir l'installation par code lorsque le site possède du code applicatif

Utilisez le SDK par code lorsque le site est une application et que le widget doit démarrer après un consentement, une authentification, une sélection de routage ou un autre événement applicatif. L'intégration par script standard reste l'option la plus simple pour un constructeur de site ou un champ de code personnalisé appliqué à l'ensemble du site.

Les deux méthodes chargent le même widget hébergé par DobroDesk. Le SDK ne crée pas une seconde implémentation du widget. Il fournit l'ID d'intégration et la locale au chargeur, puis expose des méthodes typées pour contrôler l'instance obtenue.

• Utilisez l'intégration par script lorsque le bouton Contacter l'assistance doit se charger sur toutes les pages publiques sans logique applicative.
• Utilisez le SDK lorsque l'initialisation dépend de l'état de l'application ou lorsqu'un bouton personnalisé doit ouvrir le widget.
• Initialisez le widget une seule fois par page. Conservez le client retourné au lieu d'appeler à nouveau createDobroDeskWidget.
• Exécutez l'initialisation dans le navigateur. Le rendu côté serveur ne fournit ni document ni window.

Installer le package

Ajoutez le package du widget DobroDesk à l'application frontend avec le gestionnaire de paquets déjà utilisé par le projet.

npm install @dobrodesk/widget

Initialiser une seule instance du widget

1. 1

   Copiez l'ID d'intégration dans Administration > Canaux > Widgets du site.

   

2. 2

   Importez createDobroDeskWidget dans le code de l'application exécuté dans le navigateur.

3. 3

   Passez l'ID d'intégration exact à l'option integrationId et choisissez auto, en, uk, de, es, fr ou pt.

4. 4

   Stockez le client retourné et attendez client.ready avant d'exécuter une logique qui dépend du chargement réussi de la configuration.

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

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "auto",
});

await supportWidget.ready;

Utiliser le module ES hébergé sans gestionnaire de paquets

Une application navigateur compatible avec les modules ES peut importer directement le même SDK. C'est utile pour un petit site utilisant des modules JavaScript sans étape de build npm.

import { createDobroDeskWidget } from "https://widget.dobrodesk.com/widget/sdk/v1.js";

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "en",
  openOnReady: false,
});

Contrôler le widget depuis les actions de l'application

Conservez le client dans le module ou le composant qui contrôle l'expérience d'assistance. Lorsque votre propre bouton Aide ou Assistance ouvre le widget, initialisez-le avec launcher: hidden afin que le lanceur par défaut n'apparaisse pas à côté. La logique de consentement peut contrôler la visibilité du lanceur après l'initialisation. Le préremplissage initial peut fournir les champs déjà connus par votre application.

• open, close et toggle modifient l'état du panneau.
• hide retire le widget de l'interaction, tandis que show le rend à nouveau disponible.
• setLauncherVisibility masque ou affiche uniquement le lanceur par défaut, sans détruire le client du widget.
• prefill combine les champs fournis de nom, e-mail, objet, message ou champs personnalisés configurés.
• setLocale charge en, uk, de, es, fr ou pt et utilise l'anglais pour toute autre locale.
• destroy supprime définitivement l'instance du widget de la page actuelle.

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

await supportWidget.ready;

// Your application button
supportWidget.open();

// Consent or route state
supportWidget.setLauncherVisibility(false);
supportWidget.setLauncherVisibility(true);

supportWidget.close();
supportWidget.toggle();
supportWidget.hide();
supportWidget.show();

supportWidget.prefill({
  email: "customer@example.com",
  subject: "Question about order 1042",
});

supportWidget.setLocale("uk");

Identifier les clients connectés avec un JWT de courte durée

Utilisez une identité client signée lorsque votre application connaît déjà le client connecté. DobroDesk vérifie l'ID client et, si nécessaire, l'e-mail vérifié avant d'associer l'historique des conversations ou d'exposer le contexte CRM. Le secret d'identité doit rester uniquement dans le gestionnaire de secrets du backend.

Dans les réglages du widget, choisissez Exiger un utilisateur connecté et signé, enregistrez le widget, puis choisissez Copier le secret d'identité. Stockez cette valeur comme DOBRODESK_WIDGET_IDENTITY_SECRET dans le backend. L'ID d'intégration public peut rester dans le code navigateur. Le secret d'identité, lui, ne doit pas y figurer.

1. 1

   Installez dans le backend une bibliothèque JWT maintenue, comme jose.

2. 2

   Signez avec HS256 en utilisant l'issuer dobrodesk-widget:{Integration ID}, l'audience égale à l'ID d'intégration et le subject égal à l'ID interne stable de l'utilisateur.

3. 3

   Utilisez une durée de validité de cinq minutes, jamais supérieure à 15 minutes. Créez un nouveau token au chargement de la page ou à la connexion de l'utilisateur.

4. 4

   N'incluez email et email_verified: true qu'après confirmation par votre application de la propriété de cette adresse.

5. 5

   Retournez le token par l'endpoint backend authentifié et transmettez-le à identityToken lors de la création du widget.

• sub est l'ID stable de l'utilisateur dans votre application, pas une adresse e-mail.
• email_verified: false ou une valeur omise ne rend pas l'adresse e-mail fiable.
• Lorsque l'e-mail figure dans identityToken ou prefill.email, le widget n'affiche pas un autre champ e-mail.
• Un e-mail prérempli ou saisi sans signature reste non vérifié jusqu'à la confirmation par le client du lien e-mail à usage unique.
• Si la connexion intervient après l'initialisation, appelez setIdentityToken(token) et prefill({ email, name }).
• Avant que votre application déconnecte le client, appelez logout() afin qu'une autre personne utilisant le navigateur n'hérite pas de la conversation précédente.

import { SignJWT } from "jose";

const integrationId = process.env.DOBRODESK_WIDGET_ID;
const identitySecret = new TextEncoder().encode(
  process.env.DOBRODESK_WIDGET_IDENTITY_SECRET,
);

export const createWidgetIdentityToken = (user) =>
  new SignJWT({
    name: user.name,
    email: user.email,
    email_verified: true,
  })
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setIssuer(`dobrodesk-widget:${integrationId}`)
    .setAudience(integrationId)
    .setSubject(user.id)
    .setIssuedAt()
    .setExpirationTime("5m")
    .sign(identitySecret);

// Browser code after your authenticated endpoint returns the token
const supportWidget = createDobroDeskWidget({
  integrationId,
  identityToken,
  prefill: { email: currentUser.email, name: currentUser.name },
});

Vérifier l'intégration de l'application

1. 1

   Chargez la route de l'application qui initialise le SDK et vérifiez que seul le bouton Contacter l'assistance standard ou personnalisé prévu apparaît.

   

2. 2

   Déclenchez l'action personnalisée qui appelle open et vérifiez que le panneau s'ouvre sans recharger la page.

   

3. 3

   Testez chaque champ prérempli avec une valeur d'exemple non sensible. Ne placez pas de données de paiement, de mots de passe ou de jetons privés dans les champs du widget.

4. 4

   Basculez entre auto, en, uk, de, es, fr et pt et vérifiez le lanceur, les libellés du formulaire et les réponses suggérées.

5. 5

   Envoyez un message de test complet et vérifiez qu'il arrive dans la boîte de réception DobroDesk configurée.