无头 Web SDK 指南

借助无头 Web SDK，您可以根据需要灵活地扩展和自定义公司的支持体验。它包含我们所有熟悉的 Web SDK 功能，并提供构建界面和用户体验以支持这些功能的能力。

安装和使用无头 Web SDK 需要贵组织 Web 开发团队的支持。为成功完成集成并实现最佳性能，Google 建议您让符合条件的人员参与进来。

在软件开发中，“无头”是指一种解耦架构，其中前端展示层（“头”）与后端逻辑和功能分离。在无头架构中，后端（也称为“无头”部分）提供 API，让您可以使用其功能和服务。

例如，自定义工作流自动化。当最终用户发起聊天时，系统会触发 on("chat.message") 事件。您可以根据收到的特定聊天消息定义自定义自动化触发器。例如，如果最终用户在聊天中输入“上报”，事件处理脚本可以自动将聊天会话上报给更高级别的支持团队，从而及时关注关键问题。

本指南将引导您完成 SDK 的安装流程、集成功能和使用。如需详细了解如何使用该 API，请参阅无头 Web SDK API 文档。 您可以在“活动”页面上找到可用活动列表。

注意： Google 仅支持最新三个次要版本的无头 Web SDK。如需获得支持，您的网站必须使用以下某个版本的无头 Web SDK。

安装无头 Web SDK

如需安装无头 Web SDK 客户端，请在项目中使用以下代码段。

您可以使用 npm 安装该软件包：

npm install @ujet/websdk-headless --save

或者，您也可以使用 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>

使用无头 Web SDK

如需使用无头 Web SDK，您可以参考以下示例代码：

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

Client 类接受多个选项（您可以根据自己的要求进行自定义）：

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

启用日志记录

在实现和测试期间，可能需要在控制台日志中收集更多信息。如需为无头 SDK 启用日志记录，请将以下代码添加到您的 Web 应用中，以导入 Logger 和 consoleLoggerHandler：

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

配置屏幕共享

您可以使用无头 Web SDK 启用和配置屏幕共享。

以下代码示例展示了如何启用屏幕共享：

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

以下代码示例展示了屏幕共享选项：

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
}

自定义模板

您可以使用上述代码示例中的 template 选项自定义屏幕共享对话框模板。

以下示例展示了默认模板：

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

您可以使用此模板配置一个对话框，请求最终用户批准以下事项：

• 启动屏幕共享会话

• 启动远程控制屏幕共享会话

• 启动完整设备屏幕共享会话

以下是模板选项：

• confirmSessionTemplate：用于确认屏幕共享会话。

• confirmRemoteControlTemplate：用于确认远程控制屏幕共享会话。

• confirmFullDeviceTemplate。用于确认完整设备屏幕共享会话。

• sessionControlsTemplate：用于会话控件按钮。以下是默认模板： <button class="cobrowse-end js-cobrowse-end">$end</button>

消息

自定义模板中使用以下消息变量：

• $title

• $content

• $allow

• $deny

以下示例展示了这些变量的应用方式：

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

以下示例显示了默认的英语变量值：

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

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

注意： 错误处理 - 大多数 Client 方法都会将 HTTP 错误作为抛出的异常进行传播。除非方法文档另有说明，否则请将调用封装在 try/catch 中。

事件

如需查看所有发出的事件的列表，请参阅事件页面。

属性

名称	说明
deviceId	设备的 ID，由无头 SDK 在初始化时确定。
lang	当前客户端的语言配置。如果在配置中传递了 lang，它将变为只读。
chat	仅在有正在进行的对话时才有值。
cobrowse	底层 CobrowseIO 客户端，在 Cobrowse 初始化后可用

事件

如需查看所有已发出事件的列表，请参阅所有可用事件页面。

名称	说明
destroy	销毁通信器和所有事件监听器。
on	为提供的事件添加事件处理脚本。
off	移除所提供事件的事件处理脚本。

使用 .destroy 方法移除 iframe 和所有事件监听器：

client.destroy()

使用 .on 方法跟踪事件：

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

使用 .off 移除事件处理脚本：

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

参考实现

如需查看 Web SDK 的参考实现，请参阅 GitHub 上的 ccaas-web-headless-sdk-sample。

此代码库包含使用 CCAI Platform Web Headless SDK 构建的聊天应用的演示。它展示了一个基本的客户端-服务器架构，其中 Node.js 后端负责处理安全身份验证和配置交付，而纯 JavaScript 前端则提供聊天界面。