ページ Context の注入

embed SDK の auth.contextData を通じて、ページの context（商品 ID、チケット番号、ユーザー識別子など）を AI アシスタントの LLM System Prompt に注入します

Web Chat をお客様のウェブサイトに埋め込んだ場合、AI アシスタントはデフォルトでは「ユーザーが今どのページにいて、何を見ているのか」を把握していません。contextData を使うと、埋め込み側が embed 設定で任意の key-value データを渡せます。このデータはメッセージごとに自動送信され、LLM System Prompt に注入されるため、AI アシスタントは会話やツール呼び出し（Tool / Function Calling）でそのまま利用できます。

主な活用例：

EC の商品ページ：productId を注入すると、アシスタントは「どの商品についてのご質問ですか？」と聞き返すことなく、その商品 ID で「商品検索」API ツールを呼び出して回答できます
カスタマーサポートシステム：ticketId や customerId を注入すると、アシスタントはチケットのコンテキストを直接参照してサポートフローを処理できます
医療／フォームサービス：QR コードから読み取った識別子（発行番号など）を注入すると、アシスタントは送信 API の呼び出し時に自動で付与します
会員／金融サービス：会員ランクなどの属性を注入すると、アシスタントは属性に応じたパーソナライズ回答を提供できます

contextData は embed 設定の auth 配下にあるため、auth.sourceId（ユーザー識別子）を併せて指定する必要があります。auth の仕組みの詳細は Web Chat 埋め込みと SDK をご参照ください。

一、クイックスタート

埋め込みスクリプトの前の maiagentChatbotConfig に auth.contextData を追加します：

<script>
  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://yourdomain.com/web-chats',
    auth: {
      sourceId: 'user-12345',        // 必須：ユーザーの一意な識別子
      name: '山田太郎',               // 任意：表示名
      contextData: {                 // 任意の key-value、LLM system prompt に注入されます
        productId: '3021',
        productName: 'ワイヤレスノイズキャンセリングイヤホン',
      },
    },
  }
</script>
<script src="https://yourdomain.com/js/embed.min.js"></script>

SDK の読み込みが完了すると auth.setup() が自動実行され、以降ユーザーが送信するすべてのメッセージの metadata にこれらの key-value が付与されます。バックエンドはそれらを次の形式で System Prompt に追加します：

Contact custom attributes:
- productId: 3021
- productName: ワイヤレスノイズキャンセリングイヤホン

AI アシスタントは回答やツール呼び出しでこれらの値を直接参照できるようになります。

二、動作の仕組み

重要な特性：

メッセージごとに送信、データベースには保存されない：contextData はフロントエンドのメモリ上にのみ存在し、各メッセージの payload とともに送信されます。ユーザーがページを再読み込みした後は、埋め込みページから再注入する必要があります（QR コードやセッションなど、ライフサイクルの短いデータに適しています）
会話の全ターンで有効：メッセージごとに送信されるため、AI は会話全体を通じて常に最新の context を取得できます
追加の API 呼び出しなし：既存のメッセージチャネルをそのまま利用するため、追加のパフォーマンス負荷はありません

queryMetadata との違い

両者は用途がまったく異なるため、混同しないようご注意ください：

auth.contextData

queryMetadata

用途

ページの context を AI に伝える（System Prompt に入る）

ナレッジベースの検索範囲を制御する（RAG 権限フィルタリング）

LLM から見えるか

✅ System Prompt に含まれる

❌ prompt に入らず、ツールにも渡されない

適した用途

商品 ID、チケット番号、ユーザー識別子

ナレッジ管理権限、ドキュメントのアクセス範囲

AI にある値を「知らせたい」場合（API ツールのパラメータに反映させたい場合など）は contextData を、AI が「どのナレッジドキュメントを検索できるか」を制限したい場合はナレッジ管理権限（Query Metadata）をご利用ください。

三、データルールと制限

SDK は渡された contextData にサニタイズ（sanitize）を行います。ルールは次のとおりです：

ルール

動作

value の型

string をサポート。number / boolean は自動で文字列に変換。その他の型（object、array、null など）はその key ごと破棄されます

key 数の上限

最大 50 組の key-value。超過分は破棄されます

予約 key

システム既存の metadata と衝突する key は破棄されます（下記リスト参照）

空オブジェクト {}

サニタイズ後に空となり、未指定と同様に扱われ、metadata にカスタム key は含まれません

サニタイズ方式

サイレントに処理され、エラーは発生せず、メッセージ送信もブロックされません

予約 key リスト（渡しても破棄されます。システムフィールドの上書きを防ぐため）：

contact_name、timezone、latitude、longitude、accuracy、locale、language、working_directory

セキュリティは埋め込み側の責任です：contextData は埋め込みページから注入されるものであり、MaiAgent はその出所に対する署名や暗号化の検証を行いません。エンドユーザーに知られてはならない機密データは注入しないでください（値は LLM prompt に入るため、AI が回答内で復唱する可能性があります）。識別性のあるデータ（マイナンバーなど）を扱う場合は、埋め込み側で出所の信頼性を担保し（署名付き QR コード／セッションなど）、個人情報保護の法令要件に準拠してください。

四、更新とクリア

