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

# Identity Match フリークエンシーキャップデータフロー

> フリークエンシーキャッピングのためのインプレッショントラッカーと Identity Match サービス間の境界コントラクト — データフローのみ。内部カウント、ポリシー評価、ストレージレイアウトはバイヤー内部の関心事。

# Identity Match フリークエンシーキャップデータフロー

このページは、フリークエンシーキャップの状態がどう Identity Match サービスに到達し、Identity Match が適格性時にどうそれを消費するかを記述します。それは **データフローのみ** を定義します — インプレッショントラッカーと Identity Match サービスの間の境界を越えるもの。内部メカニクス（インプレッショントラッカーがどうインプレッションをカウントするか、ポリシーがどこに存在するか、Identity Match サービスがどのストレージレイアウトを使うか、アイデンティティが上流でどう重複排除されるか）はバイヤー内部の関心事で、ここではスコープ外です。

ワイヤー仕様は [TMP 仕様](/docs/trusted-match/specification) に存在します。Identity Match サービスが満たさなければならない適合性不変条件もそこで規範的です。Identity Match キャップ状態ストアのリファレンス実装は [`adcp-go/targeting/fcap`](https://github.com/adcontextprotocol/adcp-go/tree/main/targeting/fcap) で出荷されます。

## ロール

| Component                          | Responsibility                                                                                                                                             |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Identity Match service**         | クエリ時に `eligible_package_ids` — ユーザーが現在キャップされていない（そして他の適格性チェックを通過する）要求されたパッケージのサブセット — を返す。インプレッションをカウントせず、fcap ポリシーを所有しない。                                 |
| **Impression tracker**             | ピクセル発火を受け取り、TMPX をデコードし、バイヤーの fcap ポリシー（カウント、ウィンドウ化、マルチアイデンティティ重複排除、バイヤーのポリシーロジックが行う何でも）を適用し、キャップを使い果たすインプレッションで Identity Match キャップ状態ストアに「キャップ発火」をシグナルする。 |
| **Identity Match cap-state store** | TTL を伴う `(user_identity, package) → cap-until` エントリを記録。適格性時に Identity Match サービスによってクエリされる。インプレッショントラッカー（またはそのパイプラインの下流サービス）によって書き込まれる。                    |

分割は意図的です: インプレッションのカウント、ウィンドウの評価、キャップがいつ発火するかの決定は、バイヤーとキャンペーンをまたいで異なるバイヤー内部のポリシー関心事です。Identity Match サービスは狭いまま — 「このユーザーはこのパッケージについて現在キャップされているか？」に答え、それ以上はしません。新しいキャップ次元（広告主、キャンペーン、クリエイティブ — [extensions](#future-extensions) を参照）は、サービスを変えずに同じ境界コントラクトに接続します。

## エンドツーエンドフロー

```
1. Identity Match query
   publisher → router → Identity Match service
   Identity Match looks up cap state for each (identity, package) pair
   returns eligible_package_ids + tmpx (HPKE-encrypted resolved identities)

2. Ad serves; creative tracking URL fires pixel with {TMPX}
   publisher's player/page → impression tracker

3. Impression tracker decodes TMPX
   → resolved identities + signed package context (seller_agent_url, package_id)

4. Impression tracker applies the buyer's fcap policies
   → counts this exposure against whatever dimensions the buyer caps on
     (package, campaign, advertiser, creative, line item, …) for each
     resolved identity, using whatever policy logic and storage the buyer
     runs internally

5. If this impression exhausts a cap (i.e., it is the last allowed exposure
   under one of the buyer's policies), the impression tracker (or a
   downstream service in its pipeline) writes a cap-fire entry to the
   Identity Match cap-state store:
     (user_identity, package) capped until <expireAt>

6. Subsequent Identity Match queries for that user see the cap-state entry
   and exclude the package from eligible_package_ids until the entry expires
```

ステップ 1、2、6 はワイヤーを越え、[TMP 仕様](/docs/trusted-match/specification) で規範的に定義されます。ステップ 3 と 5 はインプレッショントラッカー → キャップ状態ストアの境界を越え、このページで定義されます。ステップ 4 はバイヤー内部 — プロトコルはそれを制約しません。

## The cap-fire event

バイヤーのポリシー評価が、インプレッションがキャップを使い果たしたと判断すると、インプレッショントラッカーは Identity Match キャップ状態ストアにキャップ発火エントリを書き込みます。各エントリは次から成ります:

| Field              | Description                                                                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_identity`    | キャップが発火した解決されたアイデンティティトークン（例: `rampid:abc`、`id5:def`、`maid:ghi`）。単一のインプレッションが複数のアイデンティティに解決しポリシーがそのすべてで発火した場合、インプレッショントラッカーはアイデンティティごとに 1 エントリを書き込む。 |
| `seller_agent_url` | パッケージが属するセラーエージェント。セラーをまたいで同一の `package_id` 文字列を曖昧性解消。                                                                                               |
| `package_id`       | キャップが発火したパッケージ。                                                                                                                                      |
| `expire_at`        | キャップが期限切れになる壁時計時刻。キャップ状態ストアはこれを TTL として強制する — エントリは `expire_at` の後は欠如する。                                                                             |

単一のキャップ発火イベントは通常 1 エントリに対応します。複数の解決されたアイデンティティまたは複数のパッケージで発火するキャップは、バイヤーのポリシーが同じなら同じ `expire_at` を共有する `(identity, package)` ペアごとに 1 エントリを生成します。

キャップ状態ストアは、インプレッションごとのカウント、ポリシー定義、ウィンドウ設定を記録しません。その唯一の仕事は「この `(user_identity, package)` は現在キャップされているか？」に答えることです。バイヤーのポリシーロジック — カウント、ウィンドウ化、キャップする次元の選択、いつ発火するかの決定 — は完全にインプレッショントラッカーに存在します。

## 適格性クエリ

クエリ時に、Identity Match サービスはアイデンティティのリストと候補パッケージのリストを受け取ります。各候補パッケージについて、ユーザーのアイデンティティにわたって一致する `(identity, package)` エントリをキャップ状態ストアで確認します。任意のエントリが存在すれば、パッケージは `eligible_package_ids` から除外されます。これは存在チェックであり、カウントではありません。

キャップ状態は適格性への 1 つの入力です。Identity Match サービスは、オーディエンスメンバーシップ、パッケージのアクティブ状態、オーディエンス鮮度、バイヤーが気にする他の任意の入力も評価します — [適合性不変条件](/docs/trusted-match/specification#conformance-invariants-for-identitymatch-eligibility) を参照。その評価のキャップ状態の部分が、このページが定義する部分です。

## Policy updates and cap-state re-evaluation

キャップ状態エントリは、キャップ発火時に有効だった fcap ポリシーの下で書き込まれます。バイヤーの fcap ポリシーが変わるとき — ウィンドウが短縮または延長、`max_count` が上昇または下降、ポリシーが一時停止または削除、パッケージが異なるポリシーに再割り当て — 古いポリシーの下で書き込まれた既存のキャップ状態エントリは古くなりうる。古いエントリは、今や適格であるべきユーザーを抑制する（過剰抑制）か、今やキャップされるべきユーザーを抑制しそこなう（過少抑制）かのいずれかです。

fcap ルールが変わるとき、バイヤーのポリシー所有者（通常はインプレッショントラッカーまたはそのパイプラインのサービス）は、ルールが適用したすべてのキャップ状態エントリを再評価し、適切な更新を IdentityMatch キャップ状態ストアにプッシュしなければなりません（MUST）。2 つのイベント形状がケースをカバーします:

| Event                | When to push                                                                                                              | Effect on cap-state                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Delete cap-state** | 新しいポリシーの下でのユーザーの露出カウントが新しい `max_count` 未満、またはポリシーが削除/無効化、またはパッケージがポリシーから再割り当て。                                            | `(user_identity, package)` エントリを削除 — ユーザーはそのパッケージについてもう抑制されない。 |
| **Extend cap-state** | ユーザーが新しいポリシーの下でまだキャップ超過だが、新しい `expire_at` が既存エントリと異なる — 例えばウィンドウが延長（より遅い `expire_at` をプッシュ）または短縮（より早い `expire_at` をプッシュ）。 | 新しい `expire_at` でエントリを上書き。                                     |

再評価は、キャップ状態ストアではなくバイヤー自身のカウント状態（インプレッション履歴が存在する場所）で実行されます — キャップ状態ストアはカウントを運びません。出力は、適用する削除または延長イベントのセットです。

[`adcp-go/targeting/fcap`](https://github.com/adcontextprotocol/adcp-go/tree/main/targeting/fcap) のリファレンスストアは、延長をネイティブに実装します（同じ `(user_identity, field)` の 2 番目の `RecordCap` が `HSETEX` 経由で以前の `expire_at` を上書き）。削除は将来の拡張です — 今日、最もシンプルな回避策は、既に過去の `expire_at` で延長することで、これにより次のクエリでエントリが欠如として扱われ、バックエンドの TTL 機構によって刈り取られます。

再評価は、ポリシーが多くのユーザーに適用されるとき高価になりえます。バイヤーは通常それを非同期に実行します: ポリシー変更イベントをエンキューし、影響を受けるユーザー母集団をバッチでスイープし、削除/延長イベントを段階的にプッシュ。プロトコルはケイデンスを制約しません — キャップ状態が現在のポリシーが示すものに収束しなければならないという結果整合性要件のみ。

## リファレンス実装

[`adcp-go/targeting/fcap`](https://github.com/adcontextprotocol/adcp-go/tree/main/targeting/fcap) のキャップ状態ストア API がリファレンス形状です。2 つの操作を公開します:

```go theme={null}
RecordCap(ctx, userIdentity string, fields []Field, expireAt time.Time) error
IsCapped(ctx, userIdentity string, field Field) (bool, error)
```

— に加え両方のバッチバリアント。`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 仕様](/docs/trusted-match/specification) — ワイヤー仕様、TMPX 形式、適合性不変条件
* [インプレッショントラッカー実装リファレンス](/docs/trusted-match/impression-tracker-implementation) — 境界のインプレッショントラッカー側の非規範的リファレンス（`impression_id` 経由のマルチアイデンティティ重複排除、fcap\_keys ラベルモデル、ログベースのリファレンスデータモデル、SDK プリミティブ）
* [バイヤーガイド](/docs/trusted-match/buyer-guide) — バイヤーエージェント統合、Context Match + Identity Match フロー
* [AXE からの移行](/docs/trusted-match/migration-from-axe) — OpenRTB User.eids クロスウォークを含む、AXE 形状のパイプラインから移行するバイヤー向け
* [プライバシーアーキテクチャ](/docs/trusted-match/privacy-architecture) — 各当事者が学ぶもの
* [ルーターアーキテクチャ](/docs/trusted-match/router-architecture) — プロバイダー登録、ファンアウト、レイテンシー
* [`adcp-go/targeting/fcap`](https://github.com/adcontextprotocol/adcp-go/tree/main/targeting/fcap) — Go のリファレンスキャップ状態ストア