feat(schema): audience activation method declarations (#4324)

.changeset/audience-activation-methods.md

@@ -0,0 +1,5 @@
+---
+"adcontextprotocol": minor
+---
+
+Add audience activation method declarations (#4324). Products declare how buyer audience data can reach them via `audience_activation.methods` — `sync_audiences`, `tmp_identity_match`, `file_transfer`, `dataset_query`, `clean_room`, or `platform_distribution` — with vendor identity as a BrandRef domain. The seller-level union surfaces as `media_buy.audience_targeting.supported_activation_methods` in `get_adcp_capabilities` for fast-fail discovery, and buyers filter products with `filters.audience_activation_methods` (OR across entries, AND within an entry, omitted fields as wildcards). Dataset entries may publish `consumer_identities[]` with an opaque principal and optional paired cloud/region deployment metadata. Platform destinations are optional account-scoped coordinates. Clean-room declarations cover only collaborations that produce targetable audiences and compose with the declared dataset or distribution rail; analytics-only rooms do not imply audience activation. Grant-based paths are in-protocol only when the vendor flow is grantee-identified.

docs/media-buy/product-discovery/media-products.mdx

@@ -150,6 +150,56 @@ At buy time, a package can repeat `audience_evidence_requirements` and can carry
 
 When an attestation affected either decision, readback preserves the exact reference and its `AttestationEvaluation` as one pair. That pair is valid only when the reference is published on the selected snapshot, its claim and issuer satisfy both buyer and seller policy, `reference_digest` covers that same reference, the outcome is `verified`, and both the subject digest and action-binding digest equal the evidence `content_digest`. An evaluation for one reference cannot verify a different reference. Sellers retain the full immutable snapshot and evaluations for at least as long as the package remains readable. Buyers should cache the evidence returned during discovery; AdCP 3.2 does not introduce a buyer-controlled snapshot fetch URL. Sellers may embed the full snapshot in readback, but need not duplicate it on every product or package.
 
+### Audience activation
+
+The [`audience_targeting`](/docs/protocol/get_adcp_capabilities#audience_targeting) capability describes *what identifiers* a seller matches on; `audience_activation` describes *how the data moves*. Two parties can both support audiences and remain practically incompatible — a buyer built around Snowflake sharing and a seller that only accepts API pushes discover that today at integration time, or worse, at activation time. Products that accept buyer audiences declare their activation paths so that mismatch surfaces during discovery.
+
+```json
+"audience_activation": {
+  "methods": [
+    { "pattern": "sync_audiences" },
+    {
+      "pattern": "dataset_query",
+      "vendor": { "domain": "data-cloud.example" },
+      "consumer_identities": [
+        { "cloud": "aws", "region": "us-east-1", "identity": "SELLERORG.ADCP_INGEST" }
+      ]
+    },
+    {
+      "pattern": "platform_distribution",
+      "vendor": { "domain": "activation-hub.example" },
+      "destination_ref": "dest_12345",
+      "bind_expiry_days": 14
+    }
+  ],
+  "preferred_method": { "pattern": "sync_audiences" },
+  "notes": "Dataset ingestion runs daily at 06:00 UTC."
+}
+```
+
+`methods` is an unordered set of activation capabilities. Entries are usually independent options; `clean_room` may compose with `dataset_query` or `platform_distribution` to declare the output rail. `preferred_method` (optional) names the seller's preference and MUST also appear in `methods`. Absence of `audience_activation` means undeclared — treat it as needs-clarification rather than non-support, except under an `audience_activation_methods` filter, where sellers MUST exclude undeclared products.
+
+Schema: [`core/audience-activation-method.json`](https://adcontextprotocol.org/schemas/v3/core/audience-activation-method.json)
+
+#### Activation method patterns
+
+Each entry declares a `pattern` plus pattern-specific fields. Vendor identity is a [BrandRef](/docs/media-buy/product-discovery/media-products) domain — new platforms declare a domain, no enum change required.
+
+| Pattern | Required fields | Meaning |
+|---------|----------------|---------|
+| `sync_audiences` | — | Audience pushes and external source references via the AdCP [`sync_audiences`](/docs/media-buy/task-reference/sync_audiences) task. Any AdCP-speaking buyer can use it. |
+| `tmp_identity_match` | `buyer_agent.agent_url` | The seller has wired TMP identity-match calls to this specific buyer agent. Entries MUST be consistent with `trusted_match.providers[]` where both are present. |
+| `file_transfer` | `transport`, `vendor` | Bucket-addressed file exchange (`s3`, `gcs`, `azure_blob`). Optional `directions` (`buyer_to_seller`, `seller_to_buyer`); absent means unspecified, not neither. |
+| `dataset_query` | `vendor` | The seller reads a dataset the buyer shares through the vendor's grantee-identified sharing mechanism (Snowflake Secure Data Sharing, Databricks Delta Sharing, BigQuery authorized views). Optional `consumer_identities[]` lists the principals to grant. `identity` is required; paired `cloud` and `region` metadata is optional for deployment-scoped identities and omitted for global principals. Location semantics are vendor-specific: they can constrain direct-share reachability, select fulfillment, or provide routing/cost hints, but are not compliance boundaries. |
+| `clean_room` | `vendor` | Privacy-preserving match in the named vendor's room. Declare this under audience activation only when the collaboration can produce an audience targetable on this product; analytics-only or measurement-only room access does not qualify. The declaration does not promise portable output. Room setup remains bilateral. |
+| `platform_distribution` | `vendor` | The vendor's rails deliver segments to the seller's destination. The buyer initiates distribution in the vendor's system, then binds the arriving segment via `sync_audiences`. Optional `destination_ref` is an opaque account-scoped destination or seat reference; omit it until bilateral setup establishes the destination. Optional `bind_expiry_days` declares when an unfulfilled bind may expire. |
+
+Clean-room activation composes with the output rail rather than assuming every room behaves alike. Platform-native and partner-distributed audiences pair `clean_room` with `platform_distribution`; queryable outputs pair it with `dataset_query`. Cryptographic hashing protocols (such as PAIR) coordinate hashing with no centralized query environment and activate through a DSP: declare them as `clean_room` (pairing provider as vendor) + `platform_distribution` (DSP vendor) — not as `tmp_identity_match`, which covers request-time TMP matching, not batch cryptographic reconciliation. A room that only returns aggregate insights belongs in measurement or reporting capabilities, not `audience_activation`. This covers walled-garden rooms, independent collaboration providers, warehouse-native rooms, and cryptographic-hashing protocols.
+
+A grant-based path is in-protocol only when the vendor flow is **grantee-identified** — the grant names a principal and no secret is conveyed. Token-bearer flows (presigned URLs, bearer-token activation links) remain out-of-band integrations.
+
+Buyers filter discovery with [`filters.audience_activation_methods`](/docs/media-buy/task-reference/get_products): OR across requested entries, AND within an entry, omitted optional fields are wildcards, `directions` matches on non-empty intersection.
+
 ### Pricing Models
 
 Publishers declare which pricing models they support for each product. Buyers select from the available options when creating a media buy. This approach supports:

docs/media-buy/task-reference/get_products.mdx

@@ -360,6 +360,7 @@ targeting filter and the legacy top-level `property_list`.
 | `required_metrics` | string[] ([metric vocabulary](/docs/media-buy/media-buys/optimization-reporting)) | Filter to products whose `reporting_capabilities.available_metrics` is a superset of these metrics — i.e., products that commit to reporting all listed metrics in delivery. Use for capability discovery (e.g., `["completed_views"]` for a CTV CPCV buy). Sellers MUST silently exclude products that cannot meet the list — filter-not-fail; do not return an error. The product's declared `available_metrics` becomes the binding reporting contract carried into the resulting media buy. |
 | `required_vendor_metrics` | object[] | Filter to products whose `reporting_capabilities.vendor_metrics` covers vendor-defined metrics (proprietary attention, emissions, panel demographics, brand-lift surveys, etc.). Each entry pins `vendor` (BrandRef) and/or `metric_id` — at least one. Cross-vendor discovery (e.g., "any attention measurement") is the buyer agent's responsibility: resolve which vendors offer a category via the vendors' `brand.json` records, then enumerate them as filter entries. Same filter-not-fail semantics as `required_metrics`. |
 | `audience_evidence_requirements` | AudienceEvidenceRequirements | Apply buyer-authored admissibility or ranking policy to `Product.audience_evidence`. `requirement_mode` distinguishes hard filtering from preference; `evidence_presence` distinguishes evidence-must-exist from apply-when-published. |
+| `audience_activation_methods` | object[] | Filter to products whose [`audience_activation.methods`](/docs/media-buy/product-discovery/media-products#audience-activation) matches at least one requested entry (OR across entries). Within an entry every specified field must match (AND); omitted optional fields are wildcards; `directions` matches on non-empty intersection. Each entry requires `pattern` ([`sync_audiences`](/docs/media-buy/task-reference/sync_audiences), `tmp_identity_match`, `file_transfer`, `dataset_query`, `clean_room`, `platform_distribution`) plus optional `vendor`, `transport`, `directions`, `buyer_agent`. Sellers MUST exclude products with no `audience_activation` declaration when this filter is present, reported via `filter_diagnostics.excluded_by`. |
 
 ### Audience evidence requirements
 

docs/media-buy/task-reference/sync_audiences.mdx

@@ -146,6 +146,8 @@ Providing multiple identifiers for the same person improves match rates. Composi
 
 **Identifier support varies by seller**: Check [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) → `media_buy.audience_targeting.supported_identifier_types` and `media_buy.audience_targeting.supported_uid_types` before sending. MAID support is not universal (LinkedIn does not accept MAIDs; iOS IDFA requires App Tracking Transparency consent). The `media_buy.audience_targeting.matching_latency_hours` range and `media_buy.audience_targeting.minimum_audience_size` in capabilities are also seller-specific.
 
+**Activation paths beyond inline push**: Inline members are one activation method. Sellers declare which paths they support — AdCP push, dataset sharing, clean rooms, platform distribution — via [`audience_activation`](/docs/media-buy/product-discovery/media-products#audience-activation) on products and `media_buy.audience_targeting.supported_activation_methods` in [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities). Filter discovery with `filters.audience_activation_methods` on [`get_products`](/docs/media-buy/task-reference/get_products) to find inventory compatible with your data pipeline.
+
 **Size limit**: Payloads are limited to 100,000 members per call across all audiences. For larger lists, chunk into sequential calls using `add` deltas.
 
 **Concurrency**: Ensure that calls made to `sync_audience` are independent of eachother. They may be processed out-of-order. If you need sequential execution, wait for the callback to your configured webhook before making another call. 

docs/protocol/get_adcp_capabilities.mdx

@@ -857,6 +857,7 @@ Audience targeting capabilities. Presence of this object indicates the seller su
 | `supports_platform_customer_id` | boolean  |              | When `true`, the seller accepts the buyer's CRM/loyalty ID as a matchable identifier. Only applicable when the seller operates a closed ecosystem with a shared ID namespace (e.g., a retailer matching against their loyalty program). Buyers can include `platform_customer_id` values in `AudienceMember.identifiers`. Reporting on matched IDs typically requires a clean room or the seller's own reporting surface. |
 | `supported_uid_types`           | string[] |              | Universal ID types accepted for audience matching (MAIDs, RampID, UID2, etc.). MAID support varies significantly by platform — check this field before sending `uids` with `type: maid`.                                                                                                                                                                                                                                  |
 | `matching_latency_hours`        | object   |              | Expected matching latency range in hours after upload. Use to calibrate polling cadence and set appropriate expectations before configuring `push_notification_config`. Shape: `{ min: integer, max: integer }`.                                                                                                                                                                                                          |
+| `supported_activation_methods`  | object[] |              | Union of per-product [`audience_activation.methods`](/docs/media-buy/product-discovery/media-products#audience-activation) across the seller's catalog. Fast-fail discovery: read this once and skip the catalog walk when nothing overlaps your pipeline. Per-product declarations are the source of truth; sellers MUST keep this consistent with the catalog. Operational coordinates are account-scoped: this union may omit `consumer_identities` and `destination_ref` until bilateral setup establishes them, and must never expose another account's coordinates. Each entry is an [activation method](/docs/media-buy/product-discovery/media-products#activation-method-patterns). |
 
 #### conversion_tracking
 
@@ -1672,7 +1673,23 @@ const buy = await client.createMediaBuy({
       "supports_platform_customer_id": false,
       "supported_uid_types": ["uid2", "rampid"],
       "minimum_audience_size": 500,
-      "matching_latency_hours": { "min": 1, "max": 24 }
+      "matching_latency_hours": { "min": 1, "max": 24 },
+      "supported_activation_methods": [
+        { "pattern": "sync_audiences" },
+        {
+          "pattern": "dataset_query",
+          "vendor": { "domain": "data-cloud.example" },
+          "consumer_identities": [
+            { "cloud": "aws", "region": "us-east-1", "identity": "SELLERORG.ADCP_INGEST" }
+          ]
+        },
+        {
+          "pattern": "platform_distribution",
+          "vendor": { "domain": "activation-hub.example" },
+          "destination_ref": "dest_12345",
+          "bind_expiry_days": 14
+        }
+      ]
     },
     "conversion_tracking": {
       "multi_source_event_dedup": false,