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

网页 widget

Web widget 是一种基于 Web 的客户端，您可以在 Web 应用和移动应用中使用它，让用户通过聊天或语音与您的代理应用互动。本指南提供了概览和设置说明。

打开后，该 widget 可以显示为右下角的浮动对话框窗口、主内容旁边的面板，也可以在展开的对话框模式下打开，以便专注于对话。

限制

目前，富媒体内容回答仅支持英语。

设置 Web widget

如需在您的网站上嵌入 widget，请执行以下操作：

点击代理构建器顶部的部署。
点击创建频道或新频道。
选择网站 widget 渠道类型。
为您的频道输入名称。
选择或创建代理应用版本。
配置其他偏好设置，例如色彩主题和体验类型（聊天、通话或混合）。
点击创建渠道以生成部署代码。
将部署代码添加到网站的 HTML 中。
为最终用户设置身份验证。如果您使用未经修改的嵌入代码而不配置身份验证，该 widget 会显示警告。如需详细了解相关选项和设置，请参阅配置身份验证部分。

在您的网站上嵌入微件

如需将该 widget 添加到您的网站，您需要添加以下 HTML 代码段。

以下代码段包含 reCAPTCHA 所需的脚本。如果 widget 中使用了 reCAPTCHA，widget 底部会显示一条通知，指出相应网站受 Google 保护，并且适用 Google 隐私权政策和服务条款。您还可以隐藏 reCAPTCHA 徽章。

为了支持响应式布局，您还可以选择加载 chat-messenger-layout.css。 chat-messenger-layout.css 文件用于实现自适应样式，并在使用 render-mode="slide-in" 或 render-mode="slide-over" 时使即时通讯工具滑入和滑出视图。由于它会设置 body 的样式，因此可能会影响您的网站。因此，您可以选择不加载 chat-messenger-layout.css，也可以复制其内容并将其集成到您自己的 CSS 中。

为了获得最佳性能并确保响应式布局，请遵循以下展示位置：

在 <header> 部分中：

<header>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <script defer src="https://www.gstatic.com/chat-messenger/sdk/prod/latest/chat-messenger.js"></script>

  <!-- Chat Messenger CSS -->
  <link rel="stylesheet" href="https://www.gstatic.com/chat-messenger/sdk/prod/latest/themes/chat-messenger-default.css">

  <!-- Optional responsive styling  -->
  <!-- <link rel="stylesheet" href="https://www.gstatic.com/chat-messenger/sdk/prod/latest/themes/chat-messenger-layout.css"> -->

  <!-- CSS customization -->
  <style>
    chat-messenger {
      z-index: 999;
      position: fixed;
      <!-- Your CSS customization goes here if needed -->
    }
  </style>
</header>

在 <body> 部分中：


<body>
  <!-- Your website's main content goes here -->

  <script>
    window.addEventListener("chat-messenger-loaded", () => {
      chatSdk.registerContext(
        chatSdk.prebuilts.ces.createContext({
          deploymentName: "projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID",
          tokenBroker: {
            enableTokenBroker: true,
            // If you enabled reCAPTCHA for the token broker, set enableRecaptcha to true.
            // enableRecaptcha: true,
          },
          // Automatically prompt the agent to start the conversation with a greeting.
          enableWelcomeEvent: true,
        }),
      );
    });
  </script>

  <!-- Messenger component -->
  <chat-messenger
    language-code="en"
    max-query-length="-1">
    <chat-messenger-chat-bubble
      chat-title="${your-chat-title}">
    </chat-messenger-chat-bubble>
  </chat-messenger>

  <!-- Page content continues -->
</body>

自动开始对话

默认情况下，聊天微件会等待用户发送第一条消息。如需提示智能体自动以问候语开始对话，请在 chatSdk.prebuilts.ces.createContext 函数中设置 enableWelcomeEvent: true。

