ウェブ ウィジェット

ウェブ ウィジェットは、ウェブベースのクライアントです。ウェブ アプリケーションやモバイル アプリケーションで使用して、ユーザーがチャットや音声でエージェント アプリケーションとやり取りできるようにします。このガイドでは、概要と設定手順について説明します。

ウィジェットを開くと、画面右下のフローティング ダイアログ ウィンドウとして表示したり、メイン コンテンツの横のパネルとして表示したり、会話に集中できるように拡張ダイアログ モードで開いたりできます。

アーキテクチャ図

制限事項

現在、リッチ コンテンツの回答は英語のみをサポートしています。

ウェブ ウィジェットを設定する

ウィジェットをウェブサイトに埋め込むには:

  1. エージェント ビルダーの上部にある [デプロイ] をクリックします。
  2. [チャンネルを作成] または [新しいチャンネル] をクリックします。
  3. チャネル タイプとして [ウェブ ウィジェット] を選択します。
  4. チャンネルの名前を入力します。
  5. エージェント アプリケーションのバージョンを選択または作成します。
  6. カラーテーマやエクスペリエンス タイプ（チャット、通話、混合）など、その他の設定を行います。
  7. [チャンネルを作成] をクリックして、デプロイコードを生成します。
  8. ウェブサイトの HTML にデプロイ コードを追加します。
  9. エンドユーザーの認証を設定します。認証を構成せずに変更されていない埋め込みコードを使用すると、ウィジェットに警告が表示されます。オプションと設定の詳細については、認証を構成するをご覧ください。

ウィジェットをウェブサイトに埋め込む

ウィジェットをウェブサイトに追加するには、次の 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/ces-console/fast/chat-messenger/prod/v1/chat-messenger.js"></script>

  <!-- Chat Messenger CSS -->
  <link rel="stylesheet" href="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/themes/chat-messenger-default.css">

  <!-- Optional responsive styling  -->
  <!-- <link rel="stylesheet" href="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/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,
          },
        }),
      );
    });
  </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>

セキュリティ上の考慮事項

ウィジェットをカスタム要素（<chat-messenger>）としてウェブサイトに直接埋め込むと、ウィジェットはホストページのシャドー DOM で実行されます。デフォルトでは厳格なサンドボックス化（iframe など）は適用されません。

ウィジェットはアプリケーションとウィンドウのオリジンを共有するため:

  • 共有ストレージへのアクセス: ウィジェットのカスタム コンポーネント内で実行されるスクリプトは、ホストページの window.sessionStorage と window.localStorage にアクセスできます。これには、ウィジェット自体が保存する認証トークンや機密性の高いセッション データが含まれます。
  • クロスサイト スクリプティング（XSS）: カスタム コンポーネント コードまたはリッチ コンテンツ ペイロードにサニタイズされていない入力が含まれている場合、それらが悪用されて、メイン アプリケーションのコンテキストで任意の JavaScript が実行される可能性があります。

アプリケーションとユーザーのデータのセキュリティを維持するには、次のことを行う必要があります。

  1. カスタムコードのサニタイズ: カスタム コンポーネントまたはペイロードで使用されるすべてのカスタム JavaScript と HTML が厳密にサニタイズされていることを確認します。
  2. 入力を検証する: 外部ソース（エージェントの回答を含む）からウィジェットに渡されるすべてのデータを信頼できないものとして扱います。
  3. ハンドルの分離: セキュリティ要件でチャット ウィジェットとアプリケーションのデータ間の厳格な分離が義務付けられている場合は、独自のサンドボックス（制御および分離するコンテナにウィジェット コンポーネントをラップするなど）を実装する必要があります。

人間のエージェントへのハンドオフを構成する

ウィジェットを構成する前に、必要なリソースが作成され、WebChat Proxy のデプロイが完了していることを確認してください。

  1. エスカレーション番号を設定します。
    1. プロジェクトの PhoneNumber リソースを作成します。
      1. エージェント アプリケーション用に構成された有効な会話プロファイルを使用します。
      2. 会話プロファイルを PhoneNumber に関連付けて、システムが人間のエスカレーションを処理できるようにします。
    2. 手順に沿って WebChat Proxy を設定します。

  2. Webchat クライアントの構成:

    1. 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 文字列 ボットの「思考中」にレンダリングされる画像の URL
