> 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/serve/web-chat-sdk/web-chat-context-data.md).

# ページの Context を注入する

embed SDK の auth.contextData を使用して、ページのコンテキスト（商品 ID、チケット番号、ユーザー識別子など）を Agent の LLM System Prompt に注入します

Web Chat をウェブサイトに埋め込んだ場合、Agent はデフォルトでは「ユーザーが現在どのページにいて、何を見ているか」を把握していません。`contextData` を使用すると、埋め込み側が embed 設定で任意のキーと値のデータを渡せます。このデータは**各メッセージとともに自動送信され、LLM System Prompt に注入される**ため、Agent は会話やツール呼び出し（Tool / Function Calling）で直接使用できます。

主な用途：

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

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

## 1. クイックスタート <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: {                 // 任意のキーと値を LLM system prompt に注入します
        productId: '3021',
        productName: 'ワイヤレスノイズキャンセリングヘッドホン',
      },
    },
  }
</script>
<script src="https://yourdomain.com/js/embed.min.js"></script>
```

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

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

Agent は回答やツール呼び出しでこれらの値を直接参照できます。

## 2. 動作の仕組み <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 がコンテキストを読み取ります"]
  E --> F["会話への回答 /<br/>API ツール呼び出しの引数に値を設定します"]
```

主な特徴：

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

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

用途がまったく異なるため、混同しないでください：

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

AI に値を「認識」させたい場合（API ツールの引数に設定させる場合など）は `contextData` を使用してください。AI が「どのナレッジドキュメントを検索できるか」を制限したい場合は、[ナレッジ管理の権限（Query Metadata）](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) を使用してください。

## 3. データのルールと制限 <a href="#data-rules" id="data-rules"></a>

SDK は渡された `contextData` を次のルールに従ってサニタイズします：

| ルール           | 動作                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------- |
| 値の型           | `string` に対応します。`number` / `boolean` は自動で文字列に変換します。それ以外の型（object、array、null など）は、そのキーを破棄します |
| キー数の上限        | 最大 **50 組**のキーと値に対応し、超過分は破棄します                                                              |
| 予約済みキー        | 既存のシステム metadata と競合するキーは破棄します（下記の一覧を参照してください）                                              |
| 空のオブジェクト `{}` | サニタイズ後に空の場合は未指定と同じ扱いとなり、metadata にカスタムキーは含まれません                                             |
| サニタイズの処理      | エラーを出さずに処理し、メッセージの送信を妨げません                                                                  |

**予約済みキーの一覧**（システムフィールドの上書きを防ぐため、渡された場合は破棄します）：

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

{% hint style="warning" %}
**セキュリティは埋め込み側の責任です**：`contextData` は埋め込みページから注入され、MaiAgent はその送信元を署名や暗号化によって検証しません。エンドユーザーに知られるべきでない機密データは注入しないでください（値は LLM prompt に入り、AI が回答で繰り返す可能性があります）。識別性のあるデータ（身分証明書番号など）の場合、埋め込み側で送信元の信頼性（署名付きの QR code / セッションなど）を確保し、個人情報保護の要件を満たしてください。
{% endhint %}

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

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

* **更新**：`MaiAgent.auth.setup()` を再度呼び出すと、現在の `contextData` を**全体ごと上書き**します（マージはしません）
* **クリア**：`contextData` を指定せずに `auth.setup()` を呼び出すと、以前に注入した値をクリアします。`MaiAgent.auth.signOut()` も同時に値をクリアし、別のユーザーにデータが残るのを防ぎます

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

// 商品ページを離れる際、コンテキストをクリアします（contextData を省略するとクリアされます）
MaiAgent.auth.setup({
  sourceId: 'user-12345',
})
```

## 5. 活用例 <a href="#examples" id="examples"></a>

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

シナリオ：Agent に「商品検索」API ツール（商品 ID で商品詳細を取得するツール）を設定しています。Web Chat を商品詳細ページに埋め込み、ユーザーが「これは私に合っていますか？」と質問したときに、Agent が聞き返さず、現在の商品について直接回答するようにします。

```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" %}
**ロール指示によるガイドを併用することを推奨します**：ツールでコンテキストを実際に使用するかどうかは、LLM が prompt に基づいて判断します。Agent の[ロール指示](/tech/ja/advanced-genai-tech/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 code / URL パラメータ <a href="#example-identifier-injection" id="example-identifier-injection"></a>

シナリオ：QR code またはパラメータ付きリンクからサービスページを開き、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 に自動で設定します。

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

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

1. ブラウザーの開発者ツールで Network タブを開き、WebSocket メッセージを確認します。送信メッセージのペイロード内の `metadata` に、注入したキーが含まれている必要があります
2. Agent に「私の productId を知っていますか？」と直接質問します。注入に成功していれば、AI は直接回答できます
3. 管理画面の会話監視で、そのメッセージに実際に使用された prompt を確認します。`Contact custom attributes` ブロックが含まれている必要があります

**よくある問題**

| 問題                         | 原因と対処                                                                |
| -------------------------- | -------------------------------------------------------------------- |
| contextData がまったく有効になりません  | `auth.sourceId` を指定しているか確認してください（必須です。省略すると `auth.setup()` は実行されません） |
| 一部のキーが消えます                 | 予約済みキーを使用していないか、値が未対応の型（object / array）ではないか、50 組の上限を超えていないか確認してください |
| 再読み込み後にコンテキストが消えます         | 想定どおりの動作です。データベースには保存しないため、ページの読み込みごとに再注入する必要があります                   |
| AI がコンテキストを使用してツールを呼び出しません | ロール指示で明確にガイドしてください（上記の例 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.