Das DobroDesk Web-Widget-SDK integrieren

Veröffentlichtes Paket installieren

Das Browserpaket ist unter https://www.npmjs.com/package/@dobrodesk/widget/v/0.3.1 veröffentlicht. Halten Sie die Paketversion in Ihrer Lockdatei fest und kopieren Sie die öffentliche Integration ID aus Admin > Channels > Website widgets.

npm install @dobrodesk/widget@0.3.1

Widget konfigurieren und anzeigen

Kopieren Sie nach der Installation die öffentliche Integration ID unter Admin > Channels > Website widgets und konfigurieren Sie das Widget in Ihrer Anwendung.

Verwenden Sie launcher: hidden, wenn Ihre Anwendung die Schaltfläche besitzt. Der eingebaute Launcher wird ausgeblendet, solange das Panel offen ist, und stellt den Fokus beim Schließen wieder her. Lassen Sie einen reduceMotion-Override weg, damit das Widget der aktuellen Systemeinstellung der Besucherin oder des Besuchers folgt, einschließlich laufender prefers-reduced-motion-Änderungen.

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

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

await widget.ready;
widget.open();

Eigenen Trigger oder Inline-Fläche verwenden

Verwenden Sie launcher: hidden, wenn Ihre Anwendung den Trigger besitzt. Für eine Inline-Fläche braucht der Host vor dem Mounten feste Breite und Höhe, damit sich das Layout beim Laden nicht verschiebt.

Der eigene Button bleibt per Tastatur erreichbar und erhält aria-controls sowie aria-expanded. Verwenden Sie beim erneuten Mounten denselben Client, dieselbe Sitzung und denselben Entwurf.

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;

Laden und signierte Identität behandeln

Der Widget-Frame besitzt die kunden sichtbaren Ladeanzeigen. Verwenden Sie onLoadingChange für den Seitenzustand, etwa um eine umgebende Checkout-Aktion zu deaktivieren. Die Phasen umfassen Initialisierung, Laden von Inhalt und Sitzung, Nachrichtenzustellung, Warten auf den Assistenten, Aktionsausführung und Wiederverbinden.

Anonyme Websitzungen werden unterstützt. Für eine signierte Kundin oder einen signierten Kunden muss Ihr Backend ein kurzlebiges HS256-Identitäts-JWT ausstellen. Der Browser kann es mit der bekannten E-Mail-Adresse senden. Legen Sie das Signier-Geheimnis oder ein Support-API-Token niemals in Browsercode. Rufen Sie logout auf, bevor die authentifizierte Host-Sitzung endet oder eine andere Person den Browser verwendet.

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 });

Laden, Sichtbarkeit und Barrierefreiheit behandeln

Nutzen Sie Loading-Hooks oder typisierte Events für den Ladezustand des Hosts. Die Oberfläche zeigt Nachrichtenladen, Warten und Wiederholungen selbst an, damit kein zweiter Spinner das Eingabefeld überlagert.

Verbergen oder zeigen Sie die Oberfläche bei einer vorübergehenden Navigation und behalten Sie den Client. Das Widget respektiert die Systemoptionen für reduzierte Bewegung. Ein Entfernen oder Schließen verwirft weder Sitzung noch Entwurf.

1. Verwenden Sie beim erneuten Mounten denselben Client und feste Host-Abmessungen.
2. Verwenden Sie die Sichtbarkeitsfunktion für vorübergehendes Ausblenden und keine Session-Reset-Funktion.
3. Beenden Sie die Sitzung erst bei Logout oder einem bewussten Kontowechsel.

Integration prüfen

1. Öffnen Sie die Seite von einem erlaubten Origin und prüfen Sie, dass sich das Panel einmal öffnet und der versteckte Launcher verborgen bleibt.
2. Senden Sie aus einer privaten Browsersitzung eine Testnachricht und prüfen Sie anschließend, dass sie den konfigurierten Posteingang erreicht, ohne eine zweite Unterhaltung zu erzeugen.
3. Deaktivieren Sie kurz das Netzwerk und warten Sie auf den Zustand Wiederverbinden des Widgets. Lassen Sie den Frame seine ausstehende Operation selbst wiederholen. Senden Sie dieselbe Kundennachricht nicht über eine zweite Steuerung, solange die erste Anfrage kein Ergebnis hat.
4. Ändern Sie die Systemoption für reduzierte Bewegung bei geöffnetem Widget und prüfen Sie, dass spätere Übergänge die neue Einstellung beachten.