Le SDK Web headless vous offre la possibilité 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’interface utilisateur et l’expérience utilisateur pour les prendre en charge.
L'installation et l'utilisation du SDK Web headless nécessitent l'assistance 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 présentation frontale ("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 pour que vous puissiez utiliser ses fonctionnalités et services.
L'automatisation personnalisée des workflows en est un exemple. Lorsqu'un utilisateur final lance une discussion, 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 discussion spécifiques que vous avez reçus. Par exemple, si un utilisateur final saisit "Escalate" (Faire remonter) dans la discussion, le gestionnaire d'événements peut automatiquement faire remonter la session de discussion à une équipe d'assistance de niveau supérieur, ce qui permet de traiter rapidement les problèmes critiques.
Ce guide vous explique le processus d'installation, les fonctionnalités d'intégration et l'utilisation du SDK. Pour en savoir plus sur l'utilisation de l'API, consultez la documentation de l'API du SDK Web headless. Vous trouverez la liste des événements disponibles sur la page des événements.
Installer le SDK Web headless
Pour installer le SDK Web headless, 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 (que vous pouvez personnaliser en fonction de 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 recueillir des informations supplémentaires dans le journal de la console. Pour activer la journalisation pour le SDK headless, importez
Logger et consoleLoggerHandler en ajoutant le code suivant à votre application Web :
import {Logger, consoleLoggerHandler } from '@ujet/websdk-headless'
Logger.addHandler(consoleLoggerHandler)
Configurer le partage d'écran
Vous pouvez activer et configurer le partage d'écran à l'aide du SDK Web headless.
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 de partage d'é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 de l'appareil complet
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 de l'appareil complet.sessionControlsTemplate: pour le bouton de 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) lors de la création d'une discussion :
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 être amené à conserver l'historique et les interactions d'autres fournisseurs de chat. Pour ce faire, utilisez le custom_data object.
Consultez l'exemple ci-dessous :
const custom_data = {
unsigned: {
external_chat_transfer: {
greeting_override: "Please hold while we connect you with a human agent.",
agent: {
name: "Agent Name",
avatar: "https://ujet.s3.amazonaws.com/default-virtual-agent-avatar-1.png"
},
transcript: [
{
sender: "agent",
timestamp: "2021-03-15 12:00:00Z",
content: [
{
type: "text",
text: "Hello! How can I help you today?"
},
{
type: "buttons",
buttons: [
{
label: "Create New Order",
selected: false
},
{
label: "Check Order Status",
selected: true
},
{
label: "Check Account Balance",
selected: false
},
]
}
]
},
{
sender: "end_user",
timestamp: "2021-03-15 12:00:15Z",
content: [
{
type: "text",
text: "Check Order Status"
}
]
},
{
sender: "agent",
timestamp: "2021-03-15 12:00:16Z",
content: [
{
type: "text",
text: "I can help you with that, what's your order number?"
}
]
},
{
sender: "end_user",
timestamp: "2021-03-15 12:00:20Z",
content: [
{
type: "media",
media: {
type: "image",
url: "https://ujet.s3.amazonaws.com/default-virtual-agent-avatar-1.png"
}
}
]
}
]
}
},
signed: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' // JWT or other signed payload
}
try {
const chat: Chat = await client.createChat(123, { custom_data })
} catch (error) {
// handle error
}
Implémentation de référence
Pour obtenir une implémentation de référence du SDK Web, consultez ccaas-web-headless-sdk-sample sur GitHub.
Ce dépôt contient une démonstration d'une application de chat créée à l'aide d'un SDK Web headless de la plate-forme CCAI. Il présente une architecture client-serveur de base où le backend Node.js gère l'authentification sécurisée et la diffusion de la configuration, tandis que le frontend JavaScript pur fournit l'interface utilisateur de chat.