启用此选项后，widget 会在聊天会话初始化时自动向代理发送 welcome 事件。代理会使用配置的问候语来响应此事件。

安全注意事项

如果将微件作为自定义元素 (<chat-messenger>) 直接嵌入到您的网站中，该微件会在宿主网页上的影子 DOM 中运行。默认情况下，它不会强制执行严格的沙盒处理（例如 iframe）。

因为该 widget 与您的应用共享窗口来源：

共享存储空间访问权限：在 widget 自定义组件中运行的任何脚本都可以访问宿主页面的 window.sessionStorage 和 window.localStorage。这包括 widget 本身存储的身份验证令牌或敏感会话数据。
跨站脚本攻击 (XSS)：如果您的自定义组件代码或富内容载荷包含未经清理的输入，则可能会被利用来在主应用的上下文中执行任意 JavaScript。

为确保应用和用户数据的安全，您必须：

清理自定义代码：确保自定义组件或载荷中使用的所有自定义 JavaScript 和 HTML 都经过严格清理。
验证输入：将从外部来源（包括代理响应）传递给 widget 的所有数据视为不受信任的数据。
句柄隔离：如果您的安全要求规定聊天微件与应用的数据之间必须严格隔离，您必须自行实现沙盒化（例如，将微件组件封装在您控制和隔离的容器中）。

配置人工客服切换

在配置 widget 之前，请确保已创建必要的资源并已完成 WebChat Proxy 部署。

设置升级号码。
1. 为您的项目创建 PhoneNumber 资源。
  1. 使用为代理应用配置的有效对话配置文件。
  2. 将对话资料与电话号码相关联，以使系统能够处理人工升级。
2. 按照说明设置 WebChat Proxy。

Webchat 客户端配置：

设置 WebChat 代理中的属性以启用实时转接功能。代码段示例：

<chat-messenger service='{"name":"ces","deployment-id":"projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID"}'
  liveHandoff="true"
escalationNumber="projects/YOUR_PROJECT_ID/locations/global/phoneNumbers/YOUR_PHONE_NUMBER_ID"
  url-allowlist="*"
>
  </chat-messenger>

HTML 自定义

您可以自定义聊天对话框显示方式和行为方式的各个方面。chat-messenger 和 chat-messenger-container HTML 元素具有以下属性：

属性	组件归因	值（可选）	效果
服务	chat-messenger		已连接的后端服务的必需服务名称。
网址许可名单	chat-messenger	*	（以英文逗号分隔的图片网域列表
logging-level	chat-messenger	调试	<OMIT>
enable-audio-input-only	chat-messenger-container		仅语音模式
从录制内容开始	chat-messenger-container		需要使用仅限语音模式。仅语音模式在聊天信使容器呈现的瞬间启动
enable-audio-input	chat-messenger-container		添加了一个按钮，用于启用多模态聊天
enable-file-upload	chat-messenger-container		启用图片上传
bot-writing-image	chat-messenger-container	字符串	在机器人“思考”期间呈现的图片的网址
chat-title-icon	chat-messenger-container	字符串	显示在聊天顶部（品牌图片）的图片的网址
chat-title	chat-messenger-container	字符串	聊天标题的文本
render-mode	chat-messenger	字符串（“slide-in”或“slide-over”）	聊天对话框相对于网页其余部分的呈现模式。选项为“slide-over”或“slide-in”。如果未指定，则可由客户端指定位置。必须提供样式才能支持 render-mode。`chat-messenger-layout.css` 可用作基准。

CSS 自定义

微件外观的自定义通过 CSS 令牌系统进行处理。通过修改这些令牌，您可以确保聊天界面与您的品牌风格保持一致，同时保持布局完整性和无障碍性。

彩色 token

这些令牌定义了 widget 表面、互动元素、文本和状态的调色板。

