Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

網頁小工具

網頁小工具是網頁式用戶端，您可以在網頁和行動應用程式中使用，讓使用者透過即時通訊或語音與代理程式應用程式互動。本指南提供總覽和設定說明。

開啟後，小工具可以顯示為右下角的浮動對話方塊、主內容旁的面板，或以展開的對話模式開啟，方便專心對話。

限制

目前多媒體內容回覆僅支援英文。

設定網頁小工具

如要在網站上嵌入小工具，請按照下列步驟操作：

按一下代理程式建構工具頂端的「部署」。
按一下「建立頻道」或「新頻道」。
選取「網站小工具」管道類型。
輸入頻道名稱。
選取或建立代理程式應用程式版本。
設定其他偏好設定，例如色彩主題和體驗類型 (即時通訊、通話或混合)。
按一下「建立管道」，產生部署程式碼。
將部署程式碼新增至網站的 HTML。
為使用者設定驗證機制。如果您使用未經修改的嵌入程式碼，但未設定驗證，小工具就會顯示警告。如要瞭解選項和設定詳情，請參閱「設定驗證」一節。

在網站上嵌入小工具

如要在網站中加入小工具，請新增下列 HTML 程式碼片段。

下方程式碼片段包含 reCAPTCHA 必要的指令碼。如果在小工具中使用 reCAPTCHA，小工具底部會顯示通知，指出該網站受到 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。

啟用這個選項後，小工具會在聊天工作階段初始化時，自動將 welcome 事件傳送給代理程式。代理會根據設定的問候語回覆這個事件。

安全性考量

將小工具以自訂元素 (<chat-messenger>) 直接嵌入網站時，小工具會在主機網頁的陰影 DOM 中執行。根據預設，這項功能不會強制執行嚴格的沙箱 (例如 iframe)。

因為小工具會與應用程式共用視窗來源：

共用儲存空間存取權： 在小工具自訂元件中執行的任何指令碼，都可以存取主機網頁的 window.sessionStorage 和 window.localStorage。包括小工具本身儲存的驗證權杖或私密工作階段資料。
跨網站指令碼攻擊 (XSS)： 如果自訂元件程式碼或富內容酬載含有未經清理的輸入內容，攻擊者就能利用這些內容，在主要應用程式的環境中執行任意 JavaScript。

為維護應用程式和使用者資料的安全，您必須：

清除自訂程式碼： 確保自訂元件或酬載中使用的所有自訂 JavaScript 和 HTML 都經過嚴格清除。
驗證輸入內容： 將從外部來源傳遞至小工具的所有資料 (包括代理程式回覆) 視為不受信任。
控點隔離： 如果您的安全防護規定要求聊天小工具與應用程式資料之間必須嚴格隔離，您必須自行實作沙箱 (例如將小工具元件包裝在您控管和隔離的容器中)。

設定轉介給真人服務專員

設定小工具前，請務必先建立必要資源，並完成 WebChat Proxy 部署作業。

設定緊急聯絡電話號碼。
1. 為專案建立 PhoneNumber 資源。
  1. 使用為代理程式應用程式設定的有效對話設定檔。
  2. 將對話設定檔與 PhoneNumber 建立關聯，讓系統處理人工介入程序。
2. 按照操作說明設定 WebChat Proxy。

Webchat 用戶端設定：

從 WebChat Proxy 設定屬性，啟用即時轉接功能。程式碼片段範例：

<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		已連結後端服務的必要服務名稱。
url-allowlist	chat-messenger	*	(以半形逗號分隔的圖片網域清單
logging-level	chat-messenger	偵錯	<OMIT>
enable-audio-input-only	chat-messenger-container		僅語音模式
start-with-recording	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」。如未指定，則可由用戶端指定位置。必須有樣式才能支援算繪模式。`chat-messenger-layout.css` 可做為基準。

自訂 CSS

自訂小工具外觀時，系統會透過 CSS 權杖處理。修改這些符記後，即可確保聊天介面與品牌風格一致，同時維持版面配置完整性和無障礙功能。

顏色權杖

這些符記會定義小工具表面的調色盤、互動式元素、文字和狀態。

屬性	說明	預設淺色主題	預設深色主題
容器 / 介面
--chat-messenger-color--surface	聊天主體和頁尾區域的主要背景顏色。	#F8FAFD	#1B1B1B
--chat-messenger-color--surface-container	聊天室中巢狀小工具容器的背景顏色 (例如產品資訊卡和輪轉介面)。	#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	放置在主要容器背景上的文字和圖示顏色。	#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	細微邊框的顏色 (例如小工具的外框)	#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	文字和圖示放置在錯誤容器背景上。	#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	小工具中巢狀容器的圓角半徑 (例如輪轉介面資訊卡、快速操作資訊卡)	20px
--chat-messenger-shape--corner-value-extra-large	主要即時通訊視窗和 Widget 容器的圓角半徑。	28px
--chat-messenger-shape--corner-fully-rounded	用於按鈕和藥丸形狀的互動式元素，確保結尾為完整圓形。	100 像素
--chat-messenger-elevation	套用至浮動元素和主要即時通訊元件的陰影。	0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15)

