エージェントを Web サイトに埋め込むとき、ページ側が持っているユーザー情報やページ固有の情報を ユーザーコンテキスト として引き渡せます。
たとえば、会員向けページでログイン済みユーザーのメールアドレスや契約プランを渡したり、記事ページでカテゴリや閲覧中の商品 ID を渡したりできます。渡された値はセッションの context として保存され、ゲートの事前入力や Webhook 連携などで利用できます。
渡せる情報の例
| キー | 値の例 | 用途 |
|---|
email | user@example.com | ゲートのメールアドレス入力を事前入力する |
company | 株式会社サンプル | 会社名をセッションに紐づける |
plan | enterprise | 契約プランに応じた会話や分岐に使う |
accountId | acct_123 | 自社システム上のアカウント ID と紐づける |
pageCategory | pricing | どのページ文脈で起動されたかを渡す |
data-turnint-context で渡す
埋め込み要素に data-turnint-context 属性を追加し、JSON 文字列を指定します。
<div
data-turnint-id="pub_xxxxxxxxxxxxxxxx"
data-turnint-type="inline"
data-turnint-context='{"email":"user@example.com","company":"株式会社サンプル","plan":"enterprise"}'
></div>
<button
data-turnint-id="pub_xxxxxxxxxxxxxxxx"
data-turnint-type="fullscreen"
data-turnint-context='{"email":"user@example.com","accountId":"acct_123"}'
>
AI と資料を読む
</button>
data-turnint-context の値は JSON として解釈されます。HTML 属性内では、JSON 全体をシングルクォートで囲むと書きやすくなります。
embed script はページ内で 1 度だけ読み込みます。UI 言語は script 側の data-turnint-locale で指定してください。
application/json の script で渡す
属性に長い JSON を直接書きたくない場合は、data-turnint-context を付けた application/json の script block を使えます。
<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 がある場合は、後に出現した値が同じキーを上書きします。
application/ld+json は対象外です。構造化データや SEO 用の JSON-LD を誤ってユーザーコンテキストに取り込まないよう、コンテキスト引き渡しには type="application/json" を使ってください。
ゲートとの関係
ユーザーコンテキストのキーがゲートのフォームフィールドのキーと一致する場合、その値はゲートの型に沿って検証・整形されます。
たとえば、ゲートに email というメールアドレス項目がある場合、data-turnint-context で渡した email はメールアドレスとして検証されます。score のような数値項目であれば、数値として扱える値に整形されます。
ゲートに存在しないキーも破棄されず、セッションの context に保持されます。
{
"email": "user@example.com",
"company": "株式会社サンプル",
"plan": "enterprise"
}
email と company がある場合はその 2 つがゲートの定義に沿って扱われ、plan は追加のセッションコンテキストとして保持されます。
ゲートが設定されていないエージェントでも、data-turnint-context で渡した値はセッションの context に保存されます。
URL query parameter との優先順位
URL query parameter は、ゲートのフォームフィールドと一致するキーだけを事前入力に使います。autoconfirm=true はゲートの自動確認用の制御フラグとして扱われますが、セッションの context には保存されません。
ゲートに存在しない query parameter はユーザーコンテキストとしては取り込まれません。ページ固有の情報や任意のキーをセッション context に渡したい場合は、data-turnint-context または application/json の script block を使ってください。
同じゲートフィールドのキーが複数の場所に存在する場合、次の順序で後の値が優先されます。
外部サービス連携 < ページ上のフォーム入力 < 保存済みコンテキスト < 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 | フォームで入力済みの顧客情報 | 低優先度のユーザーコンテキストとして利用します |
password、token、secret、csrf、auth、card など、認証情報や機密情報に該当しうるキーは自動取り込みの対象外です。ユーザーコンテキストには、セッションで利用して問題ない業務情報だけを渡してください。
トラッキングパラメータとの違い
utm_source や gclid などの広告・計測用パラメータは、ユーザーコンテキストではなく sys.tracking として自動保存されます。
| 種類 | 保存先 | 例 |
|---|
| ユーザーコンテキスト | セッションの context | email, company, plan, accountId |
| トラッキングパラメータ | sys.tracking | utm_source, utm_campaign, gclid, fbclid |
関連ドキュメント
