> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timothe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ユーザーコンテキストの引き渡し

> エージェント起動時にユーザー情報やページ固有の情報を渡し、ゲートの事前入力やセッションの文脈として利用する方法

エージェントを Web サイトに埋め込むとき、ページ側が持っているユーザー情報やページ固有の情報を **ユーザーコンテキスト** として引き渡せます。

たとえば、会員向けページでログイン済みユーザーのメールアドレスや契約プランを渡したり、記事ページでカテゴリや閲覧中の商品 ID を渡したりできます。渡された値はセッションの context として保存され、ゲートの事前入力や Webhook 連携などで利用できます。

## 渡せる情報の例

| キー             | 値の例                | 用途                     |
| -------------- | ------------------ | ---------------------- |
| `email`        | `user@example.com` | ゲートのメールアドレス入力を事前入力する   |
| `company`      | `株式会社サンプル`         | 会社名をセッションに紐づける         |
| `plan`         | `enterprise`       | 契約プランに応じた会話や分岐に使う      |
| `accountId`    | `acct_123`         | 自社システム上のアカウント ID と紐づける |
| `pageCategory` | `pricing`          | どのページ文脈で起動されたかを渡す      |

キー名は任意です。ゲートのフォームフィールドと連動させたい場合は、ダッシュボード側で設定したフィールドのキーと同じ名前にしてください。

## `data-turnint-context` で渡す

埋め込み要素に `data-turnint-context` 属性を追加し、JSON 文字列を指定します。

```html theme={null}
<div
  data-turnint-id="pub_xxxxxxxxxxxxxxxx"
  data-turnint-type="inline"
  data-turnint-context='{"email":"user@example.com","company":"株式会社サンプル","plan":"enterprise"}'
></div>
```

ボタンでフルスクリーン表示する場合も同じです。

```html theme={null}
<button
  data-turnint-id="pub_xxxxxxxxxxxxxxxx"
  data-turnint-type="fullscreen"
  data-turnint-context='{"email":"user@example.com","accountId":"acct_123"}'
>
  AI と資料を読む
</button>
```

<Note>
  `data-turnint-context` の値は JSON として解釈されます。HTML 属性内では、JSON 全体をシングルクォートで囲むと書きやすくなります。
</Note>

<Note>
  embed script はページ内で 1 度だけ読み込みます。UI 言語は script 側の `data-turnint-locale` で指定してください。
</Note>

## `application/json` の script で渡す

属性に長い JSON を直接書きたくない場合は、`data-turnint-context` を付けた `application/json` の script block を使えます。

```html theme={null}
<div data-turnint-id="pub_xxxxxxxxxxxxxxxx" data-turnint-type="inline"></div>

<script data-turnint-context type="application/json">
  {
    "email": "user@example.com",
    "company": "株式会社サンプル",
    "plan": "enterprise",
    "pageCategory": "pricing"
  }
</script>
```

同じページに複数の `data-turnint-context` がある場合は、後に出現した値が同じキーを上書きします。

<Warning>
  `application/ld+json` は対象外です。構造化データや SEO 用の JSON-LD を誤ってユーザーコンテキストに取り込まないよう、コンテキスト引き渡しには `type="application/json"` を使ってください。
</Warning>

## ゲートとの関係

ユーザーコンテキストのキーがゲートのフォームフィールドのキーと一致する場合、その値はゲートの型に沿って検証・整形されます。

たとえば、ゲートに `email` というメールアドレス項目がある場合、`data-turnint-context` で渡した `email` はメールアドレスとして検証されます。`score` のような数値項目であれば、数値として扱える値に整形されます。

ゲートに存在しないキーも破棄されず、セッションの context に保持されます。

```json theme={null}
{
  "email": "user@example.com",
  "company": "株式会社サンプル",
  "plan": "enterprise"
}
```

上記のうち、ゲートに `email` と `company` がある場合はその 2 つがゲートの定義に沿って扱われ、`plan` は追加のセッションコンテキストとして保持されます。

<Info>
  ゲートが設定されていないエージェントでも、`data-turnint-context` で渡した値はセッションの context に保存されます。
</Info>

## URL query parameter との優先順位

URL query parameter は、ゲートのフォームフィールドと一致するキーだけを事前入力に使います。`autoconfirm=true` はゲートの自動確認用の制御フラグとして扱われますが、セッションの context には保存されません。