字體排版權杖

這些權杖定義了整個介面使用的字體和特定比例 (大小、粗細、間距)。

屬性	預定用途	預設
--chat-messenger-font-family	主要字型系列	Google Sans
Title large	醒目標頭
--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
Title medium	小工具中的區塊標題。
--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
內文大	詳細說明。
--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
內文媒介	標準 UI 文字
--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
內文小	次要中繼資料和說明。
--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
Label large	按鈕和主要動作方塊中的文字。
--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
Label small	微標籤和徽章文字
--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

間距權杖

這些符記可維持一致的版面配置密度，並定義元素之間的邊界、邊框間距和間隙。

屬性	預設
--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);

設定驗證機制

網頁小工具向 Google 後端服務發出的所有 API 要求都必須經過驗證。這項作業是透過短期 OAuth 2.0 存取權杖完成。

與這個權杖相關聯的身分 (無論是使用者或服務帳戶)，都必須具備與代理程式互動的必要 IAM 權限。

其餘小節將說明如何設定驗證。

設定權杖代理程式

權杖代理程式是您 Google Cloud 專案中執行的網路服務，可代表您擁有的服務帳戶產生存取權杖。在對話開始時，網頁小工具會自動呼叫權杖代理的網址，取得與 CX Agent Studio API 通訊時要使用的新權杖。

您可以透過由 Google 代管或自行代管兩種方式設定權杖中介服務。

由 Google 代管

使用 Google 提供的權杖代理程式，允許公開存取即時通訊小工具：

建立部署作業和小工具設定時，請啟用公開存取權，並視需要啟用來源和 reCAPTCHA 檢查 (建議啟用，以防範詐欺和濫用行為)。
聊天小工具會向 Google 提供的權杖代理程式要求工作階段範圍權杖，並用於聊天工作階段。

自行託管

請按照下列步驟設定自行代管的權杖代理程式：

在專案中建立服務帳戶，並授予 Customer Engagement Suite Client 角色。
使用我們提供的權杖代理程式碼範例，部署 Cloud Run functions 函式。

如需詳細的逐步操作說明，請參閱開放原始碼存放區。

設定 OAuth 2.0

OAuth2 用戶端可讓網路小工具為使用者啟動驗證流程。這通常表示系統會開啟對話方塊視窗，讓使用者登入 Google 帳戶 (或其他供應商)，而網頁小工具則會收到權杖，代表使用者執行作業。

選擇這項設定，即可要求使用者先登入才能使用代理程式，並使用使用者憑證存取代理程式應用程式。

以下是您需要執行的主要步驟：

前往 Google Cloud 控制台的 Google Auth Platform，然後選取「用戶端」。
按一下「Create Client」(建立用戶端)。
將用戶端類型設為「Web application」(網頁應用程式)。
輸入新用戶端的名稱。
將網站網址新增至「已授權的 JavaScript 來源」和「已授權的重新導向 URI」。
按一下「建立」，然後等待 5 分鐘再繼續。

完成上述步驟後，您會取得以下格式的用戶端 ID：

123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com

在 chat-messenger 網頁元件的 oauth-client-id 屬性中提供這項資訊。

建構專屬驗證 API

建立專屬 API，處理使用者驗證和授權，並傳回有權在應用程式中呼叫 runSession 的 Google 存取權杖或已簽署的 JWT。

如要瞭解如何使用 CX Agent Studio API，請參閱「API 存取權」。

網頁小工具 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

限制