属性	说明	默认浅色主题	默认深色主题
容器 / 展示途径
--chat-messenger-color--surface	聊天正文和页脚区域的主要背景颜色。	#F8FAFD	#1B1B1B
--chat-messenger-color--surface-container	聊天中嵌套的 widget 容器（例如商品卡片和轮播界面）的背景颜色。	#FFFFFF	#131314
--chat-messenger-color--surface-container-high	微件内元素（例如输入字段）的高强调背景	#F0F4F9	#1E1F20
品牌 / 口音
--chat-messenger-color--primary	用于高强调填充和主要按钮的主要品牌颜色。	#303030	#E3E3E3
--chat-messenger-color--primary-container	用于用户消息气泡等关键组件的醒目背景颜色。	#E9EEF6	#282A2C
--chat-messenger-color--secondary	次要互动元素的颜色，例如“发送”按钮或色调按钮。	#DDE3EA	#333537
文字和图标
--chat-messenger-color--on-surface	在标准界面背景上显示的文字和图标的主色。	#1F1F1F	#E3E3E3
--chat-messenger-color--on-surface-variant	用于次要文本和装饰性图标的低强调色。	#444746	#C4C7C5
--chat-messenger-color--on-primary	放置在主要品牌背景上的文字和图标的颜色。	#F2F2F2	#303030
--chat-messenger-color--on-primary-container	放置在 primary-container 背景上的文字和图标的颜色。	#1F1F1F	#E3E3E3
--chat-messenger-color--on-secondary	放置在次要品牌背景上的文字和图标的颜色。	#444746	#C4C7C5
状态
--chat-messenger-color--state-layer-on-surface	用于在标准表面上指示悬停或选择状态的半透明叠加层。已停用组件的填充。	#1F1F1F 8%	#E3E3E3 8%
--chat-messenger-color--state-layer-on-primary	用于主要颜色元素之上的互动状态的半透明叠加层。	#FFFFFF 8%	#062E6F 8%
--chat-messenger-color--state-layer-on-secondary	用于次要颜色元素之上的互动状态的半透明叠加层。	#1F1F1F 8%	#E3E3E3 8%
--chat-messenger-color--state-on-surface-mute	已停用的文字和图标的颜色。	#444746（38%）	#C4C7C5（38%）
实用工具
--chat-messenger-color--outline	常规边框、分隔线和装饰轮廓的颜色。	#C4C7C5	#444746
--chat-messenger-color--outline-variant	细微边框（例如 widget 的外框）的颜色	#747775，16%	#8E918F，透明度为 16%
--chat-messenger-color--outline-active	输入字段和下拉菜单在聚焦或处于活动状态时的边框颜色。	#747775	#8E918F
--chat-messenger-color--error	醒目的颜色，用于填充、图标和文字，表示紧急情况。	#B3261E	#F2B8B5
--chat-messenger-color--error-container	错误横幅或互动式提醒容器的背景填充颜色。	#F9DEDC	#8C1D18
--chat-messenger-color--on-error-container	放置在 error-container 背景上的文字和图标。	#8C1D18	#F9DEDC
--chat-messenger-color--link	用于消息或说明中可点击的超链接的颜色。	#0B57D0	#A8C7FA

形状和高程令牌

这些令牌用于控制聊天组件的圆角半径和视觉深度（阴影）。

属性	说明	默认
--chat-messenger-shape--corner-value-small	微件内小型嵌套元素的圆角半径（例如，产品图片缩略图）	8px
--chat-messenger-shape--corner-value-medium	微件内嵌套元素的圆角半径（例如输入字段、图片）	16px
--chat-messenger-shape--corner-value-large	widget 中嵌套容器（例如轮播界面卡片、快速操作卡片）的圆角半径	20px
--chat-messenger-shape--corner-value-extra-large	主聊天窗口和 widget 容器的圆角半径。	28px
--chat-messenger-shape--corner-fully-rounded	用于按钮和药丸状的互动元素，以确保末端为完全圆形。	100 像素
--chat-messenger-elevation	应用于浮动元素和主要聊天组件的 box-shadow。	0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15)

