Guide pour le SDK Web headless

Le SDK Web sans interface utilisateur vous permet d'étendre et de personnaliser l'expérience d'assistance de votre entreprise selon vos besoins. Il contient toutes les fonctionnalités habituelles de nos SDK Web et vous permet de créer l'UI et l'expérience utilisateur associées.

L'installation et l'utilisation du SDK Web sans interface utilisateur nécessitent l'aide de l'équipe de développement Web de votre organisation. Pour réussir l'intégration et obtenir des performances optimales, Google vous recommande de faire appel à votre personnel qualifié.

Dans le contexte du développement logiciel, le terme "headless" désigne une architecture découplée où la couche de présentation frontend (le "head") est séparée de la logique et des fonctionnalités du backend. Dans une architecture headless, le backend, aussi appelé partie "headless", fournit des API qui vous permettent d'utiliser ses fonctionnalités et services.

Par exemple, l'automatisation des workflows personnalisés. Lorsqu'un utilisateur final lance un chat, l'événement on("chat.message") est déclenché. Vous pouvez définir des déclencheurs d'automatisation personnalisés en fonction de messages de chat spécifiques que vous avez reçus. Par exemple, si un utilisateur final saisit "Escalade" dans le chat, le gestionnaire d'événements peut automatiquement escalader la session de chat à une équipe d'assistance de niveau supérieur, ce qui permet de traiter rapidement les problèmes critiques.

Ce guide vous explique comment installer, intégrer et utiliser le SDK. Pour en savoir plus sur l'utilisation de l'API, consultez la documentation de l'API du SDK Web sans interface graphique. Vous trouverez la liste des événements disponibles sur la page des événements.

Installer le SDK Web headless

Pour installer le SDK Web sans interface utilisateur, utilisez l'extrait de code suivant dans votre projet :

npm install @ujet/websdk-headless --save

Utiliser le SDK Web headless

Pour utiliser le SDK Web headless, vous pouvez suivre l'exemple de code fourni :

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()

La classe Client accepte plusieurs options (vous pouvez personnaliser selon vos besoins) :

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[];
  };
}

Activer la journalisation

Lors de l'implémentation et des tests, il peut être nécessaire de collecter des informations supplémentaires dans le journal de la console. Pour activer la journalisation pour le SDK sans interface graphique, importez Logger et consoleLoggerHandler en ajoutant le code suivant à votre application Web :

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

Vous pouvez activer et configurer le partage d'écran à l'aide du SDK Web sans interface graphique.

L'exemple de code suivant vous montre comment activer le partage d'écran :

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

L'exemple de code suivant montre les options de partage d'écran :

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[]
}

Modèle personnalisé

Vous pouvez personnaliser le modèle de boîte de dialogue "Partager l'écran" à l'aide de l'option template de l'exemple de code précédent.

L'exemple suivant montre le modèle par défaut :

<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>

Vous pouvez utiliser ce modèle pour configurer une boîte de dialogue qui demande l'approbation de l'utilisateur final pour les éléments suivants :

Démarrer une session de partage d'écran
Démarrer une session de partage d'écran avec contrôle à distance
Démarrer une session de partage d'écran complet de l'appareil

Voici les options de modèle :

confirmSessionTemplate : pour confirmer une session de partage d'écran.
confirmRemoteControlTemplate : pour confirmer une session de partage d'écran avec contrôle à distance.
confirmFullDeviceTemplate. Pour confirmer une session de partage d'écran complet de l'appareil.
sessionControlsTemplate : pour le bouton des commandes de session. Voici le modèle par défaut : <button class="cobrowse-end js-cobrowse-end">$end</button>

Messages

Les variables de message suivantes sont utilisées dans les modèles personnalisés :

$title
$content
$allow
$deny

L'exemple suivant montre comment ces variables sont appliquées :

{
  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
}

L'exemple suivant montre les valeurs par défaut des variables en anglais :

{
  "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"
}

Configuration personnalisée des données

L'option custom_data vous permet de transmettre des données de paires clé/valeur arbitraires au SDK Web.

Utilisation

Vous pouvez fournir des données personnalisées sous forme d'objet (non signé) ou de chaîne (signée) lorsque vous créez un chat :

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

Consultez l'exemple ci-dessous :

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
}

Transfert de chatbot externe

Dans certains cas, vous pouvez souhaiter conserver l'historique et les interactions provenant d'autres fournisseurs de chat. Pour ce faire, utilisez custom_data object.