Skip to main content
セッション開始前に提供内容の詳細や提供可否、必要に応じて一致する商品を取得します。これにより、ホストはブランドとの連携について同意を求める前に、ユーザーへリッチなプレビューを提示できます。

​
このタスクを使うタイミング

SI セッションを開始する有効なフローは 2 つあります。

​
フロー A: セッション前の照会（スポンサード結果に推奨）

si_get_offering → ホストが商品を提示 → ユーザーが同意 → offering_token を付与して si_initiate_session
同意を求める前に商品を見せたい場合に使用します。offering_token がセッション前のコンテキストを橋渡しするため、「2 つ目のもの」といった参照が成立します。 例: 検索結果ページで、ユーザーがエンゲージする前に「Nike にはあなたのサイズのランニングシューズが 3 足あり、$89 から」と表示する。

​
フロー B: 直接セッション

si_initiate_session → ブランドが最初の応答で商品を提示 → 会話を継続
ユーザーがすでにエンゲージする意図を示している場合に使います。ブランドエージェントがセッション内で商品を提示し、何を提示したかを内部で追跡します。 例: ユーザーが「Nike とランニングシューズの話をしたい」と言う場合は、事前取得は不要でそのままセッションを開始します。 重要な違い: si_get_offering は 同意前の匿名プレビュー 用です。すぐにセッションへ進むなら省略できます。

​
目的

オファーの照会には 3 つの目的があります。
  1. 提供内容の提示 - 同意前に価格、提供可否、説明を表示する
  2. 一致する商品の提示 - コンテキストがあれば、関連商品を返す
  3. セッション継続性 - 返されるトークンで提示内容を保持し、セッション開始時にブランドエージェントが文脈を把握できるようにする

​
リクエスト

FieldTypeRequiredDescription
offering_idstringYesプロモートされた提供内容の ID
contextstringNoパーソナライズのための自然言語コンテキスト（PII は禁止）
include_productsbooleanNo一致する商品を含めるか（デフォルト: false）
product_limitintegerNo返す商品の最大数（デフォルト: 5、最大: 50）

​
プライバシー

このリクエストには個人を特定できる情報を含めてはいけません。context フィールドには意図の説明を記載できますが、匿名である必要があります（例: “mens size 14 near Cincinnati” は可、メールアドレスは不可）。

​
レスポンス

FieldTypeDescription
availableboolean提供が現在利用可能か
offering_tokenstringsi_initiate_session に渡すトークン
ttl_secondsinteger情報が有効な秒数
checked_atstring照会時刻の ISO 8601 タイムスタンプ
offeringobject提供内容の詳細
matching_productsarrayコンテキストに一致する商品（要求された場合）
total_matchinginteger一致商品の総数（返却数を上回る場合あり）
unavailable_reasonstring提供不可の理由（利用不可の場合）
alternative_offering_idsarray代替オファーの候補

​
Offering Object

FieldTypeDescription
offering_idstring提供内容の ID
titlestringタイトル
summarystring簡潔な説明
taglinestring短い宣伝フレーズ
expires_atstring提供終了時刻
price_hintstring価格の目安（例: “from $89”）
image_urlstringヒーロー画像の URL
landing_urlstringランディングページ URL

​
Matching Product Object

FieldTypeDescription
product_idstring商品 ID
namestring商品名
pricestring表示価格
original_pricestringセール時の元価格
image_urlstring商品画像の URL
availability_summarystring簡単な在庫情報
urlstring商品詳細ページの URL

​
Unavailable Reasons

ReasonDescription
sold_out商品/オファー在庫が枯渇
expired提供期間が終了
region_restrictedユーザー地域では提供不可
inactiveキャンペーンが停止または終了

​
例

​
基本的な提供内容の照会

{
  "offering_id": "nike-summer-sale"
}

​
Response

{
  "available": true,
  "offering_token": "offering_abc123xyz",
  "ttl_seconds": 3600,
  "checked_at": "2025-01-19T10:00:00Z",
  "offering": {
    "offering_id": "nike-summer-sale",
    "title": "Nike Summer Sale",
    "summary": "Up to 50% off summer collection",
    "price_hint": "from $89",
    "expires_at": "2025-08-31T23:59:59Z"
  }
}

​
商品コンテキストを付与

{
  "offering_id": "nike-summer-sale",
  "context": "mens size 14 running shoes near Cincinnati",
  "include_products": true,
  "product_limit": 3
}

​
商品を含むレスポンス

