L'SDK web headless ti offre la flessibilità di estendere e personalizzare l'esperienza di assistenza della tua azienda in base alle tue esigenze. Contiene tutte le nostre funzionalità dell'SDK web e offre la possibilità di creare l'interfaccia utente e l'esperienza utente per supportarle.
L'installazione e l'utilizzo dell'SDK web headless richiedono il supporto del team di sviluppo web della tua organizzazione. Per eseguire un'integrazione corretta e ottenere un rendimento ottimale, Google consiglia di coinvolgere il tuo personale qualificato.
Nel contesto dello sviluppo software, "headless" si riferisce a un'architettura disaccoppiata in cui il livello di presentazione del frontend (l'"head") è separato dalla logica e dalle funzionalità del backend. In un'architettura headless, il backend, noto anche come parte "headless", fornisce API che consentono di utilizzare le sue funzionalità e i suoi servizi.
Un esempio è l'automazione del workflow personalizzato. Quando un utente finale avvia una chat, viene attivato l'evento
on("chat.message"). Puoi definire trigger di automazione personalizzati in base a messaggi di chat specifici che hai ricevuto. Ad esempio, se un
utente finale digita "Riassegna" nella chat, il gestore di eventi può riassegnare automaticamente
la sessione di chat a un team di assistenza di livello superiore, fornendo un'attenzione
tempestiva ai problemi critici.
Questa guida illustra la procedura di installazione, le funzionalità di integrazione e l'utilizzo dell'SDK. Per informazioni dettagliate sull'utilizzo dell'API, consulta la documentazione dell'API SDK web headless. Un elenco degli eventi disponibili è disponibile nella pagina degli eventi.
Installa l'SDK web headless
Puoi installare il pacchetto con npm:
npm install @ujet/websdk-headless --save
In alternativa, puoi utilizzare lo script ospitato da UJET:
<script src="https://websdk.ujet.co/v3/headless.js"></script>
<script>
// The hosted script exposes the client as the global `UJETClient`.
// const client = new UJETClient(...)
</script>
Utilizza l'SDK web headless
Per utilizzare l'SDK web headless, puoi seguire il codice di esempio fornito:
import { Client } from "@ujet/websdk-headless"
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 accetta diverse opzioni (puoi personalizzare in base ai tuoi requisiti):
interface ClientOption {
companyId: string;
authenticate: () => Promise<TokenResponse>;
tenant?: string;
host?: string;
lang?: string;
bridge?: string;
version?: string;
cobrowse?: {
enabled?: boolean;
messages?: CobrowseMessages;
api?: string;
license?: string;
trustedOrigins?: string[];
capabilities?: string[];
registration?: boolean;
redactedViews?: string[];
unredactedViews?: string[];
};
}
Abilita il logging
Durante l'implementazione e il test potrebbe essere necessario raccogliere ulteriori
informazioni nel log della console. Per attivare la registrazione per l'SDK headless, importa
Logger e consoleLoggerHandler aggiungendo il seguente codice all'applicazione web:
import {Logger, consoleLoggerHandler } from '@ujet/websdk-headless'
Logger.addHandler(consoleLoggerHandler)
Configurare la condivisione schermo
Puoi attivare e configurare la condivisione dello schermo utilizzando l'SDK web headless.
Il seguente esempio di codice mostra come attivare la condivisione dello schermo:
new Client({
// ...
cobrowse: {
enabled: true,
license: 'YOUR_SCREEN_SHARE_LICENSE'
}
})
Il seguente esempio di codice mostra le opzioni per la condivisione schermo:
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[]
}
Modello personalizzato
Puoi personalizzare il modello della finestra di dialogo Condividi schermo utilizzando l'opzione template
dell'esempio di codice precedente.
Il seguente esempio mostra il modello predefinito:
<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>
Puoi utilizzare questo modello per configurare una finestra di dialogo che richiede l'approvazione dell'utente finale per quanto segue:
Avviare una sessione di condivisione schermo
Avviare una sessione di condivisione schermo con controllo remoto
Avviare una sessione di condivisione schermo dell'intero dispositivo
Ecco le opzioni del modello:
confirmSessionTemplate: Per confermare una sessione di condivisione schermo.confirmRemoteControlTemplate: Per confermare una sessione di condivisione schermo con controllo remoto.confirmFullDeviceTemplate. Per confermare una sessione di condivisione dello schermo dell'intero dispositivo.sessionControlsTemplate: per il pulsante dei controlli della sessione. Ecco il modello predefinito:<button class="cobrowse-end js-cobrowse-end">$end</button>
Messaggi
Le seguenti variabili di messaggio vengono utilizzate nei modelli personalizzati:
$title$content$allow$deny
Il seguente esempio mostra come vengono applicate queste variabili:
{
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'esempio seguente mostra i valori predefiniti delle variabili in inglese:
{
"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"
}
Proprietà
| Nome | Descrizione |
|---|---|
deviceId |
L'ID del dispositivo, determinato dall'SDK headless all'inizializzazione. |
lang |
La configurazione della lingua del client attuale. Se lang viene passato nella configurazione, diventa di sola lettura. |
chat |
Ha un valore solo quando è in corso una chat. |
cobrowse |
Il client CobrowseIO sottostante, disponibile dopo l'inizializzazione di Cobrowse |
Eventi
| Nome | Descrizione |
|---|---|
destroy |
Elimina il comunicatore e tutti i listener di eventi. |
on |
Aggiunge un gestore di eventi per l'evento fornito. |
off |
Rimuove il gestore di eventi per l'evento fornito. |
Utilizza il metodo .destroy per rimuovere l'iframe e tutti i listener di eventi
client.destroy()
Utilizza il metodo .on per monitorare gli eventi.
client.on('chat.updated', someFunc)
Rimuovi il gestore di eventi con .off:
client.off('chat.updated', someFunc)
Configurazione dei dati personalizzata
L'opzione custom_data ti consente di passare dati di coppie chiave-valore arbitrarie all'SDK web.
Utilizzo
Quando crei una chat, puoi fornire dati personalizzati come oggetto (senza firma) o come stringa (con firma):
interface ChatRequest {
lang?: string;
trigger_id?: string;
ticket_id?: string;
email?: string;
greeting?: string;
cobrowsable?: boolean;
custom_data?: {
signed?: string;
unsigned?: Record<string, any>;
};
}
Vedi il seguente esempio:
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
}
Trasferimento di chatbot esterni
In alcuni casi potresti voler mantenere la cronologia e le interazioni
di altri fornitori di chat. Puoi farlo utilizzando custom_data object.
Vedi il seguente esempio:
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
}
Implementazione di riferimento
Per un'implementazione di riferimento dell'SDK web, consulta ccaas-web-headless-sdk-sample su GitHub.
Questo repository contiene una dimostrazione di un'applicazione di chat creata utilizzando un SDK headless web della piattaforma CCAI. Mostra un'architettura client-server di base in cui il backend Node.js gestisce l'autenticazione sicura e la distribuzione della configurazione, mentre il frontend JavaScript puro fornisce l'interfaccia utente della chat.