chat-title-icon chat-messenger-container 文字列 チャットの上部に表示される画像の URL（ブランド画像）
chat-title chat-messenger-container 文字列 チャットのタイトルのテキスト
render-mode chat-messenger 文字列（「slide-in」または「slide-over」） ページの他の部分に対するチャット ダイアログのレンダリング モード。オプションは「スライドオーバー」または「スライドイン」です。指定しない場合、クライアントが位置を指定できます。render-mode をサポートするには、スタイルが必要です。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%）
Utility
--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

Shape & Elevation Tokens

これらのトークンは、チャット コンポーネントの角の丸みと視覚的な奥行き（影）を制御します。

プロパティ 説明 デフォルト
--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 メインのチャット ウィンドウとウィジェット コンテナの角の半径。 28px
--chat-messenger-shape--corner-fully-rounded ボタンやピル型のインタラクティブ要素に使用され、端が完全に円形になるようにします。 100px
--chat-messenger-elevation フローティング要素とメインのチャット コンポーネントに適用される box-shadow。 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
タイトル（中） ウィジェット内のセクションの見出し。
--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
Body large 長い説明文。
--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
Body medium 標準 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
Body small 二次的なメタデータと説明。
--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 アクセス トークンを使用して実現されます。

このトークンに関連付けられている ID（エンドユーザーまたはサービス アカウント）には、エージェントを操作するために必要な IAM 権限が必要です。

残りのサブセクションでは、認証を設定する方法について説明します。

トークン ブローカーを設定する

トークン ブローカーは、 Google Cloud プロジェクトで実行され、ユーザーが所有するサービス アカウントに代わってアクセス トークンを生成するウェブ サービスです。ウェブ ウィジェットは、会話の開始時にトークン ブローカーの URL を自動的に呼び出して、CX Agent Studio API との通信時に使用する新しいトークンを取得できます。

トークン ブローカーは、Google ホスト型とセルフホスト型の 2 つの方法で設定できます。

Google ホスティング

Google が提供するトークン ブローカーを使用して、チャット ウィジェットへの公開アクセスを許可します。

  • デプロイとウィジェットの構成を作成するときに、公開アクセスを有効にします。必要に応じて、オリジンと reCAPTCHA のチェックを有効にします（スプーフィングと不正使用を防ぐためにおすすめします）。
  • チャット ウィジェットは、Google が提供するトークン ブローカーからセッション スコープ トークンをリクエストし、チャット セッションで使用します。

Self-hosted

セルフホスト型トークン ブローカーを設定する手順は次のとおりです。

  • プロジェクトにサービス アカウントを作成し、Customer Engagement Suite クライアント ロールを付与します。
  • 提供されているトークン ブローカーのサンプルコードを使用して、Cloud Run functions の関数をデプロイします。

詳しい手順については、オープンソース リポジトリをご覧ください。

OAuth2 を設定する

OAuth2 クライアントを使用すると、ウェブ ウィジェットでエンドユーザーの認証フローを開始できます。通常、これはダイアログ ウィンドウが開かれ、ユーザーが Google アカウント（または他のプロバイダ）にログインして、ユーザーに代わって操作を行うためのトークンがウェブ ウィジェットに渡されることを意味します。

エンドユーザーがエージェントを使用する前にログインすることを要求する場合に選択します。ユーザー認証情報は、エージェント アプリケーションへのアクセスに使用されます。

主な手順は次のとおりです。

  • Google Cloud コンソールで、[Google Auth Platform] に移動して [クライアント] を選択します。
  • [クライアントを作成] をクリックします。
  • クライアント タイプとして [ウェブ アプリケーション] を選択します。
  • 新しいクライアントの名前を入力します。
  • 承認済みの JavaScript 生成元と承認済みのリダイレクト URI の両方にウェブサイトの URL を追加します。
  • [作成] をクリックし、5 分待ってから続行します。

手順を完了すると、次のような形式のクライアント ID が取得されます。

123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com

これは、chat-messenger ウェブ コンポーネントの oauth-client-id 属性で指定します。

独自の認証 API を構築する

エンドユーザーの認証と認可を処理する独自の API を構築します。この API は、アプリで runSession を呼び出す権限を持つ Google アクセス トークンまたは署名付き JWT を返します。

CX Agent Studio API の使用については、API アクセスをご覧ください。