DobroDesk-Widget programmatisch initialisieren

Programmatische Installation für Websites mit Anwendungscode wählen

Verwenden Sie das programmatische SDK, wenn die Website als Anwendung entwickelt ist und das Widget erst nach Einwilligung, Anmeldung, Routenauswahl oder einem anderen Anwendungsereignis starten soll. Für Website-Baukästen und websiteweite Felder für benutzerdefinierten Code bleibt die normale Skripteinbettung einfacher.

Beide Methoden laden dasselbe gehostete DobroDesk-Widget. Das SDK erstellt keine zweite Widget-Implementierung. Es übergibt Integration ID und Sprache an den Loader und stellt anschließend typisierte Methoden zur Steuerung der Instanz bereit.

• Verwenden Sie die Skripteinbettung, wenn die Support-Schaltfläche ohne Anwendungslogik auf jeder öffentlichen Seite geladen werden soll.
• Verwenden Sie das SDK, wenn die Initialisierung vom Anwendungszustand abhängt oder eine eigene Schaltfläche das Widget öffnen soll.
• Initialisieren Sie das Widget einmal pro Seite. Behalten Sie den zurückgegebenen Client, statt createDobroDeskWidget erneut aufzurufen.
• Initialisieren Sie im Browser. Beim Server-Rendering stehen document und window nicht zur Verfügung.

Paket installieren

Fügen Sie das DobroDesk-Widget-Paket mit dem bereits im Projekt verwendeten Paketmanager zur Frontend-Anwendung hinzu.

npm install @dobrodesk/widget

Eine Widget-Instanz initialisieren

1. 1

   Kopieren Sie die Integration ID aus Admin > Channels > Website widgets.

   

2. 2

   Importieren Sie createDobroDeskWidget in den browserseitigen Anwendungscode.

3. 3

   Übergeben Sie die genaue Integration ID und wählen Sie auto, en oder uk.

4. 4

   Speichern Sie den zurückgegebenen Client und warten Sie mit await client.ready, bevor Sie Logik ausführen, die eine erfolgreich geladene Konfiguration voraussetzt.

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

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

await supportWidget.ready;

Gehostetes ES-Modul ohne Paketmanager verwenden

Eine Browseranwendung mit ES-Modul-Unterstützung kann dasselbe SDK direkt importieren. Das eignet sich für kleine individuelle Websites mit JavaScript-Modulen, aber ohne npm-Build-Schritt.

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

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

Widget über Anwendungsaktionen steuern

Bewahren Sie den Client in dem Modul oder der Komponente auf, die den Supportbereich steuert. Wenn eine eigene Hilfe- oder Support-Schaltfläche das Widget öffnet, initialisieren Sie es mit launcher: hidden, damit daneben keine Standard-Schaltfläche erscheint. Nach der Initialisierung kann die Einwilligungslogik die Launcher-Sichtbarkeit steuern und prefill bereits bekannte Kundendaten übernehmen.

• open, close und toggle ändern den Zustand des Panels.
• hide entfernt das Widget aus der Bedienung; show macht es wieder verfügbar.
• setLauncherVisibility blendet nur den Standard-Launcher aus oder ein, ohne den Widget-Client zu zerstören.
• prefill ergänzt die übergebenen Werte für Name, E-Mail, Betreff, Nachricht oder konfigurierte benutzerdefinierte Felder.
• setLocale lädt en oder uk und verwendet für jede andere Sprache Englisch.
• destroy entfernt die Widget-Instanz dauerhaft von der aktuellen Seite.

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

Angemeldete Kunden mit einem kurzlebigen JWT sicher identifizieren

Verwenden Sie eine signierte Kundenidentität, wenn Ihre Anwendung den angemeldeten Kunden bereits kennt. DobroDesk prüft die Kunden-ID und optional die bestätigte E-Mail-Adresse, bevor Gesprächsverlauf oder CRM-Kontext verknüpft werden. Das Identitätsgeheimnis gehört ausschließlich in den Secret Manager des Backends.

Wählen Sie in den Widget-Einstellungen Require a signed logged-in user, speichern Sie das Widget und klicken Sie auf Copy identity secret. Speichern Sie den Wert als DOBRODESK_WIDGET_IDENTITY_SECRET im Backend. Die öffentliche Integration ID darf im Browser stehen, das Identitätsgeheimnis nicht.

1. 1

   Installieren Sie im Backend eine gepflegte JWT-Bibliothek wie jose.

2. 2

   Signieren Sie mit HS256, dem Issuer dobrodesk-widget:{Integration ID}, der Integration ID als Audience und Ihrer stabilen internen Benutzer-ID als Subject.

3. 3

   Verwenden Sie fünf Minuten Gültigkeit und niemals mehr als 15 Minuten. Erstellen Sie beim Laden der Seite oder bei der Anmeldung ein neues Token.

4. 4

   Fügen Sie email und email_verified: true nur hinzu, wenn Ihre Anwendung den Besitz der Adresse bereits bestätigt hat.

5. 5

   Geben Sie das Token über einen authentifizierten Backend-Endpunkt zurück und übergeben Sie es beim Erstellen des Widgets als identityToken.

• sub ist die stabile Benutzer-ID Ihrer Anwendung und keine E-Mail-Adresse.
• email_verified: false oder ein fehlender Wert macht die E-Mail-Adresse nicht vertrauenswürdig.
• Steht die E-Mail-Adresse in identityToken oder prefill.email, zeigt das Widget kein zweites E-Mail-Feld.
• Eine unsignierte vorausgefüllte oder eingegebene E-Mail-Adresse bleibt unbestätigt, bis der Kunde den einmaligen Bestätigungslink öffnet.
• Erfolgt die Anmeldung später, rufen Sie setIdentityToken(token) und danach prefill({ email, name }) auf.
• Rufen Sie vor der Abmeldung in Ihrer Anwendung logout() auf, damit die nächste Person im Browser nicht die vorherige Unterhaltung übernimmt.

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

Anwendungsintegration prüfen

1. 1

   Laden Sie die Anwendungsroute, die das SDK initialisiert, und prüfen Sie, ob nur die beabsichtigte Standard- oder eigene Support-Schaltfläche erscheint.

2. 2

   Lösen Sie die eigene Aktion aus, die open aufruft, und prüfen Sie, ob sich das Panel ohne Neuladen der Seite öffnet.

3. 3

   Testen Sie jedes vorausgefüllte Feld mit einem nicht sensiblen Beispielwert. Geben Sie keine Zahlungsdaten, Passwörter oder privaten Token in Widget-Felder ein.

4. 4

   Wechseln Sie zwischen auto, en und uk und prüfen Sie Schaltfläche, Formulartexte und vorgeschlagene Antworten.

5. 5

   Senden Sie eine vollständige Testnachricht und prüfen Sie, ob sie den konfigurierten DobroDesk-Posteingang erreicht.