Headless-Web-SDK – Leitfaden

Mit dem Headless Web SDK können Sie den Support für Ihr Unternehmen flexibel erweitern und anpassen. Es enthält alle bekannten Web-SDK-Funktionen und bietet die Möglichkeit, die Benutzeroberfläche und ‑freundlichkeit entsprechend zu gestalten.

Für die Installation und Verwendung des Headless Web SDK ist die Unterstützung durch das Webentwicklungsteam Ihrer Organisation erforderlich. Für eine erfolgreiche Integration und optimale Leistung empfiehlt Google, dass Sie Ihr qualifiziertes Personal einbeziehen.

Im Kontext der Softwareentwicklung bezieht sich „headless“ auf eine entkoppelte Architektur, bei der die Frontend-Präsentationsschicht (der „Head“) von der Backend-Logik und den Backend-Funktionen getrennt ist. In einer Headless-Architektur stellt das Backend, auch als „Headless“-Teil bezeichnet, APIs bereit, mit denen Sie seine Funktionen und Dienste nutzen können.

Ein Beispiel ist die benutzerdefinierte Workflow-Automatisierung. Wenn ein Endnutzer einen Chat startet, wird das Ereignis on("chat.message") ausgelöst. Sie können benutzerdefinierte Automatisierungsauslöser auf Grundlage bestimmter Chatnachrichten definieren, die Sie erhalten haben. Wenn ein Endnutzer beispielsweise „Escalate“ in den Chat eingibt, kann der Ereignishandler die Chatsitzung automatisch an ein Supportteam der höheren Ebene eskalieren, sodass kritische Probleme schnell behoben werden können.

In diesem Leitfaden werden die Installation, die Integrationsmöglichkeiten und die Verwendung des SDK beschrieben. Weitere Informationen zur Verwendung der API finden Sie in der API-Dokumentation zum Headless Web SDK. Eine Liste der verfügbaren Events finden Sie auf der Seite „Events“.

Headless Web SDK installieren

Verwenden Sie das folgende Code-Snippet in Ihrem Projekt, um das Headless Web SDK zu installieren:

npm install @ujet/websdk-headless --save

Headless Web-SDK verwenden

Wenn Sie das Headless Web SDK verwenden möchten, können Sie dem bereitgestellten Beispielcode folgen:

import { Client } from "@ujet/websdk-headless"
const client = new Client({ ... })

async function authenticate() {
  const resp = await fetch("/your-auth-endpoint")
  const data = await resp.json()
  return { token: data.token }
}

const client = new Client({
  companyId: "YOUR-COMPANY-ID",
  tenant: "YOUR-TENANT-NAME",
  authenticate: authenticate,
})

// const company = await client.getCompany()
// const menus = await client.getMenus()

Die Client-Klasse akzeptiert mehrere Optionen, die Sie an Ihre Anforderungen anpassen können:

interface ClientOption {
  companyId: string;
  authenticate: () => Promise<TokenResponse>;
  tenant?: string;
  host?: string;
  lang?: string;
  bridge?: string;
  cobrowse?: {
    enabled: boolean;
    messages?: CobrowseMessages;
    api?: string;
    license?: string;
    trustedOrigins?: string[];
    capabilities?: string[];
    registration?: boolean;
    redactedViews?: string[];
    unredactedViews?: string[];
  };
}

Logging aktivieren

Während der Implementierung und des Testens kann es erforderlich sein, zusätzliche Informationen im Konsolenprotokoll zu erfassen. Wenn Sie die Protokollierung für das Headless SDK aktivieren möchten, importieren Sie Logger und consoleLoggerHandler, indem Sie Ihrer Webanwendung den folgenden Code hinzufügen:

import {Logger, consoleLoggerHandler } from '@ujet/websdk-headless'
Logger.addHandler(consoleLoggerHandler)

Sie können die Bildschirmfreigabe mit dem Headless Web SDK aktivieren und konfigurieren.

Das folgende Codebeispiel zeigt, wie Sie die Bildschirmfreigabe aktivieren:

new Client({
  // ...
  cobrowse: {
    enabled: true,
    license: 'YOUR_SCREEN_SHARE_LICENSE'
  }
})

Das folgende Codebeispiel zeigt die Optionen für die Bildschirmfreigabe:

interface CobrowseOption {
  enabled: boolean
  template?: string
  confirmSessionTemplate?: string
  confirmRemoteControlTemplate?: string
  confirmFullDeviceTemplate?: string
  sessionControlsTemplate?: string
  root?: Element
  messages?: {
    confirmSessionTitle: string;
    confirmSessionContent: string;
    confirmRemoteControlTitle: string;
    confirmRemoteControlContent: string;
    confirmFullDeviceTitle: string;
    confirmFullDeviceContent: string;
    allowText: string;
    denyText: string;
    endSessionText: string;
  }
  api?: string
  license?: string
  trustedOrigins?: string[]
  capabilities?: string[]
  registration?: boolean
  redactedViews?: string[]
  unredactedViews?: string[]
}

Benutzerdefinierte Vorlage

Sie können die Vorlage für das Dialogfeld „Bildschirmfreigabe“ mit der Option template aus dem vorherigen Codebeispiel anpassen.

Das folgende Beispiel zeigt die Standardvorlage:

<dialog open class="cobrowse-dialog">
  <h1>$title</h1>
  <div class="cobrowse-dialog_content">$content</div>
  <div class="cobrowse-dialog_footer">
    <button class="cobrowse-dialog_allow js-cobrowse-allow">$allow</button>
    <button class="cobrowse-dialog_deny js-cobrowse-deny">$deny</button>
  </div>
</dialog>

Mit dieser Vorlage können Sie ein Dialogfeld konfigurieren, in dem der Endnutzer um Genehmigung für Folgendes gebeten wird:

Bildschirmfreigabe starten
Bildschirmfreigabe mit Fernsteuerung starten
Bildschirmfreigabe für das gesamte Gerät starten

Folgende Vorlagenoptionen sind verfügbar:

confirmSessionTemplate: Zum Bestätigen einer Bildschirmfreigabesitzung.
confirmRemoteControlTemplate: Zum Bestätigen einer Screen Share-Sitzung mit Fernbedienung.
confirmFullDeviceTemplate. Zum Bestätigen einer Bildschirmfreigabesitzung für das gesamte Gerät.
sessionControlsTemplate: Für die Schaltfläche „Sitzungssteuerung“. Hier ist die Standardvorlage: <button class="cobrowse-end js-cobrowse-end">$end</button>

Nachrichten

Die folgenden Nachrichtenvariablen werden in benutzerdefinierten Vorlagen verwendet:

$title
$content
$allow
$deny

Im folgenden Beispiel sehen Sie, wie diese Variablen angewendet werden:

{
  confirmSessionTitle: string;  // $title
  confirmSessionContent: string;  // $content
  confirmRemoteControlTitle: string;  // $title
  confirmRemoteControlContent: string;  // $content
  confirmFullDeviceTitle: string;  // $title
  confirmFullDeviceContent: string;  // $content
  allowText: string;  // $allow
  denyText: string;  // $deny
  endSessionText: string;  // $end
}

Im folgenden Beispiel sehen Sie die englischen Standardwerte für Variablen:

{
  "confirmSessionTitle": "Screen Share Session Request",
  "confirmSessionContent": "Do you want to share your current screen with the agent?",
  "endSessionText": "End Screen Share Session",
  "confirmRemoteControlTitle": "Remote Access Request",
  "confirmRemoteControlContent": "The agent would like to have access to your currently shared screen to further assist you. Do you want to allow this?",
  "confirmFullDeviceTitle": "Screen Share Request",
  "confirmFullDeviceContent": "Do you want to share your full screen with the agent? The agent will not be able to control anything on the screen.",
  "allowText": "Allow",
  "denyText": "Deny"
}

Benutzerdefinierte Datenkonfiguration

Mit der Option „custom_data“ können Sie beliebige Schlüssel/Wert-Paare an das Web-SDK übergeben.

Nutzung

Sie können beim Erstellen eines Chats benutzerdefinierte Daten als Objekt (nicht signiert) oder als String (signiert) angeben:

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

Sehen Sie sich folgendes Beispiel an:

const custom_data = {
  unsigned: {
    version: {
      label: 'Version',
      value: '1.0.0'
    }
  },
  signed: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' // JWT or other signed payload
}

try {
  const chat: Chat = await client.createChat(123, { custom_data })
} catch (error) {
  // handle error
}

Weiterleitung an externen Chatbot

In einigen Fällen möchten Sie möglicherweise den Verlauf und die Interaktionen von anderen Chatanbietern beibehalten. Dazu können Sie custom_data object verwenden.