ゲートに存在しない query parameter はユーザーコンテキストとしては取り込まれません。ページ固有の情報や任意のキーをセッション context に渡したい場合は、`data-turnint-context` または `application/json` の script block を使ってください。

同じゲートフィールドのキーが複数の場所に存在する場合、次の順序で後の値が優先されます。

```txt theme={null}
外部サービス連携 < ページ上のフォーム入力 < 保存済みコンテキスト < data-turnint-context < URL query parameter（ゲートフィールド一致時のみ）
```

たとえば、ページ上で `data-turnint-context='{"email":"old@example.com"}'` を指定し、URL に `?email=new@example.com` が含まれる場合、最終的な `email` は `new@example.com` になります。

URL query parameter は、メール配信や広告キャンペーンなどでゲート入力を一時的に上書きする用途に向いています。`data-turnint-context` は、ページテンプレートやログイン済みユーザー情報から安定して渡したい値、またはゲートに含まれない追加コンテキストに向いています。

## 自動的に参照されるコンテキスト

embed script は、明示的に指定された `data-turnint-context` や URL query parameter に加えて、同一ページ上で利用できる一部のコンテキストも低い優先度で参照します。これにより、既存のフォームや外部フォームサービスに入力済みの情報を、追加実装を少なく Turnint AI のセッションに引き継げます。

### ページ上のフォーム入力

ページ上の安全なフォーム入力値は、Turnint AI のセッション context として利用されます。次回以降、同じ `name` 属性を持つフォーム項目が空欄の場合は、以前の入力値を復元します。

ページ上のフォーム入力は、既に入力されている値や HubSpot などホストサイト側の prefill を上書きしません。対象になるのは `name` 属性を持つ安全な input / select に限られ、`textarea`、`search`、`password`、`file`、`hidden`、無効化された項目、読み取り専用の項目は対象外です。

### 外部サービス連携

一部の外部フォームサービスがページ内に保持している一時データは、最も低い優先度のユーザーコンテキストとして利用されます。この値は読み取り専用で扱われ、Turnint AI 側の保存データには書き戻されません。同じキーがページ上のフォーム入力、保存済みコンテキスト、`data-turnint-context`、URL query parameter に存在する場合は、そちらが優先されます。

#### 対応している外部サービス

| サービス    | 参照するデータ        | 備考                      |
| ------- | -------------- | ----------------------- |
| Immedio | フォームで入力済みの顧客情報 | 低優先度のユーザーコンテキストとして利用します |

<Warning>
  `password`、`token`、`secret`、`csrf`、`auth`、`card` など、認証情報や機密情報に該当しうるキーは自動取り込みの対象外です。ユーザーコンテキストには、セッションで利用して問題ない業務情報だけを渡してください。
</Warning>

## トラッキングパラメータとの違い

`utm_source` や `gclid` などの広告・計測用パラメータは、ユーザーコンテキストではなく `sys.tracking` として自動保存されます。

| 種類          | 保存先            | 例                                               |
| ----------- | -------------- | ----------------------------------------------- |
| ユーザーコンテキスト  | セッションの context | `email`, `company`, `plan`, `accountId`         |
| トラッキングパラメータ | `sys.tracking` | `utm_source`, `utm_campaign`, `gclid`, `fbclid` |

広告効果測定やクロスドメイン計測にはトラッキングパラメータを使い、ユーザーやページの業務的な文脈にはユーザーコンテキストを使ってください。

<Note>
  Meta Pixel や HubSpot 広告連携が生成する計測フィールド（`fbc`, `fbcs`, `cd[type]` など）は、ユーザーコンテキストには取り込まれません。これらは `sys.tracking` 側で必要な値だけが自動保存されます。`data-turnint-context` に tracking 系キーを含めても、セッション context からは除外されます。
</Note>

## 関連ドキュメント

* [Nuxt への組み込み](/ja/get-started/onboarding/nuxt) — `data-turnint-*` 属性を使った埋め込み方法
* [Google Tag Manager 経由で導入する](/ja/get-started/onboarding/google-tag-manager) — GTM のカスタム HTML タグで導入する手順
* [トラッキングパラメータの自動保持](/ja/integrations/tracking-params) — UTM や広告クリック ID の扱い
* [Webhook 連携](/ja/integrations/webhook) — セッション context を外部システムで受け取る