排版 token

这些令牌定义了整个界面中使用的字体和具体缩放比例（大小、粗细、间距）。

属性	预期用途	默认
--chat-messenger-font-family	主要字体系列	Google Sans
大标题	醒目标头
--chat-messenger-typescale--title-large-font-size		18px
--chat-messenger-typescale--title-large-font-weight		400
--chat-messenger-typescale--title-large-line-height		24px
--chat-messenger-typescale--title-large-letter-spacing		0
媒介	widget 中的部分标题。
--chat-messenger-typescale--title-medium-font-size		16px
--chat-messenger-typescale--title-medium-font-weight		500
--chat-messenger-typescale--title-medium-line-height		24px
--chat-messenger-typescale--title-medium-letter-spacing		0
Title small
--chat-messenger-typescale--title-small-font-size	小卡片中的子标题或标题。	14px
--chat-messenger-typescale--title-small-font-weight		500
--chat-messenger-typescale--title-small-line-height		20px
--chat-messenger-typescale--title-small-letter-spacing		0
Body large	长说明。
--chat-messenger-typescale--body-large-font-size		16px
--chat-messenger-typescale--body-large-font-weight		400
--chat-messenger-typescale--body-large-line-height		24px
--chat-messenger-typescale--body-large-letter-spacing		0
Body medium	标准界面文字
--chat-messenger-typescale--body-medium-font-size		14px
--chat-messenger-typescale--body-medium-font-weight		400
--chat-messenger-typescale--body-medium-line-height		20px
--chat-messenger-typescale--body-medium-letter-spacing		0
Body small	辅助元数据和说明。
--chat-messenger-typescale--body-small-font-size		12px
--chat-messenger-typescale--body-small-font-weight		400
--chat-messenger-typescale--body-small-line-height		16px
--chat-messenger-typescale--body-small-letter-spacing		0.1
标签大	按钮和主要操作条状标签中的文字。
--chat-messenger-typescale--label-large-font-size		14px
--chat-messenger-typescale--label-large-font-weight		500
--chat-messenger-typescale--label-large-line-height		20px
--chat-messenger-typescale--label-large-letter-spacing		0
标签媒介	次要按钮文字和字段标签
--chat-messenger-typescale--label-medium-font-size		12px
--chat-messenger-typescale--label-medium-font-weight		500
--chat-messenger-typescale--label-medium-line-height		16px
--chat-messenger-typescale--label-medium-letter-spacing		0.1
标签（小）	微标签和徽章文字
--chat-messenger-typescale--label-small-font-size		11px
--chat-messenger-typescale--label-small-font-weight		500
--chat-messenger-typescale--label-small-line-height		16px
--chat-messenger-typescale--label-small-letter-spacing		0.1

空格 token

这些令牌可保持一致的布局密度，定义元素之间的边距、内边距和间距。

属性	默认
--chat-messenger-spacing--half	4px
--chat-messenger-spacing--one	8px
--chat-messenger-spacing--one-and-half	12px
--chat-messenger-spacing--two	16px
--chat-messenger-spacing--two-and-half	20px
--chat-messenger-spacing--three	24px
--chat-messenger-spacing--three-and-half	28px
--chat-messenger-spacing--four	32px

JavaScript 事件

Messenger 会触发各种事件，您可以为这些事件创建事件监听器。这些事件的事件目标是 chat-messenger 元素。

如需为 chat-messenger 元素添加事件监听器，请添加以下 JavaScript 代码，其中 event-type 是本部分中所述的事件名称之一


const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.addEventListener('event-type', function (event) {
  // Handle event
  ...
});

系统支持以下事件类型：

chat-messenger-loaded：当 chat-messenger 元素已完全加载并初始化时会触发此事件。
chat-messenger-close

chat-messenger-error：当 CES 代理发送错误状态代码时，会发生此事件。事件结构如下所示

