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

ウェブウィジェット

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

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

制限事項

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

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

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

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

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

ウィジェットをウェブサイトに追加するには、次の 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,
          },
          // Automatically prompt the agent to start the conversation with a greeting.
          enableWelcomeEvent: 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>

会話を自動的に開始する

デフォルトでは、チャットウィジェットはユーザーが最初のメッセージを送信するのを待ちます。エージェントが挨拶で自動的に会話を開始するようにするには、chatSdk.prebuilts.ces.createContext 関数で enableWelcomeEvent: true を設定します。

このオプションを有効にすると、チャットセッションの初期化時に、ウィジェットからエージェントに welcome イベントが自動的に送信されます。エージェントは、構成された挨拶でこのイベントに応答します。

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

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

ウィジェットはアプリケーションとウィンドウのオリジンを共有するため、次のようになります。

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

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

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

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

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

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

Webchat クライアントの構成:

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	string（「slide-in」または「slide-over」）	ページの他の部分に対するチャットダイアログのレンダリングモード。オプションは「スライドオーバー」または「スライドイン」です。指定しない場合、クライアントが位置を指定できます。レンダリングモードをサポートするには、スタイルが必要です。`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

シェイプと標高のトークン

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

プロパティ	説明	デフォルト
--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 が提供するトークンブローカーからセッションスコープトークンをリクエストし、チャットセッションで使用します。

セルフホスト

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

プロジェクトにサービスアカウントを作成し、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 アクセスをご覧ください。

ウェブ ウィジェット コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。