Guía del SDK web sin interfaz gráfica

El SDK web sin interfaz gráfica te brinda la flexibilidad para extender y personalizar la experiencia de asistencia de tu empresa según tus necesidades. Incluye todas las funciones conocidas del SDK web y te permite crear la IU y UX para brindar asistencia.

Para instalar y usar el SDK web sin interfaz gráfica, se requiere la asistencia del equipo de desarrollo web de tu organización. Para realizar una integración exitosa y lograr un rendimiento óptimo, Google recomienda que involucres a tu personal calificado.

En el contexto del desarrollo de software, "sin interfaz gráfica" se refiere a una arquitectura separada en la que la capa de presentación del frontend (la "interfaz gráfica") está separada de la lógica y las capacidades del backend. En una arquitectura sin interfaz gráfica, el backend, también conocido como la parte "sin interfaz gráfica", proporciona APIs que te permiten usar sus funciones y servicios.

Un ejemplo es la automatización de flujos de trabajo personalizados. Cuando un usuario final inicia un chat, se activa el evento on("chat.message"). Puedes definir activadores de automatización personalizados en función de los mensajes de chat específicos que hayas recibido. Por ejemplo, si un usuario final escribe "Derivar" en el chat, el controlador de eventos puede derivar automáticamente la sesión de chat a un equipo de asistencia de nivel superior, lo que proporciona atención inmediata a los problemas críticos.

En esta guía, se explica el proceso de instalación, las capacidades de integración y el uso del SDK. Para obtener detalles sobre el uso de la API, consulta la documentación de la API del SDK web sin interfaz gráfica. Puedes encontrar una lista de los eventos disponibles en la página Eventos.

Nota: Google solo admite las tres versiones secundarias más recientes del SDK web sin interfaz gráfica. Para recibir asistencia, tu sitio web debe usar una de estas versiones del SDK web sin interfaz gráfica.

Instala el SDK web sin interfaz gráfica

Para instalar el cliente del SDK web sin interfaz gráfica, usa el siguiente fragmento de código en tu proyecto.

Puedes instalar el paquete con npm:

npm install @ujet/websdk-headless --save

También puedes usar la secuencia de comandos alojada por 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>

Usa el SDK web sin interfaz gráfica

Para usar el SDK web sin interfaz gráfica, puedes seguir el código de ejemplo que se proporciona:

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 clase Client acepta varias opciones (puedes personalizarlas según tus requisitos):

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

Habilitar registro

Durante la implementación y las pruebas, es posible que sea necesario recopilar información adicional en el registro de la consola. Para habilitar el registro del SDK sin interfaz gráfica, importa Logger y consoleLoggerHandler agregando el siguiente código a tu aplicación web:

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

Configura Compartir pantalla

Puedes habilitar y configurar la función de compartir pantalla con el SDK web sin interfaz gráfica.

En la siguiente muestra de código, se indica cómo habilitar la función para compartir pantalla:

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

En la siguiente muestra de código, se indican las opciones para compartir pantalla:

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
}

Plantilla personalizada

Puedes personalizar la plantilla del diálogo para compartir pantalla con la opción template de la muestra de código anterior.

En el siguiente ejemplo, se muestra la plantilla predeterminada:

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

Puedes usar esta plantilla para configurar un diálogo que solicite la aprobación del usuario final para lo siguiente:

• Cómo iniciar una sesión de Compartir pantalla

• Cómo iniciar una sesión de control remoto de Compartir pantalla

• Cómo iniciar una sesión de Compartir pantalla de todo el dispositivo

Estas son las opciones de plantilla:

• confirmSessionTemplate: Para confirmar una sesión de Compartir pantalla.

• confirmRemoteControlTemplate: Se usa para confirmar una sesión de uso compartido de pantalla con control remoto.

• confirmFullDeviceTemplate: Se usa para confirmar una sesión de uso compartido de pantalla completa del dispositivo.

• sessionControlsTemplate: Para el botón de controles de la sesión. Esta es la plantilla predeterminada: <button class="cobrowse-end js-cobrowse-end">$end</button>

Mensajes

Las siguientes variables de mensaje se usan en las plantillas personalizadas:

• $title

• $content

• $allow

• $deny

En el siguiente ejemplo, se muestra cómo se aplican estas variables:

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

En el siguiente ejemplo, se muestran los valores predeterminados de las variables en inglés:

{
  "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 de cliente sin interfaz gráfica

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

Nota: Manejo de errores: La mayoría de los métodos Client propagan los errores de HTTP como excepciones generadas. Une las llamadas en try/catch, a menos que la documentación del método indique lo contrario.

Eventos

Para obtener una lista de todos los eventos emitidos, consulta la página Eventos.

Propiedades

Nombre	Descripción
deviceId	Es el ID del dispositivo, que determina el SDK sin interfaz gráfica durante la inicialización.
lang	Es la configuración de idioma actual del cliente. Si se pasa lang en la configuración, se convierte en de solo lectura.
chat	Solo tiene un valor cuando hay un chat en curso.
cobrowse	El cliente de CobrowseIO subyacente, disponible después de que se haya inicializado la navegación conjunta

Eventos

Para obtener una lista de todos los eventos emitidos, consulta la página Todos los eventos disponibles.

Nombre	Descripción
destroy	Destruye el comunicador y todos los objetos de escucha de eventos.
on	Agrega un controlador de eventos para el evento proporcionado.
off	Quita el controlador de eventos para el evento proporcionado.

Usa el método .destroy para quitar el iframe y todos los objetos de escucha de eventos:

client.destroy()

Usa el método .on para hacer un seguimiento de los eventos:

client.on('chat.updated', someFunc)

Quita el controlador de eventos con .off:

client.off('chat.updated', someFunc)

Implementación de referencia

Para obtener una implementación de referencia del SDK web, consulta ccaas-web-headless-sdk-sample en GitHub.

Este repositorio contiene una demostración de una aplicación de chat compilada con un SDK web sin interfaz gráfica de CCAI Platform. Muestra una arquitectura básica de cliente-servidor en la que el backend de Node.js controla la autenticación segura y la entrega de la configuración, mientras que el frontend de JavaScript puro proporciona la interfaz de usuario del chat.