> ## 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.

# バイヤーエージェント向け TMP

> バイヤーエージェントが TMP とどう統合するか — Context Match と Identity Match リクエストへの応答、オファーの構造化、フリークエンシーキャップの管理。

# バイヤーエージェント向け TMP

バイヤーエージェントとして、あなたは TMP ルーターから Context Match と Identity Match リクエストを受け取り、オファーと適格性決定で応答します。あなたは決してリクエストを送りません — パブリッシャーがそのルーターを通じてすべての対話を開始します。

## 何を構築するか

バイヤーエージェントは、単一のベース URL の下に 2 つの HTTP/2 エンドポイント — Context Match の `POST /context` と Identity Match の `POST /identity` — を公開します。ルーターはパスでディスパッチします:

| Message type             | Receives                                   | Returns                          |
| ------------------------ | ------------------------------------------ | -------------------------------- |
| `context_match_request`  | ページ/コンテンツシグナル、プレースメント、geo                  | クリエイティブマニフェストを伴うオファー             |
| `identity_match_request` | セラーエージェント URL、アイデンティティトークン、任意のパッケージ ID リスト | 適格なパッケージ ID + `serve_window_sec` |

各エンドポイントは 1 つのメッセージタイプを扱います。両方とも 50ms 未満で応答しなければなりません。ルーターはこの予算を強制し、遅いプロバイダーをスキップします。

