Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

ヘッドレスウェブ SDK ガイド

ヘッドレスウェブ SDK を使用すると、ニーズに合わせて企業のサポートエクスペリエンスを柔軟に拡張、カスタマイズできます。これには、おなじみのウェブ SDK の機能がすべて含まれており、それらをサポートする UI と UX を構築する機能が提供されています。

ヘッドレスウェブ SDK をインストールして使用するには、組織のウェブ開発チームのサポートが必要です。統合を成功させ、最適なパフォーマンスを実現するには、資格のある担当者を関与させることをおすすめします。

ソフトウェア開発の文脈では、「ヘッドレス」とは、フロントエンドのプレゼンテーションレイヤ（「ヘッド」）がバックエンドのロジックと機能から分離された分離型アーキテクチャを指します。ヘッドレスアーキテクチャでは、バックエンド（「ヘッドレス」部分とも呼ばれます）が、その機能とサービスを使用できる 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。デバイス全体の画面共有セッションを確認する場合。
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`	初期化時にヘッドレス SDK によって決定されるデバイスの ID。
`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 オプションを使用すると、任意の Key-Value ペアデータをウェブ 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
}

外部 chatbot への転送

他のチャットプロバイダの履歴とやり取りを保持したい場合があります。これを行うには、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
}

リファレンス実装

ウェブ SDK のリファレンス実装については、GitHub の ccaas-web-headless-sdk-sample をご覧ください。

このリポジトリには、CCAI Platform Web Headless SDK を使用して構築されたチャットアプリケーションのデモが含まれています。このサンプルでは、Node.js バックエンドが安全な認証と構成の配信を処理し、純粋な JavaScript フロントエンドがチャットユーザーインターフェースを提供する基本的なクライアントサーバーアーキテクチャを示します。