> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/api-integration/web-chat-sdk/web-chat-context-data.md).

# ページ Context の注入

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

主な活用例：

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

{% hint style="info" %}
`contextData` は embed 設定の `auth` 配下にあるため、`auth.sourceId`（ユーザー識別子）を併せて指定する必要があります。auth の仕組みの詳細は [Web Chat 埋め込みと SDK](/tech/ja/api-integration/web-chat-sdk.md#identify-users) をご参照ください。
{% endhint %}

## 一、クイックスタート <a href="#quickstart" id="quickstart"></a>

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

```html
<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 アシスタントは回答やツール呼び出しでこれらの値を直接参照できるようになります。

## 二、動作の仕組み <a href="#how-it-works" id="how-it-works"></a>

```mermaid
flowchart LR
  A["埋め込みページの config:<br/>auth.contextData"] --> B["embed SDK<br/>auth.setup()"]
  B --> C["各メッセージの<br/>message.metadata"]
  C --> D["バックエンドが metadata を統合し<br/>System Prompt に注入"]
  D --> E["LLM が context を読み取る"]
  E --> F["会話の回答／<br/>API ツール呼び出しにパラメータを反映"]
```

重要な特性：

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

### queryMetadata との違い <a href="#context-data-vs-query-metadata" id="context-data-vs-query-metadata"></a>

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

|            | `auth.contextData`                        | `queryMetadata`                  |
| ---------- | ----------------------------------------- | -------------------------------- |
| 用途         | ページの context を AI に伝える（System Prompt に入る） | ナレッジベースの検索範囲を制御する（RAG 権限フィルタリング） |
| LLM から見えるか | ✅ System Prompt に含まれる                     | ❌ prompt に入らず、ツールにも渡されない         |
| 適した用途      | 商品 ID、チケット番号、ユーザー識別子                      | ナレッジ管理権限、ドキュメントのアクセス範囲           |

AI にある値を「知らせたい」場合（API ツールのパラメータに反映させたい場合など）は `contextData` を、AI が「どのナレッジドキュメントを検索できるか」を制限したい場合は [ナレッジ管理権限（Query Metadata）](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) をご利用ください。

## 三、データルールと制限 <a href="#data-rules" id="data-rules"></a>

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`

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

## 四、更新とクリア <a href="#update-and-clear" id="update-and-clear"></a>

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

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

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

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

## 五、活用例 <a href="#examples" id="examples"></a>

### 1. EC の商品ページ：AI が現在の商品に基づいて回答 <a href="#example-product-page" id="example-product-page"></a>

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

```html
<!-- 商品詳細ページ、例：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` で「商品検索」ツールを呼び出して商品詳細を取得し、そのまま回答します。「どの商品についてのご質問ですか？」と聞き返す必要はありません。

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

### 2. カスタマーサポートシステム：チケットのコンテキストを付与 <a href="#example-support-ticket" id="example-support-ticket"></a>

```jsx
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 パラメータ <a href="#example-identifier-injection" id="example-identifier-injection"></a>

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

```jsx
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 に自動で設定します。

## 六、検証とトラブルシューティング <a href="#troubleshooting" id="troubleshooting"></a>

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

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

**よくある問題**

| 問題                          | 原因と対処                                                                        |
| --------------------------- | ---------------------------------------------------------------------------- |
| contextData がまったく有効にならない    | `auth.sourceId` が指定されているか確認してください（必須。欠けている場合 `auth.setup()` は実行されません）        |
| 一部の key が消える                | 予約 key を使用していないか、value が非サポートの型（object / array）でないか、50 組の上限を超えていないかを確認してください |
| 再読み込み後に context が消える        | 想定どおりの動作です。データベースには保存されないため、ページ読み込みのたびに再注入する必要があります                          |
| AI が context を使ってツールを呼び出さない | ロール指示で明確に誘導してください（上記の例 1 の hint を参照）                                         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/tech/ja/api-integration/web-chat-sdk/web-chat-context-data.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.