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

無頭網頁 SDK 指南

無頭網頁 SDK 可讓您根據需求，彈性擴充及自訂公司的支援體驗。其中包含所有常見的網頁 SDK 功能，並提供建構 UI 和 UX 的功能，以支援這些功能。

安裝及使用無標題網頁 SDK 時，需要貴機構網頁開發團隊的支援。為順利完成整合並達到最佳效能，Google 建議您請合格人員參與。

在軟體開發領域，「無頭」是指前端呈現層 (即「頭」) 與後端邏輯和功能分離的解耦架構。在無頭架構中，後端 (也稱為「無頭」部分) 會提供 API，讓您使用其功能和服務。

例如自訂工作流程自動化。當使用者發起即時通訊時，系統會觸發 on("chat.message") 事件。您可以根據收到的特定即時通訊訊息，定義自訂自動化觸發條件。舉例來說，如果使用者在即時通訊中輸入「Escalate」，事件處理常式可以自動將即時通訊工作階段轉給更高層級的支援團隊，迅速處理重大問題。

本指南會逐步說明 SDK 的安裝程序、整合功能和使用方式。如要瞭解如何使用 API，請參閱無頭網頁 SDK API 說明文件。如要查看可用的活動清單，請前往活動頁面。

安裝無頭網頁 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>

使用無頭網頁 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 的記錄功能，請在網頁應用程式中加入下列程式碼，匯入 Logger 和 consoleLoggerHandler：

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

您可以使用無頭網頁 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. For confirming a full device Screen Share session.
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 選項，將任意鍵/值組合資料傳遞至網頁 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 Platform Web Headless SDK 建構的即時通訊應用程式範例。這個範例展示基本的用戶端/伺服器架構，其中 Node.js 後端會處理安全驗證和設定傳送作業，而純 JavaScript 前端則提供即時通訊使用者介面。