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

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

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

ソフトウェア開発の文脈では、「ヘッドレス」とは、フロントエンドのプレゼンテーションレイヤ（「ヘッド」）がバックエンドのロジックと機能から分離された分離型アーキテクチャを指します。ヘッドレスアーキテクチャでは、バックエンド（「ヘッドレス」部分とも呼ばれます）が、その機能とサービスを使用できる API を提供します。

たとえば、カスタムワークフローの自動化などです。エンドユーザーがチャットを開始すると、on("chat.message") イベントがトリガーされます。受信した特定のチャットメッセージに基づいて、カスタム自動化トリガーを定義できます。たとえば、エンドユーザーがチャットで「Escalate」と入力すると、イベントハンドラがチャットセッションを上位レベルのサポートチームに自動的にエスカレーションし、重大な問題に迅速に対応できます。

このガイドでは、SDK のインストールプロセス、統合機能、使用方法について説明します。API の使用方法について詳しくは、ヘッドレスウェブ SDK API ドキュメントをご覧ください。使用可能なイベントの一覧については、イベントのページをご覧ください。

ヘッドレスウェブ SDK をインストールする

ヘッドレスウェブ SDK をインストールするには、プロジェクトで次のコードスニペットを使用します。

npm install @ujet/websdk-headless --save

ヘッドレスウェブ SDK を使用する

ヘッドレス Web SDK を使用するには、提供されているサンプルコードを使用します。

import { Client } from "@ujet/websdk-headless"
const client = new Client({ ... })

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;
  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"
}

カスタムデータ構成

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 フロントエンドがチャットユーザーインターフェースを提供する基本的なクライアントサーバーアーキテクチャを示しています。

ヘッドレス ウェブ SDK ガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ヘッドレス ウェブ SDK をインストールする

ヘッドレス ウェブ SDK を使用する