バイヤーエージェント向け TMP
バイヤーエージェントとして、あなたは TMP ルーターから Context Match と Identity Match リクエストを受け取り、オファーと適格性決定で応答します。あなたは決してリクエストを送りません — パブリッシャーがそのルーターを通じてすべての対話を開始します。何を構築するか
バイヤーエージェントは、単一のベース URL の下に 2 つの HTTP/2 エンドポイント — Context Match のPOST /context と Identity Match の POST /identity — を公開します。ルーターはパスでディスパッチします:
各エンドポイントは 1 つのメッセージタイプを扱います。両方とも 50ms 未満で応答しなければなりません。ルーターはこの予算を強制し、遅いプロバイダーをスキップします。
adcp-go SDK は、両エンドポイントの Go 型、リクエストパース、レスポンスビルダーを提供します。
前提条件
TMP リクエストが到着する前に、あなたのパッケージが存在しなければなりません。メディアバイは 1 つ以上のパッケージを含みます — TMP はパッケージレベルで動作します。- パブリッシャーのセールスエージェントと
create_media_buy経由で メディアバイを作成 - パブリッシャーがあなたのクリエイティブアセットを持つよう
sync_creatives経由で クリエイティブを同期 - パブリッシャーのルーターがあなたのエンドポイントを知るよう TMP プロバイダーとして登録
Responding to Context Match
ルーターはあなたにページコンテキストを送ります。あなたはそのコンテキストに対してアクティブなパッケージを評価し、一致するパッケージのオファーを返します。- この
property_ridとplacement_idのアクティブなパッケージをルックアップする - 各パッケージのターゲティングをコンテキストシグナル、geo、artifact refs に対して評価する
- 一致するパッケージのオファーを、それぞれクリエイティブマニフェスト付きで返す
Responding to Identity Match
ルーターはあなたにセラーのseller_agent_url と 1 つ以上のアイデンティティトークンを送ります。seller_agent_url を使ってそのセラーに登録したアクティブなパッケージセットをルックアップし、サポートするトークンでアイデンティティを解決し、解決されたユーザーに対して各パッケージの適格性ルールを確認します。パブリッシャーは評価を明示的にスコープするため package_ids も送ってもよい（MAY）。存在するとき、登録済みアクティブセットと package_ids の 交差 に対して評価し、認識しない任意の ID を 黙って落とす（silently drop） — 両方のパブリッシャーモード（all-active と fuzzed/padded）はこの動作に依存します。未知の ID をエラーとしてサーフェスすることは、あなたのレジストリメンバーシップをパブリッシャーに漏らします。
- サポートする
uid_typeでトークンをアイデンティティグラフに対して解決する。リクエストのエントリ順は意味的に重要でない — バイヤー自身の優先順に従って自身の優先順を適用する。すべてのエントリは同じユーザーを識別するので、最初の成功した解決で十分。複数のアイデンティティタイプが存在するとき、バイヤーはhashed_emailのような強く再識別するトークンより不透明なプロバイダー ID（UID2、EUID、ID5、RampID）を優先すべき（SHOULD）。これは、誤設定または侵害されたルーターが最高リスクのトークンのみを転送するシナリオを無効化する。 - フリークエンシーキャップを確認: このユーザーはパッケージのインプレッション制限を超えたか？
- オーディエンスルールを確認: このユーザーはターゲットオーディエンスにいるか？
- 抑制リストを確認: このユーザーは除外されるべきか？
- 各パッケージの適格性を返す
serve_window_sec は パッケージごとのシングルショット fcap です: パブリッシャーがこのウィンドウ内で各適格パッケージにユーザーへ 1 インプレッションを提供した後、パブリッシャーはそれらのパッケージから再び提供する前に Identity Match を再クエリしなければなりません（MUST）。デフォルト 60s、最大 300s。これはルーターのレスポンスキャッシュ TTL ではありません — The serve-window contract を参照。
Identity Match で あなたが決して受け取らないもの: ページ URL、コンテンツトピック、キーワード、記事テキスト、任意のコンテンツシグナル。あなたはユーザーが何を見ているかを判断できません。
なぜ Context Match で一致したものだけでなく、すべてのパッケージを受け取るか: これはあなたがユーザーがどのコンテンツを見ているかを推論するのを防ぎます。ハイキング記事に一致したパッケージのみを受け取ったら、ユーザーがハイキングについて読んでいたと知ってしまいます。すべてのパッケージを受け取ることが構造的分離を保ちます。
結合はパブリッシャー側で起こる
あなたは結合された結果を決して見ません。パブリッシャーのルーターは:- あなたの Context Match オファーとあなたの Identity Match
eligible_package_idsを交差させる - 両方のレスポンスに現れるパッケージのみをアクティベートする
- 一致したパッケージのアドサーバーターゲティングキー値を設定する
- アドサーバーが最終的なレンダリング決定を下す
フリークエンシーキャップ管理
クロスパブリッシャーフリークエンシーキャッピングは Identity Match の主要なユースケースです。キャップポリシーとカウントはあなたの インプレッショントラッカー に存在します。Identity Match サービスはクエリ時にキャップ発火シグナルのみを消費します。分割:- インプレッショントラッカー はピクセル発火を受け取り、TMPX トークンをデコードし、維持する任意の fcap ポリシーを適用します — 各解決されたユーザーアイデンティティについて、キャップする任意の次元（パッケージ、キャンペーン、広告主、クリエイティブ、ラインアイテム）にわたってインプレッションをカウントし、ポリシーエンジンが使う任意のウィンドウ化と重複排除ロジックで。
- キャップを使い果たすインプレッションで、インプレッショントラッカーはキャップ発火エントリ —
(user_identity, package) capped until <expireAt>— を Identity Match キャップ状態ストアに書き込みます。 - Identity Match サービス はクエリ時に、リクエストの任意のアイデンティティに対してキャップ発火エントリを持つ任意のパッケージを
eligible_package_idsから除外します。
max_count が上昇または下降、ポリシーが一時停止または削除、パッケージが再割り当て — あなたは影響を受ける (user_identity, package) キャップ状態エントリを新しいポリシーに対して再評価し、適切な更新をプッシュしなければなりません（MUST）: もはやキャップ超過でないユーザーのエントリを 削除、まだキャップ超過だがウィンドウが変わったエントリを 延長（新しい expire_at で上書き）。キャップ状態ストアはカウントを保存せず自身で再評価できません。バイヤーのポリシー所有者が真実の源泉です。イベント形状については ポリシー更新とキャップ状態の再評価 を参照。
Identity Match は TMP を使うすべてのパブリッシャーにわたって実行されるため、Publisher A であなたの広告を見たユーザーは、どのパブリッシャーがリクエストを送ったか見えなくても、Publisher B で正しくフリークエンシー超過として現れます。
実装の詳細 — fcap_keys ラベルモデル、リファレンス valkey データモデル、露出レコード形状、SDK プリミティブ、適合性シナリオ — については インプレッショントラッカー実装リファレンス を参照。インプレッショントラッカーと Identity Match サービスの間に位置する境界コントラクトは フリークエンシーキャップデータフロー にあります。
バイヤーはどう露出を学ぶか
Identity Match レスポンスのtmpx フィールドは TMPX トークン — ユーザーの解決されたアイデンティティトークンを含む HPKE 暗号化された blob — を運びます。パブリッシャーは {TMPX} をクリエイティブトラッキング URL に代入します。広告が提供されると、あなたのインプレッションピクセルが暗号化トークンを受け取ります。あなたのインプレッショントラッカーはそれを復号し、解決されたアイデンティティに対して fcap ポリシーロジックを適用し、（キャップが発火したとき）Identity Match キャップ状態ストアにキャップ発火エントリを書き込みます。ほとんどの本番デプロイは、バッファリングのため、デコード（同期、取り込み時）をポリシー評価とキャップ状態書き込み（非同期、キューの背後）から分離します。
これはパブリッシャーがユーザーアイデンティティを見ずに、あなたにリアルタイムのユーザーごとの露出シグナルを与えます。
暗号化形式とバイナリトークン構造については TMPX 露出トークン を、キャップ状態ストア境界コントラクトについては フリークエンシーキャップデータフロー を参照。
プロバイダー登録
プロバイダー登録は帯域外プロセスです。create_media_buy 経由でメディアバイを確立した後、パブリッシャーと調整してあなたの TMP ベース URL を提供します。これは通常商業的合意を含み、法的レビューを必要とするかもしれません。なぜならパブリッシャーがあなたのエンドポイントにコンテンツシグナルとアイデンティティトークンを送るからです。パブリッシャーは次にそのルーターであなたのプロバイダーエントリを設定します（ルーターデプロイ を参照）。
identity_match をサポートするとき、countries（提供する国コード）と uid_types（解決するアイデンティティタイプ）を宣言しなければなりません（MUST）。ルーターはこれらを使って Identity Match ファンアウトをフィルターします — それらなしでは、ルーターはあなたのプロバイダーにリクエストをルーティングできません。
いずれか、または両方のエンドポイントをサポートできます。Context Match のみは、フリークエンシーキャッピングなしのコンテキストターゲティングを意味します。Identity Match のみは、パブリッシャーがあなたのメディアバイのターゲティングルールからコンテキストをローカルで評価し、フリークエンシーチェックのためだけにあなたを呼ぶことを意味します。両方は完全な TMP 統合を意味します。
ヘルスエンドポイント
あなたはそのベース URL でGET /health を公開すべきです（SHOULD）。準備完了のとき HTTP 200 を {"status": "ok"} とともに返します。パブリッシャーのルーターはこれをプリフライトチェックと監視に使います。リクエストファンアウト中には呼ばれません — バックグラウンド間隔のみ。
エラー処理
あなたのエージェントがリクエストを評価できないとき、エラーレスポンスを返します:- 一致するパッケージなし: 空の
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）に調整します。
パフォーマンス要件
30ms のエージェント側予算は、ルーターとあなたのエンドポイントの間のネットワークオーバーヘッドを考慮します。ルーターはあなたのレイテンシーパーセンタイルを追跡し、適応的にタイムアウト割り当てを調整します。一貫して遅い応答は、ルーターがあなたの割り当てを減らすかあなたのプロバイダーをスキップする結果になります。
測定
パブリッシャーはget_media_buy_delivery 経由で配信をレポートします。あなたのエージェントは配信データをクエリして、インプレッションを再照合し、ペーシングを追跡し、フリークエンシー状態を更新します。
バイヤーは {TMPX} マクロ経由でリアルタイムのユーザーごとの露出シグナルを受け取ります。Identity Match レスポンスは、クリエイティブトラッキング URL を通じてあなたのインプレッションピクセルに流れる暗号化 TMPX トークンを含みます。あなたのクラスターマスターがトークンを復号し、ユーザーごとのフリークエンシー状態をリアルタイムで更新します。get_media_buy_delivery は再照合とペーシングのための集約配信メトリクスを提供します — 主要なフリークエンシー入力ではありません。