@adcp/sdk 14.0.0 → 14.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/lib/adapters/implicit-account-store.d.mts +12 -7
- package/dist/lib/adapters/implicit-account-store.d.ts +12 -7
- package/dist/lib/adapters/implicit-account-store.js +69 -15
- package/dist/lib/adapters/implicit-account-store.mjs +69 -15
- package/dist/lib/core/AgentClient.d.mts +1 -0
- package/dist/lib/core/AgentClient.d.ts +1 -0
- package/dist/lib/core/AgentClient.js +3 -0
- package/dist/lib/core/AgentClient.mjs +3 -0
- package/dist/lib/core/SingleAgentClient.d.mts +35 -2
- package/dist/lib/core/SingleAgentClient.d.ts +35 -2
- package/dist/lib/core/SingleAgentClient.js +377 -36
- package/dist/lib/core/SingleAgentClient.mjs +387 -38
- package/dist/lib/core/TaskExecutor.d.mts +3 -1
- package/dist/lib/core/TaskExecutor.d.ts +3 -1
- package/dist/lib/core/TaskExecutor.js +17 -12
- package/dist/lib/core/TaskExecutor.mjs +17 -12
- package/dist/lib/core/account-key.d.mts +3 -0
- package/dist/lib/core/account-key.d.ts +3 -0
- package/dist/lib/core/account-key.js +41 -0
- package/dist/lib/core/account-key.mjs +17 -0
- package/dist/lib/core/account-resolution.d.mts +2 -0
- package/dist/lib/core/account-resolution.d.ts +2 -0
- package/dist/lib/core/buyer-account-registry.d.mts +93 -0
- package/dist/lib/core/buyer-account-registry.d.ts +93 -0
- package/dist/lib/core/buyer-account-registry.js +602 -0
- package/dist/lib/core/buyer-account-registry.mjs +578 -0
- package/dist/lib/core/product-cache.d.mts +18 -0
- package/dist/lib/core/product-cache.d.ts +18 -0
- package/dist/lib/core/product-cache.js +137 -0
- package/dist/lib/core/product-cache.mjs +112 -0
- package/dist/lib/errors/index.d.mts +40 -1
- package/dist/lib/errors/index.d.ts +40 -1
- package/dist/lib/errors/index.js +69 -3
- package/dist/lib/errors/index.mjs +64 -3
- package/dist/lib/governance/authorization.d.mts +17 -1
- package/dist/lib/governance/authorization.d.ts +17 -1
- package/dist/lib/governance/authorization.js +55 -7
- package/dist/lib/governance/authorization.mjs +59 -7
- package/dist/lib/governance/index.d.mts +2 -2
- package/dist/lib/governance/index.d.ts +2 -2
- package/dist/lib/governance/index.js +2 -0
- package/dist/lib/governance/index.mjs +3 -1
- package/dist/lib/index.d.mts +7 -4
- package/dist/lib/index.d.ts +7 -4
- package/dist/lib/index.js +29 -0
- package/dist/lib/index.mjs +31 -1
- package/dist/lib/net/agent-transport-fetch.d.mts +4 -0
- package/dist/lib/net/agent-transport-fetch.d.ts +4 -0
- package/dist/lib/net/agent-transport-fetch.js +18 -5
- package/dist/lib/net/agent-transport-fetch.mjs +17 -5
- package/dist/lib/protocols/a2a.js +9 -1
- package/dist/lib/protocols/a2a.mjs +9 -1
- package/dist/lib/protocols/index.js +9 -2
- package/dist/lib/protocols/index.mjs +9 -2
- package/dist/lib/protocols/mcp-modern.js +2 -1
- package/dist/lib/protocols/mcp-modern.mjs +2 -1
- package/dist/lib/protocols/mcp.js +5 -2
- package/dist/lib/protocols/mcp.mjs +5 -2
- package/dist/lib/protocols/rawResponseCapture.d.mts +6 -0
- package/dist/lib/protocols/rawResponseCapture.d.ts +6 -0
- package/dist/lib/protocols/rawResponseCapture.js +41 -29
- package/dist/lib/protocols/rawResponseCapture.mjs +40 -29
- package/dist/lib/protocols/signedRequestRejection.d.mts +9 -0
- package/dist/lib/protocols/signedRequestRejection.d.ts +9 -0
- package/dist/lib/protocols/signedRequestRejection.js +209 -0
- package/dist/lib/protocols/signedRequestRejection.mjs +189 -0
- package/dist/lib/protocols/transportDiagnostics.d.mts +1 -0
- package/dist/lib/protocols/transportDiagnostics.d.ts +1 -0
- package/dist/lib/protocols/transportDiagnostics.js +2 -0
- package/dist/lib/protocols/transportDiagnostics.mjs +1 -0
- package/dist/lib/registry/types.generated.d.mts +112 -45
- package/dist/lib/registry/types.generated.d.ts +112 -45
- package/dist/lib/schemas-data/v2.5/_provenance.json +1 -1
- package/dist/lib/server/account-provisioning.d.mts +2 -0
- package/dist/lib/server/account-provisioning.d.ts +2 -0
- package/dist/lib/server/account-provisioning.js +30 -0
- package/dist/lib/server/account-provisioning.mjs +6 -0
- package/dist/lib/server/account-reference-warnings.d.mts +12 -0
- package/dist/lib/server/account-reference-warnings.d.ts +12 -0
- package/dist/lib/server/account-reference-warnings.js +48 -0
- package/dist/lib/server/account-reference-warnings.mjs +23 -0
- package/dist/lib/server/auth-signature.js +1 -0
- package/dist/lib/server/auth-signature.mjs +1 -0
- package/dist/lib/server/create-adcp-server.d.mts +34 -0
- package/dist/lib/server/create-adcp-server.d.ts +34 -0
- package/dist/lib/server/create-adcp-server.js +225 -14
- package/dist/lib/server/create-adcp-server.mjs +225 -14
- package/dist/lib/server/decisioning/account.d.mts +2 -0
- package/dist/lib/server/decisioning/account.d.ts +2 -0
- package/dist/lib/server/decisioning/runtime/from-platform.js +49 -10
- package/dist/lib/server/decisioning/runtime/from-platform.mjs +49 -10
- package/dist/lib/server/index.d.mts +2 -2
- package/dist/lib/server/index.d.ts +2 -2
- package/dist/lib/server/index.js +2 -0
- package/dist/lib/server/index.mjs +3 -1
- package/dist/lib/signing/agent-resolver/consistency.d.mts +6 -13
- package/dist/lib/signing/agent-resolver/consistency.d.ts +6 -13
- package/dist/lib/signing/agent-resolver/consistency.js +0 -1
- package/dist/lib/signing/agent-resolver/consistency.mjs +0 -1
- package/dist/lib/signing/agent-resolver/errors.d.mts +3 -1
- package/dist/lib/signing/agent-resolver/errors.d.ts +3 -1
- package/dist/lib/signing/agent-resolver/errors.js +6 -0
- package/dist/lib/signing/agent-resolver/errors.mjs +6 -0
- package/dist/lib/signing/agent-resolver/fetch-helpers.d.mts +11 -0
- package/dist/lib/signing/agent-resolver/fetch-helpers.d.ts +11 -0
- package/dist/lib/signing/agent-resolver/fetch-helpers.js +37 -2
- package/dist/lib/signing/agent-resolver/fetch-helpers.mjs +40 -3
- package/dist/lib/signing/agent-resolver/jwks-set.js +24 -3
- package/dist/lib/signing/agent-resolver/jwks-set.mjs +24 -3
- package/dist/lib/signing/agent-resolver/legacy-brand.d.mts +15 -0
- package/dist/lib/signing/agent-resolver/legacy-brand.d.ts +15 -0
- package/dist/lib/signing/agent-resolver/legacy-brand.js +60 -0
- package/dist/lib/signing/agent-resolver/legacy-brand.mjs +36 -0
- package/dist/lib/signing/agent-resolver/operator-authorization.d.mts +13 -0
- package/dist/lib/signing/agent-resolver/operator-authorization.d.ts +13 -0
- package/dist/lib/signing/agent-resolver/operator-authorization.js +108 -0
- package/dist/lib/signing/agent-resolver/operator-authorization.mjs +84 -0
- package/dist/lib/signing/agent-resolver/resolve-agent.d.mts +14 -4
- package/dist/lib/signing/agent-resolver/resolve-agent.d.ts +14 -4
- package/dist/lib/signing/agent-resolver/resolve-agent.js +148 -137
- package/dist/lib/signing/agent-resolver/resolve-agent.mjs +157 -139
- package/dist/lib/signing/agent-resolver/resolved-agent-jwks.d.mts +7 -1
- package/dist/lib/signing/agent-resolver/resolved-agent-jwks.d.ts +7 -1
- package/dist/lib/signing/agent-resolver/resolved-agent-jwks.js +50 -17
- package/dist/lib/signing/agent-resolver/resolved-agent-jwks.mjs +50 -17
- package/dist/lib/signing/agent-resolver/select-agent.d.mts +14 -15
- package/dist/lib/signing/agent-resolver/select-agent.d.ts +14 -15
- package/dist/lib/signing/agent-resolver/select-agent.js +98 -13
- package/dist/lib/signing/agent-resolver/select-agent.mjs +95 -13
- package/dist/lib/signing/brand-jwks.d.mts +29 -75
- package/dist/lib/signing/brand-jwks.d.ts +29 -75
- package/dist/lib/signing/brand-jwks.js +120 -182
- package/dist/lib/signing/brand-jwks.mjs +120 -182
- package/dist/lib/signing/errors.d.mts +7 -3
- package/dist/lib/signing/errors.d.ts +7 -3
- package/dist/lib/signing/errors.js +7 -2
- package/dist/lib/signing/errors.mjs +7 -2
- package/dist/lib/signing/jwks-https.d.mts +7 -0
- package/dist/lib/signing/jwks-https.d.ts +7 -0
- package/dist/lib/signing/jwks-https.js +31 -8
- package/dist/lib/signing/jwks-https.mjs +31 -8
- package/dist/lib/signing/jwks.d.mts +8 -0
- package/dist/lib/signing/jwks.d.ts +8 -0
- package/dist/lib/signing/middleware.js +2 -1
- package/dist/lib/signing/middleware.mjs +2 -1
- package/dist/lib/signing/publisher-pins.d.mts +11 -0
- package/dist/lib/signing/publisher-pins.d.ts +11 -0
- package/dist/lib/signing/publisher-pins.js +125 -0
- package/dist/lib/signing/publisher-pins.mjs +101 -0
- package/dist/lib/signing/server.d.mts +1 -0
- package/dist/lib/signing/server.d.ts +1 -0
- package/dist/lib/signing/types.d.mts +5 -0
- package/dist/lib/signing/types.d.ts +5 -0
- package/dist/lib/signing/verifier.js +50 -5
- package/dist/lib/signing/verifier.mjs +50 -5
- package/dist/lib/signing/webhook-verifier.d.mts +7 -2
- package/dist/lib/signing/webhook-verifier.d.ts +7 -2
- package/dist/lib/signing/webhook-verifier.js +42 -2
- package/dist/lib/signing/webhook-verifier.mjs +42 -2
- package/dist/lib/testing/storyboard/account-policy.d.mts +2 -0
- package/dist/lib/testing/storyboard/account-policy.d.ts +2 -0
- package/dist/lib/testing/storyboard/account-policy.js +35 -0
- package/dist/lib/testing/storyboard/account-policy.mjs +11 -0
- package/dist/lib/testing/storyboard/context.js +6 -0
- package/dist/lib/testing/storyboard/context.mjs +6 -0
- package/dist/lib/testing/storyboard/request-builder.js +12 -2
- package/dist/lib/testing/storyboard/request-builder.mjs +12 -2
- package/dist/lib/testing/storyboard/runner.js +3 -2
- package/dist/lib/testing/storyboard/runner.mjs +3 -2
- package/dist/lib/testing/storyboard/validations.d.mts +1 -1
- package/dist/lib/testing/storyboard/validations.d.ts +1 -1
- package/dist/lib/types/accept-proposal.d.ts +19 -1
- package/dist/lib/types/buy-products.d.ts +19 -1
- package/dist/lib/types/check-governance.d.ts +19 -1
- package/dist/lib/types/comply-test-controller.d.ts +19 -1
- package/dist/lib/types/control-media-buy.d.ts +19 -1
- package/dist/lib/types/core.generated.d.mts +14 -1
- package/dist/lib/types/core.generated.d.ts +14 -1
- package/dist/lib/types/create-media-buy.d.ts +14 -1
- package/dist/lib/types/get-media-buys.d.ts +14 -1
- package/dist/lib/types/get-products.d.ts +19 -1
- package/dist/lib/types/list-products.d.ts +19 -1
- package/dist/lib/types/refine-proposals.d.ts +19 -1
- package/dist/lib/types/request-proposals.d.ts +19 -1
- package/dist/lib/types/schemas.generated.d.ts +12 -3
- package/dist/lib/types/schemas.generated.js +4 -1
- package/dist/lib/types/schemas.generated.mjs +4 -1
- package/dist/lib/types/tools.generated.d.mts +14 -1
- package/dist/lib/types/tools.generated.d.ts +14 -1
- package/dist/lib/types/update-media-buy.d.ts +14 -1
- package/dist/lib/version.d.mts +3 -3
- package/dist/lib/version.d.ts +3 -3
- package/dist/lib/version.js +3 -3
- package/dist/lib/version.mjs +3 -3
- package/dist/lib/webhooks/index.d.mts +24 -0
- package/dist/lib/webhooks/index.d.ts +24 -0
- package/dist/lib/webhooks/index.js +50 -24
- package/dist/lib/webhooks/index.mjs +49 -24
- package/dist/lib/wholesale-feed-sync/index.d.mts +2 -0
- package/dist/lib/wholesale-feed-sync/index.d.ts +2 -0
- package/dist/lib/wholesale-feed-sync/index.js +7 -0
- package/dist/lib/wholesale-feed-sync/index.mjs +4 -0
- package/dist/lib/wholesale-feed-sync/mirror.d.mts +97 -0
- package/dist/lib/wholesale-feed-sync/mirror.d.ts +97 -0
- package/dist/lib/wholesale-feed-sync/mirror.js +350 -0
- package/dist/lib/wholesale-feed-sync/mirror.mjs +322 -0
- package/dist/lib/wholesale-feed-sync/sync.d.mts +13 -29
- package/dist/lib/wholesale-feed-sync/sync.d.ts +13 -29
- package/dist/lib/wholesale-feed-sync/sync.js +208 -281
- package/dist/lib/wholesale-feed-sync/sync.mjs +213 -281
- package/dist/lib/wholesale-feed-sync/types.d.mts +4 -3
- package/dist/lib/wholesale-feed-sync/types.d.ts +4 -3
- package/docs/README.md +6 -0
- package/docs/TYPE-SUMMARY.md +2 -2
- package/docs/guides/BUILD-AN-AGENT.md +2 -2
- package/docs/guides/BUYER-QUICKSTART-3.2.md +2 -0
- package/docs/guides/BUYER-STORAGE.md +3 -0
- package/docs/guides/FIRST-CALL-TO-A-SELLER.md +106 -0
- package/docs/guides/SIGNING-GUIDE.md +16 -7
- package/docs/guides/account-resolution.md +132 -10
- package/docs/llms.txt +3 -2
- package/docs/migration-14.0-to-14.1.md +85 -0
- package/docs/migration-14.x-rc-worksheet.md +4 -4
- package/docs/migration-4.x-to-5.x.md +1 -0
- package/docs/migration-agent-resolution-3.3.md +125 -0
- package/docs/recipes/verifying-inbound-webhooks.md +60 -15
- package/package.json +3 -2
- package/skills/adcp-brand.previous/SKILL.md +0 -200
- package/skills/adcp-creative.previous/SKILL.md +0 -305
- package/skills/adcp-governance.previous/SKILL.md +0 -566
- package/skills/adcp-measurement.previous/SKILL.md +0 -136
- package/skills/adcp-media-buy.previous/SKILL.md +0 -556
- package/skills/adcp-si.previous/SKILL.md +0 -206
- package/skills/adcp-signals.previous/SKILL.md +0 -204
|
@@ -1,566 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: adcp-governance
|
|
3
|
-
description: Execute AdCP Governance Protocol operations with governance agents - manage property lists, collection lists, content standards, and campaign governance (plans, checks, outcomes, audit trail). Use when users want to create include/exclude lists, set up brand safety rules, validate content delivery, register campaign plans, validate actions against policy, or produce internal/shareable audit trails.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# AdCP Governance Protocol
|
|
7
|
-
|
|
8
|
-
This skill enables you to execute the AdCP Governance Protocol with governance agents. Covers four areas: property lists (site-level targeting), collection lists (program-level targeting), content standards (brand safety rules), and campaign governance (plans, checks, outcomes, audit trail).
|
|
9
|
-
|
|
10
|
-
> **Buyer-side basics** — idempotency replay, `oneOf` variants, async `status:'submitted'` polling, error recovery from `adcp_error.issues[]` — live in `skills/call-adcp-agent/SKILL.md`. This skill covers per-task semantics only.
|
|
11
|
-
|
|
12
|
-
## Overview
|
|
13
|
-
|
|
14
|
-
The Governance Protocol provides 21 standardized tasks across four areas:
|
|
15
|
-
|
|
16
|
-
### Property Lists
|
|
17
|
-
| Task | Purpose | Response Time |
|
|
18
|
-
|------|---------|---------------|
|
|
19
|
-
| `create_property_list` | Create include/exclude list | ~1s |
|
|
20
|
-
| `update_property_list` | Modify list filters/properties | ~1s |
|
|
21
|
-
| `get_property_list` | Retrieve list with optional resolution | ~1-5s |
|
|
22
|
-
| `list_property_lists` | List all accessible lists | ~1s |
|
|
23
|
-
| `delete_property_list` | Delete a list | ~1s |
|
|
24
|
-
|
|
25
|
-
### Collection Lists
|
|
26
|
-
| Task | Purpose | Response Time |
|
|
27
|
-
|------|---------|---------------|
|
|
28
|
-
| `create_collection_list` | Create program-level list | ~1s |
|
|
29
|
-
| `update_collection_list` | Modify list | ~1s |
|
|
30
|
-
| `get_collection_list` | Retrieve with optional resolution | ~1-5s |
|
|
31
|
-
| `list_collection_lists` | List all accessible lists | ~1s |
|
|
32
|
-
| `delete_collection_list` | Delete a list | ~1s |
|
|
33
|
-
|
|
34
|
-
### Content Standards
|
|
35
|
-
| Task | Purpose | Response Time |
|
|
36
|
-
|------|---------|---------------|
|
|
37
|
-
| `create_content_standards` | Create brand safety rules | ~1s |
|
|
38
|
-
| `get_content_standards` | Retrieve standards by ID | ~1s |
|
|
39
|
-
| `update_content_standards` | Modify rules | ~1s |
|
|
40
|
-
| `list_content_standards` | List all accessible standards | ~1s |
|
|
41
|
-
| `calibrate_content` | Test content against standards | ~5-30s |
|
|
42
|
-
| `get_media_buy_artifacts` | Get creatives for compliance review | ~5s |
|
|
43
|
-
| `validate_content_delivery` | Audit delivery compliance | ~10-60s |
|
|
44
|
-
|
|
45
|
-
### Campaign Governance
|
|
46
|
-
| Task | Purpose | Response Time |
|
|
47
|
-
|------|---------|---------------|
|
|
48
|
-
| `sync_plans` | Push or update a campaign plan with budget authority and policies | ~1s |
|
|
49
|
-
| `check_governance` | Validate an action (intent or execution) against the plan | ~1-5s |
|
|
50
|
-
| `report_plan_outcome` | Report a completed action so plan budget state advances | ~1s |
|
|
51
|
-
| `get_plan_audit_logs` | Retrieve governance state, budget tracking, and audit trail | ~1-5s |
|
|
52
|
-
|
|
53
|
-
> **Experimental in 3.0.** Campaign governance may change between 3.x releases with at least 6 weeks' notice. Sellers MUST declare `governance.campaign` in `experimental_features` to participate. See [experimental status](/docs/reference/experimental-status).
|
|
54
|
-
|
|
55
|
-
## Typical Workflow
|
|
56
|
-
|
|
57
|
-
### Property Lists (site-level)
|
|
58
|
-
1. **Create list**: `create_property_list` with base properties and filters
|
|
59
|
-
2. **Resolve**: `get_property_list` with `resolve: true` to see matched properties
|
|
60
|
-
3. **Refine**: `update_property_list` to adjust filters
|
|
61
|
-
4. **Apply**: Reference `list_id` in `create_media_buy` targeting
|
|
62
|
-
|
|
63
|
-
### Collection Lists (program-level, CTV)
|
|
64
|
-
1. **Create list**: `create_collection_list` with distribution IDs or genre filters
|
|
65
|
-
2. **Resolve**: `get_collection_list` with `resolve: true` to see matched programs
|
|
66
|
-
3. **Apply**: Reference in campaign targeting for CTV brand safety
|
|
67
|
-
|
|
68
|
-
### Content Standards
|
|
69
|
-
1. **Create standards**: `create_content_standards` with rules
|
|
70
|
-
2. **Calibrate**: `calibrate_content` with test samples to validate configuration
|
|
71
|
-
3. **Monitor**: `get_media_buy_artifacts` + `validate_content_delivery` for ongoing compliance
|
|
72
|
-
|
|
73
|
-
### Campaign Governance
|
|
74
|
-
1. **Sync governance agents** to seller accounts via `sync_governance` (lives in the Accounts protocol)
|
|
75
|
-
2. **Register the plan**: `sync_plans` with budget authority, channel allocation, and resolved policy IDs
|
|
76
|
-
3. **Validate actions**: `check_governance` on intent (pre-discovery) and execution (pre-buy). Returns an opaque `governance_context` token the seller echoes on subsequent checks.
|
|
77
|
-
4. **Report outcomes**: `report_plan_outcome` so committed/remaining budget advances
|
|
78
|
-
5. **Audit and produce shareable views**: `get_plan_audit_logs` filtered by `governance_contexts` for the requesting party. See [audit trail: internal vs shareable views](/docs/governance/campaign/audit-trail).
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
|
|
82
|
-
## Task Reference
|
|
83
|
-
|
|
84
|
-
### create_property_list
|
|
85
|
-
|
|
86
|
-
Create a property list for brand safety and inventory targeting.
|
|
87
|
-
|
|
88
|
-
**Request:**
|
|
89
|
-
```json
|
|
90
|
-
{
|
|
91
|
-
"name": "Premium News Properties",
|
|
92
|
-
"description": "Tier 1 news publishers for brand campaigns",
|
|
93
|
-
"base_properties": [
|
|
94
|
-
{
|
|
95
|
-
"selection_type": "publisher_tags",
|
|
96
|
-
"publisher_domain": "publisher.com",
|
|
97
|
-
"tags": ["premium", "news"]
|
|
98
|
-
}
|
|
99
|
-
],
|
|
100
|
-
"filters": {
|
|
101
|
-
"countries_all": ["US", "GB"],
|
|
102
|
-
"channels_any": ["display", "video"]
|
|
103
|
-
},
|
|
104
|
-
"brand": {
|
|
105
|
-
"domain": "acmecorp.com"
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
**Key fields:**
|
|
111
|
-
- `name` (string, required): Human-readable name
|
|
112
|
-
- `description` (string, optional): Purpose of the list
|
|
113
|
-
- `base_properties` (array, optional): Property sources — `publisher_tags`, `publisher_ids`, or `identifiers`
|
|
114
|
-
- `filters` (object, optional): Resolution filters — `countries_all`, `channels_any`, `property_types`, `feature_requirements`, `exclude_identifiers`
|
|
115
|
-
- `brand` (object, optional): Brand reference for automatic rule inference
|
|
116
|
-
|
|
117
|
-
---
|
|
118
|
-
|
|
119
|
-
### update_property_list
|
|
120
|
-
|
|
121
|
-
Modify an existing property list.
|
|
122
|
-
|
|
123
|
-
**Request:**
|
|
124
|
-
```json
|
|
125
|
-
{
|
|
126
|
-
"list_id": "pl_abc123",
|
|
127
|
-
"filters": {
|
|
128
|
-
"countries_all": ["US", "GB", "DE"],
|
|
129
|
-
"channels_any": ["display", "video", "ctv"]
|
|
130
|
-
}
|
|
131
|
-
}
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
**Key fields:**
|
|
135
|
-
- `list_id` (string, required): Property list identifier
|
|
136
|
-
- `name`, `description` (string, optional): Update metadata
|
|
137
|
-
- `base_properties` (array, optional): Replace property sources
|
|
138
|
-
- `filters` (object, optional): Replace filter configuration
|
|
139
|
-
|
|
140
|
-
---
|
|
141
|
-
|
|
142
|
-
### get_property_list
|
|
143
|
-
|
|
144
|
-
Retrieve a property list with optional resolution.
|
|
145
|
-
|
|
146
|
-
**Request:**
|
|
147
|
-
```json
|
|
148
|
-
{
|
|
149
|
-
"list_id": "pl_abc123",
|
|
150
|
-
"resolve": true,
|
|
151
|
-
"max_results": 50
|
|
152
|
-
}
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
**Key fields:**
|
|
156
|
-
- `list_id` (string, required): Property list identifier
|
|
157
|
-
- `resolve` (boolean, optional): Resolve filters and return property identifiers (default: false)
|
|
158
|
-
- `max_results` (number, optional): Max properties when resolved
|
|
159
|
-
|
|
160
|
-
---
|
|
161
|
-
|
|
162
|
-
### list_property_lists
|
|
163
|
-
|
|
164
|
-
List all property lists accessible to the authenticated principal.
|
|
165
|
-
|
|
166
|
-
**Request:**
|
|
167
|
-
```json
|
|
168
|
-
{
|
|
169
|
-
"name_contains": "premium"
|
|
170
|
-
}
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
**Key fields:**
|
|
174
|
-
- `name_contains` (string, optional): Filter by name substring
|
|
175
|
-
- `max_results` (number, optional): Max results
|
|
176
|
-
|
|
177
|
-
---
|
|
178
|
-
|
|
179
|
-
### delete_property_list
|
|
180
|
-
|
|
181
|
-
Delete a property list.
|
|
182
|
-
|
|
183
|
-
**Request:**
|
|
184
|
-
```json
|
|
185
|
-
{
|
|
186
|
-
"list_id": "pl_abc123"
|
|
187
|
-
}
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
**Key fields:**
|
|
191
|
-
- `list_id` (string, required): Property list identifier to delete
|
|
192
|
-
|
|
193
|
-
---
|
|
194
|
-
|
|
195
|
-
### create_collection_list
|
|
196
|
-
|
|
197
|
-
Create a collection list for program-level brand safety (CTV, podcast, streaming).
|
|
198
|
-
|
|
199
|
-
**Request:**
|
|
200
|
-
```json
|
|
201
|
-
{
|
|
202
|
-
"name": "Family-Safe CTV Programs",
|
|
203
|
-
"description": "Programs suitable for family brand campaigns",
|
|
204
|
-
"base_collections": [
|
|
205
|
-
{
|
|
206
|
-
"selection_type": "publisher_genres",
|
|
207
|
-
"publisher_domain": "ctv-publisher.com",
|
|
208
|
-
"genres": ["family", "comedy"],
|
|
209
|
-
"genre_taxonomy": "iab_content_taxonomy_3.0"
|
|
210
|
-
}
|
|
211
|
-
],
|
|
212
|
-
"filters": {
|
|
213
|
-
"content_ratings_exclude": [
|
|
214
|
-
{ "system": "us_tv", "rating": "TV-MA" }
|
|
215
|
-
],
|
|
216
|
-
"kinds": ["series"]
|
|
217
|
-
},
|
|
218
|
-
"brand": {
|
|
219
|
-
"domain": "familybrand.com"
|
|
220
|
-
}
|
|
221
|
-
}
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
**Key fields:**
|
|
225
|
-
- `name` (string, required): Human-readable name
|
|
226
|
-
- `base_collections` (array, optional): Collection sources — `distribution_ids`, `publisher_collections`, or `publisher_genres`
|
|
227
|
-
- `filters` (object, optional): `content_ratings_exclude`, `content_ratings_include`, `genres_exclude`, `genres_include`, `kinds`, `production_quality`
|
|
228
|
-
- `brand` (object, optional): Brand reference
|
|
229
|
-
|
|
230
|
-
**Distribution identifier types:** `imdb_id`, `gracenote_id`, `eidr_id`
|
|
231
|
-
|
|
232
|
-
---
|
|
233
|
-
|
|
234
|
-
### update_collection_list
|
|
235
|
-
|
|
236
|
-
Modify an existing collection list.
|
|
237
|
-
|
|
238
|
-
**Request:**
|
|
239
|
-
```json
|
|
240
|
-
{
|
|
241
|
-
"list_id": "cl_abc123",
|
|
242
|
-
"filters": {
|
|
243
|
-
"content_ratings_exclude": [
|
|
244
|
-
{ "system": "us_tv", "rating": "TV-MA" },
|
|
245
|
-
{ "system": "us_tv", "rating": "TV-14" }
|
|
246
|
-
]
|
|
247
|
-
}
|
|
248
|
-
}
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
**Key fields:**
|
|
252
|
-
- `list_id` (string, required): Collection list identifier
|
|
253
|
-
- `base_collections`, `filters` (optional): Replace configuration
|
|
254
|
-
|
|
255
|
-
---
|
|
256
|
-
|
|
257
|
-
### get_collection_list
|
|
258
|
-
|
|
259
|
-
Retrieve a collection list with optional resolution.
|
|
260
|
-
|
|
261
|
-
**Request:**
|
|
262
|
-
```json
|
|
263
|
-
{
|
|
264
|
-
"list_id": "cl_abc123",
|
|
265
|
-
"resolve": true
|
|
266
|
-
}
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
**Key fields:**
|
|
270
|
-
- `list_id` (string, required): Collection list identifier
|
|
271
|
-
- `resolve` (boolean, optional): Resolve and return collection entries
|
|
272
|
-
- `max_results` (number, optional): Max collections when resolved
|
|
273
|
-
|
|
274
|
-
---
|
|
275
|
-
|
|
276
|
-
### list_collection_lists
|
|
277
|
-
|
|
278
|
-
List all collection lists accessible to the authenticated principal.
|
|
279
|
-
|
|
280
|
-
**Request:**
|
|
281
|
-
```json
|
|
282
|
-
{
|
|
283
|
-
"name_contains": "family"
|
|
284
|
-
}
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
---
|
|
288
|
-
|
|
289
|
-
### delete_collection_list
|
|
290
|
-
|
|
291
|
-
Delete a collection list.
|
|
292
|
-
|
|
293
|
-
**Request:**
|
|
294
|
-
```json
|
|
295
|
-
{
|
|
296
|
-
"list_id": "cl_abc123"
|
|
297
|
-
}
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
---
|
|
301
|
-
|
|
302
|
-
### create_content_standards
|
|
303
|
-
|
|
304
|
-
Create content standards (brand safety rules) for campaign compliance.
|
|
305
|
-
|
|
306
|
-
**Request:**
|
|
307
|
-
```json
|
|
308
|
-
{
|
|
309
|
-
"name": "Automotive Brand Safety",
|
|
310
|
-
"description": "Content rules for automotive brand campaigns",
|
|
311
|
-
"rules": [
|
|
312
|
-
{ "rule_type": "category", "action": "block", "value": "violence", "severity": "critical" },
|
|
313
|
-
{ "rule_type": "category", "action": "block", "value": "adult", "severity": "critical" },
|
|
314
|
-
{ "rule_type": "keyword", "action": "flag", "value": "accident", "severity": "medium" }
|
|
315
|
-
],
|
|
316
|
-
"brand": {
|
|
317
|
-
"domain": "automaker.com"
|
|
318
|
-
}
|
|
319
|
-
}
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
**Key fields:**
|
|
323
|
-
- `name` (string, required): Human-readable name
|
|
324
|
-
- `rules` (array, optional): Content rules — `rule_type`, `action` (allow/block/flag), `value`, `severity`
|
|
325
|
-
- `brand` (object, optional): Brand reference for automatic rule inference
|
|
326
|
-
|
|
327
|
-
---
|
|
328
|
-
|
|
329
|
-
### get_content_standards
|
|
330
|
-
|
|
331
|
-
Retrieve content standards by ID.
|
|
332
|
-
|
|
333
|
-
**Request:**
|
|
334
|
-
```json
|
|
335
|
-
{
|
|
336
|
-
"standards_id": "cs_abc123"
|
|
337
|
-
}
|
|
338
|
-
```
|
|
339
|
-
|
|
340
|
-
---
|
|
341
|
-
|
|
342
|
-
### update_content_standards
|
|
343
|
-
|
|
344
|
-
Modify existing content standards.
|
|
345
|
-
|
|
346
|
-
**Request:**
|
|
347
|
-
```json
|
|
348
|
-
{
|
|
349
|
-
"standards_id": "cs_abc123",
|
|
350
|
-
"rules": [
|
|
351
|
-
{ "rule_type": "category", "action": "block", "value": "violence", "severity": "critical" }
|
|
352
|
-
]
|
|
353
|
-
}
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
---
|
|
357
|
-
|
|
358
|
-
### list_content_standards
|
|
359
|
-
|
|
360
|
-
List all content standards accessible to the authenticated principal.
|
|
361
|
-
|
|
362
|
-
**Request:**
|
|
363
|
-
```json
|
|
364
|
-
{
|
|
365
|
-
"name_contains": "automotive"
|
|
366
|
-
}
|
|
367
|
-
```
|
|
368
|
-
|
|
369
|
-
---
|
|
370
|
-
|
|
371
|
-
### calibrate_content
|
|
372
|
-
|
|
373
|
-
Test content samples against content standards to validate configuration.
|
|
374
|
-
|
|
375
|
-
**Request:**
|
|
376
|
-
```json
|
|
377
|
-
{
|
|
378
|
-
"standards_id": "cs_abc123",
|
|
379
|
-
"samples": [
|
|
380
|
-
{ "url": "https://example.com/article1", "expected_result": "allow" },
|
|
381
|
-
{ "url": "https://example.com/article2", "expected_result": "block" },
|
|
382
|
-
{ "text": "Car crash injures three people", "expected_result": "block" }
|
|
383
|
-
]
|
|
384
|
-
}
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
**Key fields:**
|
|
388
|
-
- `standards_id` (string, required): Content standards to calibrate against
|
|
389
|
-
- `samples` (array, required): Content samples with `url` and/or `text`, and optional `expected_result`
|
|
390
|
-
|
|
391
|
-
---
|
|
392
|
-
|
|
393
|
-
### get_media_buy_artifacts
|
|
394
|
-
|
|
395
|
-
Get creative artifacts from a media buy for compliance review.
|
|
396
|
-
|
|
397
|
-
**Request:**
|
|
398
|
-
```json
|
|
399
|
-
{
|
|
400
|
-
"media_buy_id": "mb_abc123",
|
|
401
|
-
"sales_agent_url": "https://sales.publisher.com"
|
|
402
|
-
}
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
**Key fields:**
|
|
406
|
-
- `media_buy_id` (string, required): Media buy identifier
|
|
407
|
-
- `sales_agent_url` (string, required): Sales agent that owns the media buy
|
|
408
|
-
|
|
409
|
-
---
|
|
410
|
-
|
|
411
|
-
### validate_content_delivery
|
|
412
|
-
|
|
413
|
-
Validate delivered content against content standards.
|
|
414
|
-
|
|
415
|
-
**Request:**
|
|
416
|
-
```json
|
|
417
|
-
{
|
|
418
|
-
"standards_id": "cs_abc123",
|
|
419
|
-
"media_buy_id": "mb_abc123",
|
|
420
|
-
"sales_agent_url": "https://sales.publisher.com",
|
|
421
|
-
"date_range": {
|
|
422
|
-
"start": "2025-01-01",
|
|
423
|
-
"end": "2025-01-31"
|
|
424
|
-
}
|
|
425
|
-
}
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
**Key fields:**
|
|
429
|
-
- `standards_id` (string, required): Content standards to validate against
|
|
430
|
-
- `media_buy_id` (string, required): Media buy identifier
|
|
431
|
-
- `sales_agent_url` (string, required): Sales agent URL
|
|
432
|
-
- `date_range` (object, optional): Filter by delivery date range
|
|
433
|
-
|
|
434
|
-
---
|
|
435
|
-
|
|
436
|
-
### sync_plans
|
|
437
|
-
|
|
438
|
-
Register or update a campaign plan that defines authorized parameters (budget, channels, policies) for an orchestrator's autonomous action.
|
|
439
|
-
|
|
440
|
-
**Request:**
|
|
441
|
-
```json
|
|
442
|
-
{
|
|
443
|
-
"plan_id": "plan_q1_2026_launch",
|
|
444
|
-
"plan_version": 1,
|
|
445
|
-
"budget": { "authorized": 500000, "currency": "USD" },
|
|
446
|
-
"channel_allocation": { "olv": 0.55, "display": 0.30, "audio": 0.15 },
|
|
447
|
-
"policies": ["us_coppa", "alcohol_advertising"],
|
|
448
|
-
"human_review_required": false
|
|
449
|
-
}
|
|
450
|
-
```
|
|
451
|
-
|
|
452
|
-
**Key fields:**
|
|
453
|
-
- `plan_id` (string, required): Stable plan identifier
|
|
454
|
-
- `plan_version` (integer, required): Increment on every modification — checks bind to a version
|
|
455
|
-
- `budget.authorized` (number, required): Total spend authority across all governed actions on this plan
|
|
456
|
-
- `policies` (array, optional): Registry policy IDs that govern this plan. Inline `custom_policies` may add restrictions but cannot relax registry policies.
|
|
457
|
-
- `human_review_required` (boolean, optional): Force human review on all actions. Auto-set true when any resolved policy has `requires_human_review: true`.
|
|
458
|
-
|
|
459
|
-
---
|
|
460
|
-
|
|
461
|
-
### check_governance
|
|
462
|
-
|
|
463
|
-
Validate an action against the plan. Called twice in the lifecycle: once on intent (pre-discovery), once on execution (pre-buy). Sellers MUST call execution checks independently using credentials synced via `sync_governance`.
|
|
464
|
-
|
|
465
|
-
**Request (execution check):**
|
|
466
|
-
```json
|
|
467
|
-
{
|
|
468
|
-
"plan_id": "plan_q1_2026_launch",
|
|
469
|
-
"plan_version": 1,
|
|
470
|
-
"purchase_type": "media_buy",
|
|
471
|
-
"tool": "create_media_buy",
|
|
472
|
-
"payload": { "...": "the create_media_buy request body" },
|
|
473
|
-
"governance_context": "gc_mb_seller_456"
|
|
474
|
-
}
|
|
475
|
-
```
|
|
476
|
-
|
|
477
|
-
**Key fields:**
|
|
478
|
-
- `purchase_type` (enum, required): `media_buy`, `rights_license`, `signal_activation`, or `creative_services`
|
|
479
|
-
- `governance_context` (string, optional): Echoed on subsequent checks for the same governed action. The agent issues this on the first check and the buyer attaches it to the action envelope.
|
|
480
|
-
- `tool` (string, required): Which AdCP tool is being authorized
|
|
481
|
-
- `payload` (object, required): The full request body the orchestrator/seller would otherwise send
|
|
482
|
-
|
|
483
|
-
**Response status:** `approved`, `denied`, or `conditions`. On `denied`, read `governance_context.findings[]` to locate the failed rule and correct the payload.
|
|
484
|
-
|
|
485
|
-
---
|
|
486
|
-
|
|
487
|
-
### report_plan_outcome
|
|
488
|
-
|
|
489
|
-
Report the result of a governed action so plan budget and state advance.
|
|
490
|
-
|
|
491
|
-
**Request:**
|
|
492
|
-
```json
|
|
493
|
-
{
|
|
494
|
-
"plan_id": "plan_q1_2026_launch",
|
|
495
|
-
"governance_context": "gc_mb_seller_456",
|
|
496
|
-
"outcome": "completed",
|
|
497
|
-
"committed_budget": 150000
|
|
498
|
-
}
|
|
499
|
-
```
|
|
500
|
-
|
|
501
|
-
**Key fields:**
|
|
502
|
-
- `governance_context` (string, required): The token issued on the original check
|
|
503
|
-
- `outcome` (enum, required): `completed`, `cancelled`, `failed`, or `delivery` (for ongoing pacing reports)
|
|
504
|
-
- `committed_budget` (number, required for `completed`): Net budget committed by this action
|
|
505
|
-
|
|
506
|
-
---
|
|
507
|
-
|
|
508
|
-
### get_plan_audit_logs
|
|
509
|
-
|
|
510
|
-
Retrieve governance state, budget tracking, and audit trail for one or more plans.
|
|
511
|
-
|
|
512
|
-
**Request:**
|
|
513
|
-
```json
|
|
514
|
-
{
|
|
515
|
-
"plan_ids": ["plan_q1_2026_launch"],
|
|
516
|
-
"governance_contexts": ["gc_mb_seller_456"],
|
|
517
|
-
"include_entries": true
|
|
518
|
-
}
|
|
519
|
-
```
|
|
520
|
-
|
|
521
|
-
**Key fields:**
|
|
522
|
-
- `plan_ids` / `portfolio_plan_ids` / `governance_contexts` (at least one required): Scope the query
|
|
523
|
-
- `include_entries` (boolean, optional): Return the full audit trail. Default `false` returns summary only.
|
|
524
|
-
|
|
525
|
-
**Producing a shareable view:** filter `governance_contexts` to the requesting party's actions and strip plan-level aggregates (`budget.*`, `channel_allocation.*`, `summary.drift_metrics`) before forwarding. See [audit trail: internal vs shareable views](/docs/governance/campaign/audit-trail).
|
|
526
|
-
|
|
527
|
-
---
|
|
528
|
-
|
|
529
|
-
## Key Concepts
|
|
530
|
-
|
|
531
|
-
### Property Lists vs Collection Lists
|
|
532
|
-
|
|
533
|
-
- **Property Lists**: Site-level targeting. Operates on publisher domains and properties (websites, apps, CTV apps). Use for "where" the ad appears.
|
|
534
|
-
- **Collection Lists**: Program-level targeting. Operates on shows, series, and content programs using distribution identifiers (IMDb, Gracenote, EIDR). Use for "what content" the ad appears alongside (primarily CTV).
|
|
535
|
-
|
|
536
|
-
### Content Standards vs Property/Collection Lists
|
|
537
|
-
|
|
538
|
-
- **Content Standards**: Rules-based evaluation of content quality, topics, and safety. Evaluates content dynamically.
|
|
539
|
-
- **Property/Collection Lists**: Pre-computed sets of approved or excluded inventory. Static targeting applied at campaign setup.
|
|
540
|
-
|
|
541
|
-
### Filter Resolution
|
|
542
|
-
|
|
543
|
-
Property and collection lists combine static selections with dynamic filters. Use `resolve: true` on get operations to see the final resolved set of properties or collections.
|
|
544
|
-
|
|
545
|
-
### Three invariants for audit and disclosure decisions
|
|
546
|
-
|
|
547
|
-
These three properties of campaign governance shape what an orchestrator can disclose, can rely on a counterparty having, and cannot work around. Surface them when audit-trail design or counterparty disclosure decisions come up.
|
|
548
|
-
|
|
549
|
-
1. **Inline policies are additive-only over registry policies.** A buyer's bespoke `custom_policies` (or inline `policy` entries on a plan) may add restrictions on top of registry-sourced policies. They MUST NOT relax, override, or disable registry policies. Counterparties who see `policies_evaluated: ["us_coppa"]` can trust the registry version of `us_coppa` was applied at its declared `enforcement` level.
|
|
550
|
-
2. **`governance_context` is the seller-visible correlation token; full plan/budget data is buyer-side.** The seller sees the opaque token they were issued and the entries scoped to it. Plan-level totals (`budget.authorized`, `channel_allocation`, `drift_metrics`) belong to the buyer's internal view and are never shared by default.
|
|
551
|
-
3. **`plan_hash` is the cryptographic attestation surface.** `base64url_no_pad(SHA-256(JCS(plan_payload)))` over the plan revision the check evaluated. Any party with the plan revision can recompute and byte-compare. This is what makes a four-field shareable attestation (`governance_context`, `status`, `plan_hash`, `policies_evaluated`) cryptographically meaningful — counterparties don't have to trust the buyer's summary.
|
|
552
|
-
|
|
553
|
-
> A related working-group adoption pattern — `effective_date` enabling informational-before-enforcement of new policies — lives in [Policy Registry](/docs/governance/policy-registry); it shapes registry rollout rather than per-check disclosure decisions.
|
|
554
|
-
|
|
555
|
-
---
|
|
556
|
-
|
|
557
|
-
## Error Handling
|
|
558
|
-
|
|
559
|
-
Common error codes:
|
|
560
|
-
|
|
561
|
-
- `LIST_NOT_FOUND`: Invalid list_id
|
|
562
|
-
- `STANDARDS_NOT_FOUND`: Invalid standards_id
|
|
563
|
-
- `UNAUTHORIZED`: Not authorized to access this resource
|
|
564
|
-
- `VALIDATION_ERROR`: Invalid filter or rule configuration
|
|
565
|
-
- `PLAN_NOT_FOUND`: No plan with this ID, or the principal is not authorized for it. Returned indistinguishably from the unauthorized case to prevent plan-ID enumeration.
|
|
566
|
-
- `GOVERNANCE_DENIED`: `check_governance` rejected the action. Read `governance_context.findings[]` to identify the failed rule, correct the payload, and retry.
|
|
@@ -1,136 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: adcp-measurement
|
|
3
|
-
description: Operate as or integrate with an AdCP measurement agent through a buyer-controlled orchestrator gateway - publish a metric catalog, receive authorized cross-seller delivery, and return compact feedback for orchestrator-controlled seller fan-out. Use when connecting measurement providers or routing provider results into seller optimization.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# AdCP Measurement Agents
|
|
7
|
-
|
|
8
|
-
Measurement agents are first-class provider identities without requiring AdCP to become a universal measurement-data transport.
|
|
9
|
-
|
|
10
|
-
> **Calling basics** — authentication, idempotency, error recovery, and account resolution live in `skills/call-adcp-agent/SKILL.md`. This skill covers measurement-specific semantics.
|
|
11
|
-
|
|
12
|
-
## Role
|
|
13
|
-
|
|
14
|
-
A measurement agent can:
|
|
15
|
-
|
|
16
|
-
1. publish the metrics it computes through `get_adcp_capabilities.measurement.metrics[]`;
|
|
17
|
-
2. declare `measurement.produces_performance_feedback: true` when it produces optimizer-ready assertions;
|
|
18
|
-
3. obtain buyer-approved data from an orchestrator through its `get_media_buy_delivery` task; and
|
|
19
|
-
4. return compact assertions through its `provide_performance_feedback` task, after which the orchestrator decides what to send to each seller.
|
|
20
|
-
|
|
21
|
-
The measurement agent never needs seller credentials. The orchestrator controls cohort consistency, seller-ID mapping, normalization, and disclosure. `report_usage` is a vendor-service consumption and billing task, not general measurement interchange.
|
|
22
|
-
|
|
23
|
-
## Discovery
|
|
24
|
-
|
|
25
|
-
Publish an agent entry with `type: "measurement"` in the provider's `brand.json`. The agent's `get_adcp_capabilities` response includes:
|
|
26
|
-
|
|
27
|
-
```json
|
|
28
|
-
{
|
|
29
|
-
"supported_protocols": ["measurement"],
|
|
30
|
-
"experimental_features": ["measurement.core"],
|
|
31
|
-
"measurement": {
|
|
32
|
-
"produces_performance_feedback": true,
|
|
33
|
-
"metrics": [
|
|
34
|
-
{
|
|
35
|
-
"metric_id": "incremental_revenue_index",
|
|
36
|
-
"unit": "index",
|
|
37
|
-
"description": "Incremental revenue relative to a buyer-defined control.",
|
|
38
|
-
"methodology_url": "https://measurement.example/methodology",
|
|
39
|
-
"methodology_version": "2026-08"
|
|
40
|
-
}
|
|
41
|
-
]
|
|
42
|
-
}
|
|
43
|
-
}
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
Metric identity is `(provider BrandRef, metric_id)`. Do not assume vendor metric IDs are globally unique.
|
|
47
|
-
|
|
48
|
-
The first experimental gateway tier fixes the interchange tasks rather than negotiating method arrays.
|
|
49
|
-
|
|
50
|
-
## Orchestrator gateway and authorization
|
|
51
|
-
|
|
52
|
-
The buyer orchestrator's experimental `measurement_gateway` capability means it exposes the task boundary; it does not grant access by itself. The orchestrator provisions the provider on an orchestrator account. Sellers are not part of this provider authorization.
|
|
53
|
-
|
|
54
|
-
The provider's authenticated principal receives the two first-tier gateway tasks on its orchestrator account:
|
|
55
|
-
|
|
56
|
-
```json
|
|
57
|
-
{
|
|
58
|
-
"allowed_tasks": ["get_media_buy_delivery", "provide_performance_feedback"],
|
|
59
|
-
"read_only": false
|
|
60
|
-
}
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
Use an orchestrator-defined `custom:` scope name if desired. The task list is normative; the custom name is not.
|
|
64
|
-
|
|
65
|
-
Webhook and offline interchange are not part of this tier; they require explicit registration, credentials, payload, and receipt contracts before they can be advertised as interoperable AdCP paths.
|
|
66
|
-
|
|
67
|
-
The orchestrator exposes measurement-facing media-buy, package, and creative IDs to the provider and retains their mapping to every seller-local ID.
|
|
68
|
-
|
|
69
|
-
## Producing feedback
|
|
70
|
-
|
|
71
|
-
Submit one assertion per task call:
|
|
72
|
-
|
|
73
|
-
```json
|
|
74
|
-
{
|
|
75
|
-
"idempotency_key": "f7a3e291-4c58-4d6b-9012-a3e9b27c5f08",
|
|
76
|
-
"media_buy_id": "mb_123",
|
|
77
|
-
"package_id": "pkg_video",
|
|
78
|
-
"measurement_period": {
|
|
79
|
-
"start": "2026-07-01T00:00:00Z",
|
|
80
|
-
"end": "2026-07-31T23:59:59Z"
|
|
81
|
-
},
|
|
82
|
-
"metric": {
|
|
83
|
-
"scope": "vendor",
|
|
84
|
-
"vendor": { "domain": "measurement.example" },
|
|
85
|
-
"metric_id": "incremental_revenue_index"
|
|
86
|
-
},
|
|
87
|
-
"performance_index": 1.35,
|
|
88
|
-
"baseline": "control_group",
|
|
89
|
-
"producer": { "domain": "measurement.example" },
|
|
90
|
-
"methodology": "geo_incrementality",
|
|
91
|
-
"methodology_version": "2026-08",
|
|
92
|
-
"study_ref": "study_42",
|
|
93
|
-
"evidence_ref": "https://measurement.example/results/study_42",
|
|
94
|
-
"final": true
|
|
95
|
-
}
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
Rules:
|
|
99
|
-
|
|
100
|
-
- `1.0` equals the named baseline. Compact-contract producers (baseline present) MUST use observed/baseline for higher-is-better ratios and baseline/observed for lower-is-better ratios such as CPA.
|
|
101
|
-
- `producer` must match authenticated provider identity at the orchestrator gateway.
|
|
102
|
-
- `study_ref` is correlation only; it never asks a seller to construct experiment arms.
|
|
103
|
-
- Keep raw logs, model coefficients, identity paths, and full study datasets outside the feedback payload.
|
|
104
|
-
- A revision is a new assertion with a fresh idempotency key and `supersedes_feedback_id` from the earlier receipt.
|
|
105
|
-
|
|
106
|
-
## Reading receipts
|
|
107
|
-
|
|
108
|
-
```json
|
|
109
|
-
{
|
|
110
|
-
"status": "completed",
|
|
111
|
-
"success": true,
|
|
112
|
-
"feedback_id": "fb_01J5Y5KQ2T8B2M8P0A4E6R3C9D",
|
|
113
|
-
"application_status": "accepted",
|
|
114
|
-
"received_at": "2026-08-04T12:00:02Z"
|
|
115
|
-
}
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
- A gateway receipt identifies the assertion stored by the orchestrator. It should normally report `accepted`; it is not proof that any seller used the signal.
|
|
119
|
-
- Each seller returns a separate receipt to the orchestrator. A seller's `applied` means the signal entered that seller's optimizer inputs.
|
|
120
|
-
- `not_applied` means the receiving endpoint evaluated but did not incorporate the assertion; inspect `status_reason`.
|
|
121
|
-
|
|
122
|
-
Do not claim causal delivery impact from `applied`. It means the seller consumed the signal, not that the signal caused a specific bid or allocation change.
|
|
123
|
-
|
|
124
|
-
## End-to-end flow
|
|
125
|
-
|
|
126
|
-
### 1. Orchestrator supplies data
|
|
127
|
-
|
|
128
|
-
The provider calls the orchestrator's `get_media_buy_delivery` task for buyer-approved data. The orchestrator applies the same user or geographic cohort definition across sellers before measurement.
|
|
129
|
-
|
|
130
|
-
### 2. Provider returns feedback
|
|
131
|
-
|
|
132
|
-
The provider calls the orchestrator gateway's `provide_performance_feedback` task. Authenticated provider identity binds `producer`; raw logs, model coefficients, and identity paths remain outside the payload.
|
|
133
|
-
|
|
134
|
-
### 3. Orchestrator fans out
|
|
135
|
-
|
|
136
|
-
The orchestrator validates and normalizes the result, chooses what each seller should receive, maps to seller-local IDs, and calls each seller's `provide_performance_feedback` under the buyer's identity. It retains the mapping between provider and seller receipts for audit.
|