Guia do SDK da Web sem interface gráfica

O SDK da Web headless oferece a flexibilidade de estender e personalizar a experiência de suporte da sua empresa de acordo com suas necessidades. Ele contém todos os recursos do SDK da Web que você já conhece e permite criar a UI e a UX para oferecer suporte a eles.

A instalação e o uso do SDK da Web headless exigem o suporte da equipe de desenvolvimento web da sua organização. Para realizar uma integração bem-sucedida e alcançar o desempenho ideal, o Google recomenda envolver sua equipe qualificada.

No contexto do desenvolvimento de software, "headless" se refere a uma arquitetura desacoplada em que a camada de apresentação do front-end (a "cabeça") é separada da lógica e dos recursos do back-end. Em uma arquitetura headless, o back-end, também conhecido como a parte "headless", fornece APIs que permitem usar os recursos e serviços dele.

Um exemplo é a automação de fluxo de trabalho personalizada. Quando um usuário final inicia um chat, o evento on("chat.message") é acionado. É possível definir acionadores de automação personalizados com base em mensagens de chat específicas que você recebeu. Por exemplo, se um usuário final digitar "Escalar" no chat, o manipulador de eventos poderá encaminhar automaticamente a sessão de chat para uma equipe de suporte de nível superior, oferecendo atenção imediata a problemas críticos.

Este guia mostra o processo de instalação, os recursos de integração e o uso do SDK. Para saber como usar a API, consulte a documentação da API do SDK da Web sem interface. Uma lista de eventos disponíveis pode ser encontrada na página Eventos.

Observação: o Google só oferece suporte às três versões secundárias mais recentes do SDK da Web sem interface gráfica. Para receber suporte, seu site precisa usar uma dessas versões do SDK da Web headless.

Instalar o SDK da Web headless

Para instalar o cliente do SDK da Web headless, use o snippet de código a seguir no seu projeto.

Você pode instalar o pacote com o npm:

npm install @ujet/websdk-headless --save

Ou use o script hospedado pela 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>

Usar o SDK da Web headless

Para usar o SDK da Web headless, siga o exemplo de código fornecido:

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

A classe Client aceita várias opções (você pode personalizar de acordo com seus 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;
  };
}

Ativar a geração de registros

Durante a implementação e os testes, pode ser necessário coletar mais informações no registro do console. Para ativar a geração de registros no SDK headless, importe Logger e consoleLoggerHandler adicionando o seguinte código ao seu aplicativo da Web:

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

Configurar o compartilhamento de tela

É possível ativar e configurar o compartilhamento de tela usando o SDK da Web headless.

O exemplo de código a seguir mostra como ativar o compartilhamento de tela:

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

O exemplo de código a seguir mostra as opções de compartilhamento de tela:

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
}

Modelo personalizado

É possível personalizar o modelo de caixa de diálogo de compartilhamento de tela usando a opção template do exemplo de código anterior.

O exemplo a seguir mostra o modelo padrão:

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

Use esse modelo para configurar uma caixa de diálogo que solicita a aprovação do usuário final para o seguinte:

• Iniciar uma sessão de compartilhamento de tela

• Iniciar uma sessão de compartilhamento de tela com controle remoto

• Iniciar uma sessão de compartilhamento de tela inteira do dispositivo

Estas são as opções de modelo:

• confirmSessionTemplate: para confirmar uma sessão de compartilhamento de tela.

• confirmRemoteControlTemplate: para confirmar uma sessão de compartilhamento de tela por controle remoto.

• confirmFullDeviceTemplate. Para confirmar uma sessão de compartilhamento de tela completa do dispositivo.

• sessionControlsTemplate: para o botão de controles da sessão. Este é o modelo padrão: <button class="cobrowse-end js-cobrowse-end">$end</button>

Mensagens

As seguintes variáveis de mensagem são usadas em modelos personalizados:

• $title

• $content

• $allow

• $deny

O exemplo a seguir mostra como essas variáveis são aplicadas:

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

O exemplo a seguir mostra os valores padrão das variáveis em 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 headless

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

Observação : tratamento de erros. A maioria dos métodos Client propaga erros de HTTP como exceções geradas. Encapsule as chamadas em try/catch, a menos que a documentação do método indique o contrário.

Eventos

Para ver uma lista de todos os eventos emitidos, consulte a página Eventos.

Propriedades

Nome	Descrição
deviceId	O ID do dispositivo, determinado pelo SDK sem interface na inicialização.
lang	A configuração de idioma do cliente atual. Se lang for transmitido na configuração, ele se tornará somente leitura.
chat	Só tem um valor quando há uma conversa em andamento.
cobrowse	O cliente CobrowseIO, disponível após a inicialização do Cobrowse.

Eventos

Para ver uma lista de todos os eventos emitidos, consulte a página Todos os eventos disponíveis.

Nome	Descrição
destroy	Destrói o comunicador e todos os listeners de eventos.
on	Adiciona um manipulador de eventos para o evento fornecido.
off	Remove o manipulador de eventos do evento fornecido.

Use o método .destroy para remover o iframe e todos os listeners de eventos:

client.destroy()

Use o método .on para acompanhar os eventos:

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

Remova o manipulador de eventos com .off:

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

Implementação de referência

Para uma implementação de referência do SDK da Web, consulte ccaas-web-headless-sdk-sample no GitHub.

Este repositório contém uma demonstração de um aplicativo de chat criado com um SDK da Web sem interface da plataforma CCAI. Ele mostra uma arquitetura básica de cliente-servidor, em que o back-end do Node.js lida com a autenticação segura e a entrega da configuração, enquanto o front-end em JavaScript puro fornece a interface do usuário do chat.