eventId= `chat-messenger-error-v2`
event.details {
  message: string;
  code: number | undefined;
  status: number | string;
}

df-update-cart-count：当在 product_carousel、product_detail、product_comparison 富内容元素中发生“添加到购物车”“调整商品数量”“删除商品”操作时，系统会触发此事件。事件结构如下所示
```
{
  "detail": {
    "count": <cart_item_count>,
  }
}
```

JavaScript 函数

chat-messenger 元素提供了您可以调用来影响其行为的函数。

renderCustomEvent

此函数会显示一条文本消息，就像它作为文本响应来自代理应用一样。

例如：

const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.renderCustomText('Custom text');

renderCustomCard

此函数会显示一个自定义卡片，就像它作为富响应消息来自代理应用一样。富响应消息部分中定义了自定义载荷响应的格式。

例如：

const chatMessenger = document.querySelector('chat-messenger');
const payload = [
  {
    "type": "info",
    "title": "Info item title",
    "subtitle": "Info item subtitle",
    "image": {
      "src": {
        "rawUrl": "https://example.com/images/logo.png"
      }
    },
    "actionLink": "https://example.com"
  }];
chatMessenger.renderCustomCard(payload);

配置身份验证

Web widget 向 Google 后端服务发出的所有 API 请求都必须经过身份验证。这是通过使用短期有效的 OAuth 2.0 访问令牌来实现的。

与此令牌关联的身份（无论是最终用户还是服务账号）必须具有与代理互动的必要 IAM 权限。

其余子部分介绍了您可以设置身份验证的方式。

设置令牌代理

令牌代理是在您的 Google Cloud 项目中运行的网络服务，可代表您拥有的服务账号生成访问令牌。Web widget 可以在对话开始时自动调用令牌代理的网址，以获取与 CX Agent Studio API 通信时要使用的新令牌。

您可以通过两种方式设置令牌代理：Google 托管或自行托管。

由 Google 托管

使用 Google 提供的令牌代理来允许对聊天微件进行公开访问：

创建部署和 widget 配置时，启用公开访问权限，并可选择启用来源和 reCAPTCHA 检查（建议这样做，以防止欺骗和滥用）。
聊天 widget 将从 Google 提供的令牌代理请求会话范围令牌，并将其用于聊天会话。

自行托管

如需设置自托管的令牌代理，请按以下步骤操作：

在项目中创建服务账号，并向其授予 Customer Engagement Suite Client 角色。
使用我们提供的令牌代理示例代码部署 Cloud Run functions 函数。

如需详细的分步说明，请参阅开源代码库。

设置 OAuth2

OAuth2 客户端允许 Web widget 为最终用户启动身份验证流程。这通常意味着系统会打开一个对话框窗口，用户可在其中登录自己的 Google 账号（或其他提供商的账号），然后 Web widget 会收到一个令牌，以便代表用户执行操作。

选择此选项可要求最终用户在开始使用代理之前登录，用户凭据用于访问代理应用。

以下是您需要遵循的主要步骤：

在 Google Cloud 控制台中，前往 Google Auth Platform 并选择“客户端”。
点击创建客户端。
选择 Web 应用作为客户端类型。
为新客户输入名称。
将您的网站网址添加到“已获授权的 JavaScript 来源”和“已获授权的重定向 URI”中。
点击创建，然后等待 5 分钟再继续。

按照上述步骤操作后，您将获得一个客户端 ID，其格式如下：

123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com

在 chat-messenger Web 组件的 oauth-client-id 属性中提供此信息。

构建自己的身份验证 API

构建您自己的 API 来处理最终用户的身份验证和授权，该 API 会返回 Google 访问令牌或已签名的 JWT，其中包含在您的应用中调用 runSession 的权限。

如需了解如何使用 CX Agent Studio API，请参阅 API 访问权限。

网页 widget 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

限制