contextData のライフサイクルは auth.setup() に従います：

更新：MaiAgent.auth.setup() を再度呼び出すと、現在の contextData が丸ごと上書きされます（マージではありません）
クリア：auth.setup() で contextData を指定しなければ、以前注入した値がクリアされます。MaiAgent.auth.signOut() でも併せてクリアされ、別の身元へのデータ残留を防ぎます

// SPA でページを切り替える際、context を新しい商品に更新
MaiAgent.auth.setup({
  sourceId: 'user-12345',
  contextData: {
    productId: '4552',
    productName: 'ポータブル Bluetooth スピーカー',
  },
})

// 商品ページを離れる際、context をクリア（contextData を指定しなければクリアされます）
MaiAgent.auth.setup({
  sourceId: 'user-12345',
})

五、活用例

1. EC の商品ページ：AI が現在の商品に基づいて回答

シナリオ：AI アシスタントに「商品検索」API ツール（商品 ID で商品詳細を照会）を設定しています。Web Chat は商品詳細ページに埋め込まれており、ユーザーが「これは私に合いますか？」と質問したとき、アシスタントが聞き返すことなく、現在の商品についてそのまま回答することを想定しています。

<!-- 商品詳細ページ、例：product_detail.php?id=3021 -->
<script>
  // ページから現在の商品情報を取得（サイトの実装方法に合わせて取得してください）
  const productId = new URLSearchParams(location.search).get('id')

  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://yourdomain.com/web-chats',
    auth: {
      sourceId: 'visitor-' + productId,   // 会員／訪問者の識別ロジックに合わせて設定
      contextData: {
        productId,                         // AI が「商品検索」ツールを呼び出す際にこの ID を使用
        productName: document.querySelector('.product-title')?.textContent ?? '',
      },
    },
  }
</script>
<script src="https://yourdomain.com/js/embed.min.js"></script>

ユーザーが「このモデルのバッテリーはどのくらい持ちますか？」と質問したとき、System Prompt にはすでに productId: 3021 が含まれているため、AI は id=3021 で「商品検索」ツールを呼び出して商品詳細を取得し、そのまま回答します。「どの商品についてのご質問ですか？」と聞き返す必要はありません。

ロール指示による誘導を推奨：context がツールで実際に使用されるかどうかは、LLM が prompt に基づいて判断します。AI アシスタントのロール指示で明確に誘導すると安定性が大きく向上します。例：「Contact custom attributes に productId がある場合、ユーザーはその商品を閲覧中です。この ID を優先的に使って商品検索ツールを呼び出して回答し、ユーザーに聞き返さないでください。」

2. カスタマーサポートシステム：チケットのコンテキストを付与

window.maiagentChatbotConfig = {
  webChatId: 'your-web-chat-id',
  baseUrl: 'https://yourdomain.com/web-chats',
  auth: {
    sourceId: currentUser.id,
    name: currentUser.displayName,
    contextData: {
      ticketId: 'T-2026-0142',
      customerId: currentUser.id,
      plan: 'enterprise',
    },
  },
}

ユーザーが会話を開始した時点で、AI はすでにチケット番号や顧客のプランランクを把握しているため、顧客に改めて説明してもらうことなく、そのチケットの後続フローを直接処理できます。

3. 識別子の注入：QR コード／URL パラメータ

シナリオ：サービスページが QR コードやパラメータ付きリンクから開かれ、AI が送信 API を呼び出す際に識別子を自動で付与する必要がある場合です。

const params = new URLSearchParams(location.search)

window.maiagentChatbotConfig = {
  webChatId: 'your-web-chat-id',
  baseUrl: 'https://yourdomain.com/web-chats',
  auth: {
    sourceId: params.get('sessionId'),
    contextData: {
      formId: params.get('formId'),       // フォーム／伝票の識別子
      userRef: params.get('userRef'),     // ユーザー参照番号
    },
  },
}

AI がユーザーをフロー完了まで誘導した後、送信ツール（SubmitAnswers など）を呼び出す際に、formId と userRef を request body に自動で設定します。

六、検証とトラブルシューティング

contextData が有効になっているかを確認するには？

ブラウザの開発者ツールの Network タブで WebSocket メッセージを観察します。送信されたメッセージの payload の metadata に、注入した key が含まれているはずです
AI アシスタントに直接「私の productId を知っていますか？」と質問します。注入に成功していれば、AI はそのまま回答できます
管理コンソールの会話モニタリングで、そのメッセージが実際に使用した prompt を確認します。Contact custom attributes セクションが含まれているはずです

よくある問題

問題

原因と対処

contextData がまったく有効にならない

auth.sourceId が指定されているか確認してください（必須。欠けている場合 auth.setup() は実行されません）

一部の key が消える

予約 key を使用していないか、value が非サポートの型（object / array）でないか、50 組の上限を超えていないかを確認してください

再読み込み後に context が消える

想定どおりの動作です。データベースには保存されないため、ページ読み込みのたびに再注入する必要があります

AI が context を使ってツールを呼び出さない

ロール指示で明確に誘導してください（上記の例 1 の hint を参照）

前へMaiGPT モード埋め込み

次へAPI ツールエンジニアリングガイド

最終更新 21 日前

役に立ちましたか？