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 familiari e offre la possibilità di creare la UI e la UX 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 (la "testa") è 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 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 chat specifici che hai ricevuto. Ad esempio, se un utente finale digita "Assegna" nella chat, il gestore di eventi può assegnare 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 Eventi.

Installa l'SDK web headless

Per installare il client SDK web headless, utilizza il seguente snippet di codice nel tuo progetto.

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 personalizzarle 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[];
    template?: string;
  };
}

Abilita il logging

Durante l'implementazione e i test potrebbe essere necessario raccogliere ulteriori informazioni nel log della console. Per attivare il logging per l'SDK headless, importa Logger e consoleLoggerHandler aggiungendo il seguente codice alla tua applicazione web:

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

Configura la condivisione schermo

Puoi attivare e configurare la condivisione schermo utilizzando l'SDK web headless.

Il seguente esempio di codice mostra come attivare la condivisione 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
  // Widget-only - the following template + root options have no effect in the Headless SDK:
  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[]
  // Headless consent callbacks
  confirmSession?: () => Promise<boolean>
  confirmRemoteControl?: () => Promise<boolean>
  confirmFullDevice?: () => Promise<boolean>

  // Headless session-control callbacks
  showSessionControls?: () => void
  hideSessionControls?: () => void

  // Existing CobrowseIO instance
  instance?: any
}

Modello personalizzato

Puoi personalizzare il modello della finestra di dialogo di condivisione schermo utilizzando l'opzione template dell'esempio di codice precedente.

L'esempio seguente mostra il template 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 template per configurare una finestra di dialogo che richiede l'approvazione dell'utente finale per quanto segue:

  • Avvia una sessione di condivisione schermo

  • Avvia una sessione di condivisione schermo con controllo remoto

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

Nei modelli personalizzati vengono utilizzate le seguenti variabili dei messaggi:

  • $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"
}

API client headless

import { Client } from "@ujet/websdk-headless"

Eventi

Per un elenco di tutti gli eventi emessi, consulta la pagina Eventi.

Proprietà

Nome Descrizione
deviceId L'ID del dispositivo, determinato dall'SDK headless durante l'inizializzazione.
lang La configurazione della lingua del client corrente. 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 della navigazione condivisa

Eventi

Per un elenco di tutti gli eventi emessi, consulta la pagina Tutti gli eventi disponibili.

Nome Descrizione
destroy Elimina il comunicatore e tutti i listener di eventi.
on Aggiunge il 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)

Implementazione dei riferimenti

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 web headless 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.