Guida all'SDK web headless

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 ti consentono di utilizzare le sue funzionalità e i suoi servizi.

Un esempio è l'automazione del flusso di lavoro 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 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 Headless Web SDK. Un elenco degli eventi disponibili è disponibile nella pagina degli eventi.

Installa l'SDK web headless

Per installare l'SDK web headless, utilizza il seguente snippet di codice nel tuo progetto:

npm install @ujet/websdk-headless --save

Utilizzare l'SDK web headless

Per utilizzare l'SDK web headless, puoi seguire il codice di esempio fornito:

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 accetta diverse opzioni (puoi personalizzarle in base ai tuoi requisiti):

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

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)

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.

L'esempio seguente 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 schermo completa del 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"
}

Configurazione dei dati personalizzata

L'opzione custom_data consente di trasmettere 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. Per farlo, utilizza custom_data object.