[adcp-go](https://github.com/adcontextprotocol/adcp-go) SDK は、両エンドポイントの Go 型、リクエストパース、レスポンスビルダーを提供します。

## 前提条件

TMP リクエストが到着する前に、あなたのパッケージが存在しなければなりません。メディアバイは 1 つ以上のパッケージを含みます — TMP はパッケージレベルで動作します。

1. パブリッシャーのセールスエージェントと `create_media_buy` 経由で **メディアバイを作成**
2. パブリッシャーがあなたのクリエイティブアセットを持つよう `sync_creatives` 経由で **クリエイティブを同期**
3. パブリッシャーのルーターがあなたのエンドポイントを知るよう **TMP プロバイダーとして登録**

ルーターはパブリッシャーのディール履歴からあなたのパッケージについて学びます。あなたはパッケージリストをルーターにプッシュしません。

## Responding to Context Match

ルーターはあなたにページコンテキストを送ります。あなたはそのコンテキストに対してアクティブなパッケージを評価し、一致するパッケージのオファーを返します。

```json theme={null}
// Request you receive
{
  "type": "context_match_request",
  "request_id": "ctx-8f3a2b",
  "property_rid": "01916f3a-9c4e-7000-8000-000000000010",
  "property_type": "website",
  "placement_id": "article-sidebar",
  "seller_agent_url": "https://streamhaus.example",
  "artifact_refs": [
    { "type": "url", "value": "https://streamhaus.example/articles/hiking-gear-2026" }
  ],
  "context_signals": {
    "topics": ["550", "710"],
    "keywords": ["hiking", "gear", "outdoor"],
    "sentiment": "positive"
  },
  "geo": { "country": "US", "region": "US-CO" }
}
```

**あなたがすること:**

1. この `property_rid` と `placement_id` のアクティブなパッケージをルックアップする
2. 各パッケージのターゲティングをコンテキストシグナル、geo、artifact refs に対して評価する
3. 一致するパッケージのオファーを、それぞれクリエイティブマニフェスト付きで返す

```json theme={null}
// Your response
{
  "type": "context_match_response",
  "request_id": "ctx-8f3a2b",
  "offers": [
    {
      "package_id": "acme-outdoor-q2",
      "brand": { "domain": "acmeoutdoor.example.com" },
      "summary": "Hiking gear seasonal promotion",
      "creative_manifest": {
        "format_id": { "agent_url": "https://streamhaus.example", "id": "sidebar_display" },
        "assets": {
          "headline": { "content": "Trail-ready gear for every summit" },
          "image": { "url": "https://cdn.acme.example/hiking-hero.jpg", "width": 300, "height": 250 },
          "cta": { "content": "Shop now" }
        }
      },
      "price": { "amount": 12.50, "currency": "USD", "model": "cpm" }
    }
  ]
}
```

Context Match で **あなたが決して受け取らないもの**: ユーザー ID、デバイス ID、セッショントークン、IP アドレス、cookie。あなたはユーザーを識別できません。

## Responding to Identity Match

ルーターはあなたにセラーの `seller_agent_url` と 1 つ以上のアイデンティティトークンを送ります。`seller_agent_url` を使ってそのセラーに登録したアクティブなパッケージセットをルックアップし、サポートするトークンでアイデンティティを解決し、解決されたユーザーに対して各パッケージの適格性ルールを確認します。パブリッシャーは評価を明示的にスコープするため `package_ids` も送ってもよい（MAY）。存在するとき、登録済みアクティブセットと `package_ids` の **交差** に対して評価し、認識しない任意の ID を **黙って落とす**（silently drop） — 両方のパブリッシャーモード（all-active と fuzzed/padded）はこの動作に依存します。未知の ID をエラーとしてサーフェスすることは、あなたのレジストリメンバーシップをパブリッシャーに漏らします。

```json theme={null}
// Request you receive
{
  "type": "identity_match_request",
  "request_id": "id-9c4e",
  "seller_agent_url": "https://publisher.example",
  "identities": [
    { "user_token": "opaque-token-abc123", "uid_type": "publisher_first_party" },
    { "user_token": "ID5*7xYp...", "uid_type": "id5" }
  ],
  "package_ids": ["acme-outdoor-q2", "acme-winter-clearance", "acme-loyalty-retarget"],
  "consent": { "gdpr": true, "tcf_consent": "CPxyz..." }
}
```

**あなたがすること:**

1. サポートする `uid_type` でトークンをアイデンティティグラフに対して解決する。リクエストのエントリ順は意味的に重要でない — バイヤー自身の優先順に従って自身の優先順を適用する。すべてのエントリは同じユーザーを識別するので、最初の成功した解決で十分。複数のアイデンティティタイプが存在するとき、バイヤーは `hashed_email` のような強く再識別するトークンより不透明なプロバイダー ID（UID2、EUID、ID5、RampID）を優先すべき（SHOULD）。これは、誤設定または侵害されたルーターが最高リスクのトークンのみを転送するシナリオを無効化する。
2. フリークエンシーキャップを確認: このユーザーはパッケージのインプレッション制限を超えたか？
3. オーディエンスルールを確認: このユーザーはターゲットオーディエンスにいるか？
4. 抑制リストを確認: このユーザーは除外されるべきか？
5. 各パッケージの適格性を返す

```json theme={null}
// Your response
{
  "type": "identity_match_response",
  "request_id": "id-9c4e",
  "eligible_package_ids": ["acme-outdoor-q2", "acme-loyalty-retarget"],
  "serve_window_sec": 60
}
```

適格性チェックを通過するパッケージ ID のみを返します。リストにないパッケージは不適格として扱われます。`serve_window_sec` は **パッケージごとのシングルショット fcap** です: パブリッシャーがこのウィンドウ内で各適格パッケージにユーザーへ 1 インプレッションを提供した後、パブリッシャーはそれらのパッケージから再び提供する前に Identity Match を再クエリしなければなりません（MUST）。デフォルト 60s、最大 300s。これはルーターのレスポンスキャッシュ TTL ではありません — [The serve-window contract](#the-serve-window-contract) を参照。

Identity Match で **あなたが決して受け取らないもの**: ページ URL、コンテンツトピック、キーワード、記事テキスト、任意のコンテンツシグナル。あなたはユーザーが何を見ているかを判断できません。

**なぜ Context Match で一致したものだけでなく、すべてのパッケージを受け取るか**: これはあなたがユーザーがどのコンテンツを見ているかを推論するのを防ぎます。ハイキング記事に一致したパッケージのみを受け取ったら、ユーザーがハイキングについて読んでいたと知ってしまいます。すべてのパッケージを受け取ることが構造的分離を保ちます。

## 結合はパブリッシャー側で起こる

あなたは結合された結果を決して見ません。パブリッシャーのルーターは:

1. あなたの Context Match オファーとあなたの Identity Match `eligible_package_ids` を交差させる
2. 両方のレスポンスに現れるパッケージのみをアクティベートする
3. 一致したパッケージのアドサーバーターゲティングキー値を設定する
4. アドサーバーが最終的なレンダリング決定を下す

このステップにあなたの役割はありません。パブリッシャーがアクティベーションを制御します。

## フリークエンシーキャップ管理

クロスパブリッシャーフリークエンシーキャッピングは Identity Match の主要なユースケースです。キャップポリシーとカウントはあなたの **インプレッショントラッカー** に存在します。Identity Match サービスはクエリ時にキャップ発火シグナルのみを消費します。分割:

* **インプレッショントラッカー** はピクセル発火を受け取り、TMPX トークンをデコードし、維持する任意の fcap ポリシーを適用します — 各解決されたユーザーアイデンティティについて、キャップする任意の次元（パッケージ、キャンペーン、広告主、クリエイティブ、ラインアイテム）にわたってインプレッションをカウントし、ポリシーエンジンが使う任意のウィンドウ化と重複排除ロジックで。
* **キャップを使い果たすインプレッションで**、インプレッショントラッカーはキャップ発火エントリ — `(user_identity, package) capped until <expireAt>` — を Identity Match キャップ状態ストアに書き込みます。
* **Identity Match サービス** はクエリ時に、リクエストの任意のアイデンティティに対してキャップ発火エントリを持つ任意のパッケージを `eligible_package_ids` から除外します。

プロトコルは、あなたがどうインプレッションをカウントするか、ポリシーがどこに存在するか、アイデンティティをまたいでどう重複排除するかを制約しません。境界のみを定義します: キャップ発火イベントがキャップ状態ストアに流れ込み、IdentityMatch サービスがクエリ時に存在を確認します。境界コントラクトとリファレンスキャップ状態ストアについては [フリークエンシーキャップデータフロー](/docs/trusted-match/identity-match-implementation) を参照。

fcap ルールが変わるとき — ウィンドウが短縮または延長、`max_count` が上昇または下降、ポリシーが一時停止または削除、パッケージが再割り当て — あなたは影響を受ける `(user_identity, package)` キャップ状態エントリを新しいポリシーに対して再評価し、適切な更新をプッシュしなければなりません（MUST）: もはやキャップ超過でないユーザーのエントリを **削除**、まだキャップ超過だがウィンドウが変わったエントリを **延長**（新しい `expire_at` で上書き）。キャップ状態ストアはカウントを保存せず自身で再評価できません。バイヤーのポリシー所有者が真実の源泉です。イベント形状については [ポリシー更新とキャップ状態の再評価](/docs/trusted-match/identity-match-implementation#policy-updates-and-cap-state-re-evaluation) を参照。

Identity Match は TMP を使うすべてのパブリッシャーにわたって実行されるため、Publisher A であなたの広告を見たユーザーは、どのパブリッシャーがリクエストを送ったか見えなくても、Publisher B で正しくフリークエンシー超過として現れます。

実装の詳細 — fcap\_keys ラベルモデル、リファレンス valkey データモデル、露出レコード形状、SDK プリミティブ、適合性シナリオ — については [インプレッショントラッカー実装リファレンス](/docs/trusted-match/impression-tracker-implementation) を参照。インプレッショントラッカーと Identity Match サービスの間に位置する境界コントラクトは [フリークエンシーキャップデータフロー](/docs/trusted-match/identity-match-implementation) にあります。

### バイヤーはどう露出を学ぶか

Identity Match レスポンスの `tmpx` フィールドは TMPX トークン — ユーザーの解決されたアイデンティティトークンを含む HPKE 暗号化された blob — を運びます。パブリッシャーは `{TMPX}` をクリエイティブトラッキング URL に代入します。広告が提供されると、あなたのインプレッションピクセルが暗号化トークンを受け取ります。あなたのインプレッショントラッカーはそれを復号し、解決されたアイデンティティに対して fcap ポリシーロジックを適用し、（キャップが発火したとき）Identity Match キャップ状態ストアにキャップ発火エントリを書き込みます。ほとんどの本番デプロイは、バッファリングのため、デコード（同期、取り込み時）をポリシー評価とキャップ状態書き込み（非同期、キューの背後）から分離します。

これはパブリッシャーがユーザーアイデンティティを見ずに、あなたにリアルタイムのユーザーごとの露出シグナルを与えます。

暗号化形式とバイナリトークン構造については [TMPX 露出トークン](/docs/trusted-match/specification#tmpx-exposure-tokens) を、キャップ状態ストア境界コントラクトについては [フリークエンシーキャップデータフロー](/docs/trusted-match/identity-match-implementation) を参照。

## プロバイダー登録

プロバイダー登録は帯域外プロセスです。`create_media_buy` 経由でメディアバイを確立した後、パブリッシャーと調整してあなたの TMP ベース URL を提供します。これは通常商業的合意を含み、法的レビューを必要とするかもしれません。なぜならパブリッシャーがあなたのエンドポイントにコンテンツシグナルとアイデンティティトークンを送るからです。パブリッシャーは次にそのルーターであなたのプロバイダーエントリを設定します（[ルーターデプロイ](/docs/trusted-match/router-architecture#deployment) を参照）。

```json theme={null}
{
  "provider_id": "acme-outdoor-us",
  "endpoint": "https://us.tmp.acmeoutdoor.example/v1",
  "context_match": true,
  "identity_match": true,
  "countries": ["US"],
  "uid_types": ["uid2", "rampid", "id5"]
}
```

`identity_match` をサポートするとき、`countries`（提供する国コード）と `uid_types`（解決するアイデンティティタイプ）を宣言しなければなりません（MUST）。ルーターはこれらを使って Identity Match ファンアウトをフィルターします — それらなしでは、ルーターはあなたのプロバイダーにリクエストをルーティングできません。

いずれか、または両方のエンドポイントをサポートできます。Context Match のみは、フリークエンシーキャッピングなしのコンテキストターゲティングを意味します。Identity Match のみは、パブリッシャーがあなたのメディアバイのターゲティングルールからコンテキストをローカルで評価し、フリークエンシーチェックのためだけにあなたを呼ぶことを意味します。両方は完全な TMP 統合を意味します。

### ヘルスエンドポイント

あなたはそのベース URL で `GET /health` を公開すべきです（SHOULD）。準備完了のとき HTTP `200` を `{"status": "ok"}` とともに返します。パブリッシャーのルーターはこれをプリフライトチェックと監視に使います。リクエストファンアウト中には呼ばれません — バックグラウンド間隔のみ。

## エラー処理

あなたのエージェントがリクエストを評価できないとき、エラーレスポンスを返します:

```json theme={null}
{
  "type": "error",
  "request_id": "ctx-8f3a2b",
  "code": "provider_unavailable",
  "message": "Targeting data temporarily unavailable"
}
```

一般的なシナリオ:

* **一致するパッケージなし**: 空の `offers` 配列を返す（エラーではない）。これはあなたのパッケージがコンテンツに一致しないときの通常のケース。
* **内部失敗**: エラーレスポンスを返す。ルーターはあなたのプロバイダーをスキップし他のプロバイダーで続行する。
* **タイムアウト**: レイテンシー予算内に応答できない場合、ルーターはあなたをスキップする。エラーレスポンスは不要 — ルーターがこれを扱う。

## The serve-window contract

Identity Match レスポンスの `serve_window_sec` フィールドは、バイヤーとパブリッシャーの間の **パッケージごとのシングルショット fcap** です:

* `eligible_package_ids` の各パッケージについて、パブリッシャーは `serve_window_sec` 秒以内にそのパッケージでユーザーに **最大 1 インプレッション** を提供してもよい（MAY）。
* パブリッシャーが各適格パッケージに 1 インプレッションを提供した後、パブリッシャーは同じユーザーにそれらのパッケージのいずれかを再び提供する前に Identity Match を再クエリしなければなりません（MUST）。
* マルチインプレッションフリークエンシーキャッピング（5/日、100/月など）は別です。それはあなたのバイヤー側の状態に存在し、`serve_window_sec` にかかわらず TMPX インプレッションコールバック経由で帯域外で更新されます。サーブウィンドウはプロトコルレベルのスロットルで、マルチインプレッションキャップはバイヤー内部のポリシーです。

ルーターは `{identities_hash, provider_id, package_ids_hash, consent_hash}`（正準バイトについては仕様を参照）でキー付けされた内部重複排除キャッシュを適用してもよい（MAY）が、パブリッシャーの拘束コントラクトはルーターのキャッシュウィンドウではなくサーブウィンドウスロットルです。

**serve\_window\_sec 値の選択**: デフォルト 60 秒。範囲 1–300。300 より長いものは、典型的なキャンペーンにパッケージごとの fcap が粗すぎます。IdentityMatch 往復より短いものは負荷を追加するだけです。60 が良いデフォルトです。適格性状態がより速くシフトする場合（キャップに近い、オーディエンスがちょうど変わった）は下方に、IdentityMatch サービスが負荷下でキャンペーンがより粗い fcap に寛容な場合は上方（最大 300）に調整します。

## パフォーマンス要件

| Metric                                                    | Target      |
| --------------------------------------------------------- | ----------- |
| エージェント側処理                                                 | \< 30ms p95 |
| エンドツーエンド（publisher → router → agent → router → publisher） | \< 50ms p95 |
| 可用性                                                       | 99.9%       |
| エラー率                                                      | \< 0.1%     |

30ms のエージェント側予算は、ルーターとあなたのエンドポイントの間のネットワークオーバーヘッドを考慮します。ルーターはあなたのレイテンシーパーセンタイルを追跡し、適応的にタイムアウト割り当てを調整します。一貫して遅い応答は、ルーターがあなたの割り当てを減らすかあなたのプロバイダーをスキップする結果になります。

## 測定

パブリッシャーは `get_media_buy_delivery` 経由で配信をレポートします。あなたのエージェントは配信データをクエリして、インプレッションを再照合し、ペーシングを追跡し、フリークエンシー状態を更新します。

バイヤーは `{TMPX}` マクロ経由でリアルタイムのユーザーごとの露出シグナルを受け取ります。Identity Match レスポンスは、クリエイティブトラッキング URL を通じてあなたのインプレッションピクセルに流れる暗号化 TMPX トークンを含みます。あなたのクラスターマスターがトークンを復号し、ユーザーごとのフリークエンシー状態をリアルタイムで更新します。`get_media_buy_delivery` は再照合とペーシングのための集約配信メトリクスを提供します — 主要なフリークエンシー入力ではありません。

## OpenRTB との違い

|              | OpenRTB                         | TMP                                          |
| ------------ | ------------------------------- | -------------------------------------------- |
| **あなたが受け取る** | 完全な入札リクエスト（ユーザー + コンテンツ + デバイス） | コンテンツ **または** アイデンティティ、決して両方でない              |
| **あなたが返す**   | 入札価格                            | オファー（クリエイティブマニフェスト）または適格なパッケージ ID + サーブウィンドウ |
| **オークション**   | エクスチェンジがオークションを実行               | オークションなし — パブリッシャーがローカルで結合                   |
| **フリークエンシー** | DSP ごとのみ                        | Identity Match 経由でクロスパブリッシャー                 |
| **統合**       | エクスチェンジごとの SSP アダプター            | 2 つのエンドポイント（context + identity）、任意のサーフェス     |