Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

无头 Web SDK 指南

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

安装和使用无头 Web SDK 需要组织的网络开发团队提供支持。为了成功完成集成并实现最佳性能，Google 建议您让合格的人员参与其中。

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

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

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

安装无头 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[];
  };
}

启用日志记录

在实现和测试期间，可能需要在控制台日志中收集更多信息。如需为无头 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
  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[]
}

自定义模板

您可以使用上述代码示例中的 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"
}

属性

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

事件

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

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

client.destroy()

使用 .on 方法跟踪事件。

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

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

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

自定义数据配置

借助 custom_data 选项，您可以将任意键值对数据传递给 Web SDK。

用量

创建聊天时，您可以提供自定义数据，格式可以是对象（未签名）或字符串（已签名）：

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

请参阅以下示例：

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
}

外部聊天机器人转移

在某些情况下，您可能希望保留来自其他聊天服务提供商的历史记录和互动内容。您可以使用 custom_data object 来实现此目的。

请参阅以下示例：

const custom_data = {
  unsigned: {
    external_chat_transfer: {
      greeting_override: "Please hold while we connect you with a human agent.",
      agent: {
        name: "Agent Name",
        avatar: "https://ujet.s3.amazonaws.com/default-virtual-agent-avatar-1.png"
      },
      transcript: [
        {
          sender: "agent",
          timestamp: "2021-03-15 12:00:00Z",
          content: [
            {
              type: "text",
              text: "Hello! How can I help you today?"
            },
            {
              type: "buttons",
              buttons: [
                {
                  label: "Create New Order",
                  selected: false
                },
                {
                  label: "Check Order Status",
                  selected: true
                },
                {
                  label: "Check Account Balance",
                  selected: false
                },
              ]
            }
          ]
        },
        {
          sender: "end_user",
          timestamp: "2021-03-15 12:00:15Z",
          content: [
            {
              type: "text",
              text: "Check Order Status"
            }
          ]
        },
        {
          sender: "agent",
          timestamp: "2021-03-15 12:00:16Z",
          content: [
            {
              type: "text",
              text: "I can help you with that, what's your order number?"
            }
          ]
        },
        {
          sender: "end_user",
          timestamp: "2021-03-15 12:00:20Z",
          content: [
            {
              type: "media",
              media: {
                type: "image",
                url: "https://ujet.s3.amazonaws.com/default-virtual-agent-avatar-1.png"
              }
            }
          ]
        }
      ]
    }
  },
  signed: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' // JWT or other signed payload
}

try {
  const chat: Chat = await client.createChat(123, { custom_data })
} catch (error) {
  // handle error
}

参考实现

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

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