> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# si_get_offering

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

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

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. **セッション継続性** - 返されるトークンで提示内容を保持し、セッション開始時にブランドエージェントが文脈を把握できるようにします

## リクエスト

| Field              | Type    | Required | Description                    |
| ------------------ | ------- | -------- | ------------------------------ |
| `offering_id`      | string  | Yes      | プロモートされた提供内容の ID               |
| `context`          | string  | No       | パーソナライズのための自然言語コンテキスト（PII は禁止） |
| `include_products` | boolean | No       | 一致する商品を含めるか（デフォルト: false）      |
| `product_limit`    | integer | No       | 返す商品の最大数（デフォルト: 5、最大: 50）      |

### プライバシー

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

## レスポンス

| Field                      | Type    | Description                   |
| -------------------------- | ------- | ----------------------------- |
| `available`                | boolean | 提供が現在利用可能か                    |
| `offering_token`           | string  | `si_initiate_session` に渡すトークン |
| `ttl_seconds`              | integer | 情報が有効な秒数                      |
| `checked_at`               | string  | 照会時刻の ISO 8601 タイムスタンプ        |
| `offering`                 | object  | 提供内容の詳細                       |
| `matching_products`        | array   | コンテキストに一致する商品（要求された場合）        |
| `total_matching`           | integer | 一致商品の総数（返却数を上回る場合あり）          |
| `unavailable_reason`       | string  | 提供不可の理由（利用不可の場合）              |
| `alternative_offering_ids` | array   | 代替オファーの候補                     |

### Offering Object

| Field         | Type   | Description           |
| ------------- | ------ | --------------------- |
| `offering_id` | string | 提供内容の ID              |
| `title`       | string | タイトル                  |
| `summary`     | string | 簡潔な説明                 |
| `tagline`     | string | 短い宣伝フレーズ              |
| `expires_at`  | string | 提供終了時刻                |
| `price_hint`  | string | 価格の目安（例: "from \$89"） |
| `image_url`   | string | ヒーロー画像の URL           |
| `landing_url` | string | ランディングページ URL         |

### Matching Product Object

| Field                  | Type   | Description  |
| ---------------------- | ------ | ------------ |
| `product_id`           | string | 商品 ID        |
| `name`                 | string | 商品名          |
| `price`                | string | 表示価格         |
| `original_price`       | string | セール時の元価格     |
| `image_url`            | string | 商品画像の URL    |
| `availability_summary` | string | 簡単な在庫情報      |
| `url`                  | string | 商品詳細ページの URL |

### Sponsored Context Object

返された offering または `matching_products` がホスト境界に入るスポンサードコンテキストである場合、レスポンスレベルで `sponsored_context` を含めます。返されるパッケージ全体に適用されます。

| Field                   | Type   | Description                                                                   |
| ----------------------- | ------ | ----------------------------------------------------------------------------- |
| `paying_principal`      | object | スポンサードコンテキストについて経済的に説明責任を負うブランド。任意のセラーアカウント/オペレーターコンテキスト付き                    |
| `context_use`           | string | 宣言されたホスト側の使用モード: `presentation_only`、`comparison_set`、または `reasoning_context` |
| `disclosure_obligation` | object | ホストがコンテキストを使う前に受け入れて満たすか拒否するかしなければならない開示                                      |

`matching_products` が比較、ランキング、または選択のためのスポンサード候補セットである場合は `context_use: "comparison_set"` を使います。別個のスポンサードユニットまたはハンドオフには `presentation_only` を、コンテキストがホストの回答生成、プランニング、ランキング、またはその他の推論に利用可能であることを意図する場合にのみ `reasoning_context` を使います。パッケージを受け入れるホストは、監査証跡が支払いプリンシパル、宣言された使用モード、開示義務、ホストレシートをリンクするよう、後続の `si_initiate_session` リクエストに `sponsored_context_receipt` を含められます。

### Unavailable Reasons

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

## 例

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

```json theme={null}
{
  "offering_id": "nike-summer-sale"
}
```

### Response

```json theme={null}
{
  "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"
  }
}
```

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

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

### 商品を含むレスポンス

```json theme={null}
{
  "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 からです。アシスタントと詳しく見てみますか？」

### Response with Sponsored Context

```json theme={null}
{
  "$schema": "/schemas/sponsored-intelligence/si-get-offering-response.json",
  "status": "completed",
  "available": true,
  "offering_token": "offering_abc123xyz",
  "matching_products": [
    {
      "product_id": "trail-pace-14",
      "name": "Trail Pace 14",
      "price": "$89",
      "availability_summary": "Size 14 in stock"
    }
  ],
  "sponsored_context": {
    "paying_principal": {
      "brand": { "domain": "acme-running.example" },
      "display_name": "Acme Running"
    },
    "context_use": "comparison_set",
    "disclosure_obligation": {
      "required": true,
      "label_text": "Sponsored results from Acme Running",
      "timing": "near_each_influenced_output",
      "proximity": "near_influenced_output"
    },
    "declared_by": {
      "agent_url": "https://agent.acme-running.example/si",
      "role": "brand_agent"
    },
    "declared_at": "2025-01-19T10:00:00Z"
  },
  "total_matching": 1
}
```

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

```json theme={null}
{
  "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` を生成する際は、クエリの状態をサーバーサイドに保存します。

```typescript theme={null}
// 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` でトークンを受け取ったら:

```typescript theme={null}
// 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]
}
```

### セッション開始時にトークンを含めます

提供内容を取得した後にセッションを開始する場合、トークンを含めます。

```json theme={null}
{
  "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` を提供します
* 主要なオファーが利用できない場合は代替案を提案します