{
  "available": true,
  "offering_token": "offering_abc123xyz",
  "ttl_seconds": 3600,
  "checked_at": "2025-01-19T10:00:00Z",
  "offering": {
    "offering_id": "nike-summer-sale",
    "title": "Nike Summer Sale",
    "summary": "Up to 50% off summer collection",
    "price_hint": "from $89"
  },
  "matching_products": [
    {
      "product_id": "nike-pegasus-41",
      "name": "Nike Pegasus 41",
      "price": "$89",
      "original_price": "$130",
      "image_url": "https://cdn.nike.com/pegasus-41.jpg",
      "availability_summary": "Size 14 in stock"
    },
    {
      "product_id": "nike-air-max-90",
      "name": "Nike Air Max 90",
      "price": "$129",
      "image_url": "https://cdn.nike.com/air-max-90.jpg",
      "availability_summary": "Size 14 in stock"
    }
  ],
  "total_matching": 12
}
これによりホストは次のように提示できます。
「Nike にはあなたのサイズのランニングシューズが 12 足あり、$89 からです。アシスタントと詳しく見てみますか？」

​
提供不可の場合のレスポンス

{
  "available": false,
  "checked_at": "2025-01-19T10:00:00Z",
  "unavailable_reason": "expired",
  "alternative_offering_ids": [
    "nike-fall-collection",
    "nike-clearance"
  ]
}

​
Offering トークンの利用

offering_token は セッション継続性 の鍵です。si_get_offering で商品を表示した後に会話を開始するとき、このトークンによりブランドエージェントは何が提示されたかを正確に把握できます。

​
セッション継続性が重要な理由

Without the token, this conversation breaks: 
Host: "Nike has 3 running shoes in size 14: Pegasus 41 ($89), Air Max 90 ($129), Vomero 18 ($139)"
User: "Tell me more about the second one"
Host → si_initiate_session: { context: "User wants more info about the second shoe" }
Brand Agent: ??? (Which shoes were shown? In what order?)
With the token, the brand agent can reconstruct the full context: 
Host → si_initiate_session: {
  context: "User wants more info about the second shoe",
  offering_token: "offering_abc123xyz"
}
Brand Agent: (Looks up token → sees Pegasus, Air Max, Vomero were shown in that order)
Brand Agent: "The Air Max 90 is a classic! It's part of our summer sale..."

​
ブランドエージェントがトークンを使う方法

offering_token を生成する際は、クエリの状態をサーバー側に保存します。 
// When returning si_get_offering response
const token = generateToken();
await store.save(token, {
  offering_id: request.offering_id,
  context: request.context,
  products_shown: matchingProducts,  // In exact order returned
  product_ids: matchingProducts.map(p => p.product_id),
  queried_at: new Date().toISOString(),
  ttl: 3600
});

return {
  available: true,
  offering_token: token,
  matching_products: matchingProducts,
  // ...
};
si_initiate_session でトークンを受け取ったら: 
// Retrieve the pre-session context
const preContext = await store.get(request.offering_token);
if (preContext) {
  // Now you know exactly what was shown
  // "the second one" = preContext.products_shown[1]
}

​
セッション開始時にトークンを含める

提供内容を取得した後にセッションを開始する場合、トークンを含めます。 
{
  "context": "User wants running shoes, mens size 14",
  "offering_id": "nike-summer-sale",
  "offering_token": "offering_abc123xyz",
  "identity": {
    "consent_granted": true,
    "user": { ... }
  }
}

​
重要ポイント

  1. 匿名設計 - 提供内容の照会にはユーザーデータを送信しません。プライバシーを守りつつリッチなプレビューを実現します。
  2. セッション継続性 - Offering トークンは提示内容の記憶です。「最初の選択肢」や「あの青いもの」といった参照をブランドエージェントが解決できます。
  3. 商品マッチング - include_products が true で context があれば、ブランドは関連商品を返せます。「あなたのサイズの靴が 12 足、$89 から」といったプレビューを実現します。
  4. キャッシュ - ホストは ttl_seconds までレスポンスをキャッシュできます。頻繁に照会されるオファーでブランドエージェントの負荷を下げます。
  5. 段階的なフォールバック - 照会が失敗またはタイムアウトしても、ホストはセッションを直接開始できます。照会は必須ではありません。
  6. 代替提案 - 提供不可の場合は alternative_offering_ids を通じて代替案を提示できます。

​
ベストプラクティス

​
ホスト向け

  • スポンサード結果を表示する前に提供内容を取得する
  • リッチなプレビューにはコンテキスト付きで include_products を使う
  • TTL を守ってキャッシュし、古いデータを避ける
  • 提供不可の場合の扱いを丁寧にし、期限切れのオファーを表示しない
  • 可能であればセッション開始時に offering トークンを含める

​
ブランドエージェント向け

  • 正確な表示のためにリッチな offering 情報を返す
  • コンテキストに合わせた商品マッチングのため include_products をサポートする
  • 妥当な TTL 値を設定する（変動に応じて 5～60 分など）
  • デバッグに役立つ unavailable_reason を提供する
  • 主要なオファーが利用できない場合は代替案を提案する