Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/trusted-match/context-and-identity.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -149,14 +149,14 @@ Note what is absent: no URL, no search query, no content signals, no topic IDs.
"type": "identity_match_response",
"request_id": "id-9b2c",
"eligible_package_ids": ["pkg-A", "pkg-B"],
"ttl_sec": 60,
"serve_window_sec": 60,
"tmpx": "k1.dG1weC1leGFtcGxlLWVuY3J5cHRlZC10b2tlbi4uLg"
}
```

The buyer reports that this user is eligible for packages A and B. Package C is absent — the user is not eligible. The publisher does not need to know why — frequency capping, audience mismatch, and other disqualification reasons are buyer-internal.

The `ttl_sec: 60` tells the router: "Cache this for 60 seconds." The router uses this cached eligibility to fill whatever placements exist — a single slot, a CTV ad pod, or a page with multiple ad units — without re-querying the buyer. The publisher decides how to allocate across placements.
The `serve_window_sec: 60` tells the router: "Cache this for 60 seconds." The router uses this cached eligibility to fill whatever placements exist — a single slot, a CTV ad pod, or a page with multiple ad units — without re-querying the buyer. The publisher decides how to allocate across placements.

### What Identity Match never carries

Expand Down
4 changes: 2 additions & 2 deletions docs/trusted-match/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -161,11 +161,11 @@ Response from Sam's buyer agent:
"type": "identity_match_response",
"request_id": "id-7c9e1d",
"eligible_package_ids": ["pkg-outdoor-audio"],
"ttl_sec": 60
"serve_window_sec": 60
}
```

Only eligible packages are listed — `pkg-outdoor-audio` passes the buyer's checks. The `ttl_sec: 60` tells the router to cache this eligibility for 60 seconds.
Only eligible packages are listed — `pkg-outdoor-audio` passes the buyer's checks. The `serve_window_sec: 60` tells the router to cache this eligibility for 60 seconds.

The example sends `package_ids` explicitly, but the publisher MAY omit it — Sam's identity-match service resolves the active package set from `seller_agent_url`. When `package_ids` IS sent, its composition MUST be independent of the current page — either all-active (every Sam package at StreamHaus) or fuzzed (a random sample padded with synthetic IDs that Sam will silently drop). A page-specific subset is forbidden; it would let the buyer correlate package sets across Context Match and Identity Match, breaking the structural separation.

Expand Down
2 changes: 1 addition & 1 deletion docs/trusted-match/router-architecture.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ The router filters Identity Match providers by country and identity type:
7. Because the per-provider payload differs from the inbound request, the router **re-signs** each per-provider forward using the canonical `identities_hash` of the filtered set. Providers verify signatures against the router's public key.
8. It fans out to all matching providers in parallel, merges eligibility results, and returns a unified response.

Duplicate `package_id` across providers is a configuration error — packages come from media buys and are provider-specific. If it occurs, the router applies conservative merging: the package is only eligible if it appears in `eligible_package_ids` from both providers. The router uses the minimum `ttl_sec` across providers and SHOULD log a warning.
Duplicate `package_id` across providers is a configuration error — packages come from media buys and are provider-specific. If it occurs, the router applies conservative merging: the package is only eligible if it appears in `eligible_package_ids` from both providers. The router uses the minimum `serve_window_sec` across providers and SHOULD log a warning.

### Timeout handling

Expand Down
4 changes: 2 additions & 2 deletions docs/trusted-match/surfaces/ai-assistants.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ The buyer responds with the IDs of eligible packages and a TTL. The buyer comput
"pkg-outdoor-gear",
"pkg-seasonal-sale"
],
"ttl_sec": 120
"serve_window_sec": 120
}
```

Expand Down Expand Up @@ -151,7 +151,7 @@ User message: "What are the best sneakers for spring?"
→ Router returns merged response

→ (300ms later) Platform sends Identity Match with ALL buyer's active packages
→ Response: eligible_package_ids includes pkg-sneaker-reco, ttl_sec: 120
→ Response: eligible_package_ids includes pkg-sneaker-reco, serve_window_sec: 120
→ Router caches eligibility

→ Platform joins: pkg-sneaker-reco offer is eligible
Expand Down
6 changes: 3 additions & 3 deletions docs/trusted-match/surfaces/ctv.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,11 @@ Each buyer agent evaluates the household token against its own data (frequency c
"pkg-vaultline-audio",
"pkg-driftmoto-30s"
],
"ttl_sec": 90
"serve_window_sec": 90
}
```

