无头 Web SDK 指南

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

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

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

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

本指南将引导您完成 SDK 的安装流程，并介绍其集成功能和用法。如需详细了解如何使用该 API，请参阅 Headless Web SDK API 文档。如需查看可用活动的列表，请访问活动页面。

安装无头 Web SDK

如需安装无头 Web SDK，请在您的项目中使用以下代码段：

npm install @ujet/websdk-headless --save

使用无头 Web SDK

如需使用无头 Web SDK，您可以按照提供的示例代码操作：

import { Client } from "@ujet/websdk-headless"
const client = new Client({ ... })

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

自定义数据配置

借助 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 前端提供聊天用户界面。