Identity Match フリークエンシーキャップデータフロー
このページは、フリークエンシーキャップの状態がどう Identity Match サービスに到達し、Identity Match が適格性時にどうそれを消費するかを記述します。それは データフローのみ を定義します — インプレッショントラッカーと Identity Match サービスの間の境界を越えるもの。内部メカニクス（インプレッショントラッカーがどうインプレッションをカウントするか、ポリシーがどこに存在するか、Identity Match サービスがどのストレージレイアウトを使うか、アイデンティティが上流でどう重複排除されるか）はバイヤー内部の関心事で、ここではスコープ外です。 ワイヤー仕様は TMP 仕様 に存在します。Identity Match サービスが満たさなければならない適合性不変条件もそこで規範的です。Identity Match キャップ状態ストアのリファレンス実装はadcp-go/targeting/fcap で出荷されます。
ロール
分割は意図的です: インプレッションのカウント、ウィンドウの評価、キャップがいつ発火するかの決定は、バイヤーとキャンペーンをまたいで異なるバイヤー内部のポリシー関心事です。Identity Match サービスは狭いまま — 「このユーザーはこのパッケージについて現在キャップされているか？」に答え、それ以上はしません。新しいキャップ次元（広告主、キャンペーン、クリエイティブ — extensions を参照）は、サービスを変えずに同じ境界コントラクトに接続します。
エンドツーエンドフロー
The cap-fire event
バイヤーのポリシー評価が、インプレッションがキャップを使い果たしたと判断すると、インプレッショントラッカーは Identity Match キャップ状態ストアにキャップ発火エントリを書き込みます。各エントリは次から成ります:
単一のキャップ発火イベントは通常 1 エントリに対応します。複数の解決されたアイデンティティまたは複数のパッケージで発火するキャップは、バイヤーのポリシーが同じなら同じ
expire_at を共有する (identity, package) ペアごとに 1 エントリを生成します。
キャップ状態ストアは、インプレッションごとのカウント、ポリシー定義、ウィンドウ設定を記録しません。その唯一の仕事は「この (user_identity, package) は現在キャップされているか？」に答えることです。バイヤーのポリシーロジック — カウント、ウィンドウ化、キャップする次元の選択、いつ発火するかの決定 — は完全にインプレッショントラッカーに存在します。
適格性クエリ
クエリ時に、Identity Match サービスはアイデンティティのリストと候補パッケージのリストを受け取ります。各候補パッケージについて、ユーザーのアイデンティティにわたって一致する(identity, package) エントリをキャップ状態ストアで確認します。任意のエントリが存在すれば、パッケージは eligible_package_ids から除外されます。これは存在チェックであり、カウントではありません。
キャップ状態は適格性への 1 つの入力です。Identity Match サービスは、オーディエンスメンバーシップ、パッケージのアクティブ状態、オーディエンス鮮度、バイヤーが気にする他の任意の入力も評価します — 適合性不変条件 を参照。その評価のキャップ状態の部分が、このページが定義する部分です。
Policy updates and cap-state re-evaluation
キャップ状態エントリは、キャップ発火時に有効だった fcap ポリシーの下で書き込まれます。バイヤーの fcap ポリシーが変わるとき — ウィンドウが短縮または延長、max_count が上昇または下降、ポリシーが一時停止または削除、パッケージが異なるポリシーに再割り当て — 古いポリシーの下で書き込まれた既存のキャップ状態エントリは古くなりうる。古いエントリは、今や適格であるべきユーザーを抑制する（過剰抑制）か、今やキャップされるべきユーザーを抑制しそこなう（過少抑制）かのいずれかです。
fcap ルールが変わるとき、バイヤーのポリシー所有者（通常はインプレッショントラッカーまたはそのパイプラインのサービス）は、ルールが適用したすべてのキャップ状態エントリを再評価し、適切な更新を IdentityMatch キャップ状態ストアにプッシュしなければなりません（MUST）。2 つのイベント形状がケースをカバーします:
再評価は、キャップ状態ストアではなくバイヤー自身のカウント状態（インプレッション履歴が存在する場所）で実行されます — キャップ状態ストアはカウントを運びません。出力は、適用する削除または延長イベントのセットです。
adcp-go/targeting/fcap のリファレンスストアは、延長をネイティブに実装します（同じ (user_identity, field) の 2 番目の RecordCap が HSETEX 経由で以前の expire_at を上書き）。削除は将来の拡張です — 今日、最もシンプルな回避策は、既に過去の expire_at で延長することで、これにより次のクエリでエントリが欠如として扱われ、バックエンドの TTL 機構によって刈り取られます。
再評価は、ポリシーが多くのユーザーに適用されるとき高価になりえます。バイヤーは通常それを非同期に実行します: ポリシー変更イベントをエンキューし、影響を受けるユーザー母集団をバッチでスイープし、削除/延長イベントを段階的にプッシュ。プロトコルはケイデンスを制約しません — キャップ状態が現在のポリシーが示すものに収束しなければならないという結果整合性要件のみ。
リファレンス実装
adcp-go/targeting/fcap のキャップ状態ストア API がリファレンス形状です。2 つの操作を公開します:
Field は {SellerAgentURL, PackageID} です。リファレンスストアは Valkey 9 ハッシュに裏付けられ、ユーザーアイデンティティでハッシュされ、(seller_agent_url, package_id) タプルごとに 1 つのハッシュフィールドと expire_at に設定された TTL を持ちます。他のバックエンド（Aerospike、DynamoDB、インメモリ、何でも）は、上記の境界コントラクトを満たせば準拠です。
Future extensions
今日、キャップ状態ストアは(user_identity, seller_agent_url, package_id) でキー付けされます。将来のプロトコルバージョンは、フィールドを追加の次元 — 広告主、キャンペーン、クリエイティブ、ラインアイテム — に拡張し、バイヤーがすべてのキャップ発火で N エントリを書かずに複数のパッケージにまたがるキャップを表現できるようにするかもしれません。このページの境界コントラクトはそのような拡張で変わりません: インプレッショントラッカーがキャップ発火エントリを書き、Identity Match サービスがクエリ時に存在を確認します。
関連項目
- TMP 仕様 — ワイヤー仕様、TMPX 形式、適合性不変条件
- インプレッショントラッカー実装リファレンス — 境界のインプレッショントラッカー側の非規範的リファレンス（
impression_id経由のマルチアイデンティティ重複排除、fcap_keys ラベルモデル、ログベースのリファレンスデータモデル、SDK プリミティブ） - バイヤーガイド — バイヤーエージェント統合、Context Match + Identity Match フロー
- AXE からの移行 — OpenRTB User.eids クロスウォークを含む、AXE 形状のパイプラインから移行するバイヤー向け
- プライバシーアーキテクチャ — 各当事者が学ぶもの
- ルーターアーキテクチャ — プロバイダー登録、ファンアウト、レイテンシー
adcp-go/targeting/fcap— Go のリファレンスキャップ状態ストア