The response covers all packages, not just CTV ones. The `ttl_sec: 90` covers the duration of the ad break — the router uses cached eligibility to fill all pod slots without re-querying. The publisher extracts only the package IDs relevant to the current pod.
The response covers all packages, not just CTV ones. The `serve_window_sec: 90` covers the duration of the ad break — the router uses cached eligibility to fill all pod slots without re-querying. The publisher extracts only the package IDs relevant to the current pod.

## Pod Composition

Expand Down Expand Up @@ -198,7 +198,7 @@ Mid-roll break in "The Night Kitchen" S02E07
Identity Match (after temporal decorrelation — random delay + random order)
--> Broadcaster sends request: all 9 active packages across all buyers
--> Response: eligible_package_ids includes Sparklean, Greenleaf, Vaultline, Driftmoto-30s
--> ttl_sec: 90 (covers the ad break)
--> serve_window_sec: 90 (covers the ad break)
Pod Assembly (broadcaster's ad server)
--> Join: Sparklean and Greenleaf both activated and eligible
Expand Down
4 changes: 2 additions & 2 deletions docs/trusted-match/surfaces/mobile.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -194,13 +194,13 @@ Seven package IDs — the example uses all-active mode (every active package for
"pkg-sports-banner-05",
"pkg-sports-rewarded-07"
],
"ttl_sec": 60
"serve_window_sec": 60
}
```

Only eligible packages are listed. The buyer computes eligibility from frequency caps, audience membership, purchase history, and any other identity-based signals. The reasons are opaque to the publisher. The publisher does not learn why `pkg-telecom-inter-03` is ineligible — just that it is absent from the list.

The `ttl_sec` tells the router how long to cache this response. During the TTL window, the router uses cached eligibility to fill interstitials, banners, and rewarded ads without re-querying the buyer.
The `serve_window_sec` tells the router how long to cache this response. During the TTL window, the router uses cached eligibility to fill interstitials, banners, and rewarded ads without re-querying the buyer.

## Joining and Activation

Expand Down
4 changes: 2 additions & 2 deletions docs/trusted-match/surfaces/retail-media.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ The buyer responds with the IDs of eligible packages and a TTL:
"pkg-bakery-seasonal",
"pkg-frozen-meals"
],
"ttl_sec": 60
"serve_window_sec": 60
}
```

Expand All @@ -122,7 +122,7 @@ Shopper searches "cold brew"
→ Buyer: offer with creative manifest (cold brew + iced latte items, promo banner, badges)

→ (fuzzed) Retailer sends Identity Match: loyalty token + all active package IDs
→ Buyer: eligible_package_ids includes pkg-coffee-sponsored, ttl_sec: 60
→ Buyer: eligible_package_ids includes pkg-coffee-sponsored, serve_window_sec: 60

→ Retailer joins: accept offer, render items from creative manifest
→ Render sponsored carousel in search results
Expand Down
4 changes: 2 additions & 2 deletions docs/trusted-match/surfaces/web.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -119,14 +119,14 @@ The buyer evaluates the user against all requested packages and returns the IDs
"pkg-native-0079",
"pkg-display-0104"
],
"ttl_sec": 60
"serve_window_sec": 60
}
```

Key points:

- Only eligible packages are listed. Packages absent from the list (e.g., `pkg-display-0043`, `pkg-display-0103`, `pkg-video-0201`) are ineligible. The buyer computes eligibility from frequency caps, audience membership, purchase history, and any other identity-based signals. The reasons are opaque to the publisher.
- `ttl_sec` tells the router how long to cache this response. During that window, the router returns cached eligibility without re-querying the buyer. The publisher uses cached eligibility to allocate across all placements on the page.
- `serve_window_sec` tells the router how long to cache this response. During that window, the router returns cached eligibility without re-querying the buyer. The publisher uses cached eligibility to allocate across all placements on the page.
- There is no `frequency_capped`, `audience_match`, or `recency` field. The buyer's internal reasons stay with the buyer.

## Activation: Joining Context and Identity
Expand Down
2 changes: 1 addition & 1 deletion tests/example-validation-simple.test.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -581,7 +581,7 @@ async function runTests() {
"type": "identity_match_response",
"request_id": "id-7c9e1d",
"eligible_package_ids": ["pkg-outdoor-audio"],
"ttl_sec": 60
"serve_window_sec": 60
},
'/schemas/tmp/identity-match-response.json',
'TMP Identity Match response — web (overview walkthrough)'
Expand Down
Loading