無頭網頁 SDK 指南

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

如要安裝及使用無頭網頁 SDK，請向貴機構的網頁程式開發人員團隊尋求協助。為確保整合順利並達到最佳成效，Google 建議您安排合格人員參與。

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

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

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

注意： Google 僅支援最新三個子版本的無頭網頁 SDK。網站必須使用下列其中一個版本的無頭網頁 SDK，才能獲得支援。

安裝 Headless Web SDK

如要安裝無頭網頁 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[];
    template?: 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
  // Widget-only - the following template + root options have no effect in the Headless SDK:
  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[]
  // Headless consent callbacks
  confirmSession?: () => Promise<boolean>
  confirmRemoteControl?: () => Promise<boolean>
  confirmFullDevice?: () => Promise<boolean>

  // Headless session-control callbacks
  showSessionControls?: () => void
  hideSessionControls?: () => void

  // Existing CobrowseIO instance
  instance?: any
}

自訂範本

您可以使用上述程式碼範例中的 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"
}

Headless 用戶端 API

import { Client } from "@ujet/websdk-headless"

注意： 錯誤處理 - 大多數 Client 方法會將 HTTP 錯誤傳播為擲回的例外狀況。除非方法說明文件另有註明，否則請將呼叫包裝在 try/catch 中。

活動

如需所有發出事件的清單，請參閱「事件」頁面。

屬性

名稱	說明
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)

參考實作

如需網頁 SDK 的參考實作，請參閱 GitHub 上的 ccaas-web-headless-sdk-sample。

這個存放區包含使用 CCAI Platform Web Headless SDK 建構的即時通訊應用程式示範。這個範例展示了基本的用戶端-伺服器架構，其中 Node.js 後端負責處理安全驗證和設定傳遞，而純 JavaScript 前端則提供對話使用者介面。