From 69efacd6174b9b968f40e695483c5882a117e88f Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Fri, 13 Nov 2026 16:44:29 -0500 Subject: [PATCH] feat(schema): audience targeting without inline member push media_buy.audience_targeting now promises audience_include and audience_exclude plus discovery-only sync_audiences, which a declaring seller MUST answer, but no longer promises inline member push. The sync_audiences pattern in the experimental supported_activation_methods declares push; when the field is absent, push is supported as in 3.2. supported_identifier_types and minimum_audience_size move from required to an if/then that requires them only when the seller accepts inline push, so every 3.2-valid capabilities document stays valid. A seller without push rejects add/remove member deltas, and new audiences without a source reference, with UNSUPPORTED_FEATURE. Closes #8936 Co-Authored-By: Claude Opus 5.5 --- .../audience-targeting-without-member-push.md | 5 + docs/media-buy/advanced-topics/targeting.mdx | 8 +- docs/media-buy/specification.mdx | 4 +- .../task-reference/sync_audiences.mdx | 17 +- docs/protocol/get_adcp_capabilities.mdx | 37 ++++- docs/reference/experimental-status.mdx | 2 +- docs/reference/migration/3-2-to-3-3.mdx | 13 +- docs/reference/release-notes.mdx | 2 + docs/reference/versioning.mdx | 2 +- docs/reference/whats-new-in-3-3.mdx | 2 + package.json | 2 +- .../media-buy/sync-audiences-request.json | 4 +- .../get-adcp-capabilities-response.json | 30 +++- tests/audience-targeting-member-push.test.cjs | 151 ++++++++++++++++++ 14 files changed, 255 insertions(+), 24 deletions(-) create mode 100644 .changeset/audience-targeting-without-member-push.md create mode 100644 tests/audience-targeting-member-push.test.cjs diff --git a/.changeset/audience-targeting-without-member-push.md b/.changeset/audience-targeting-without-member-push.md new file mode 100644 index 00000000000..24772089faa --- /dev/null +++ b/.changeset/audience-targeting-without-member-push.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": minor +--- + +`media_buy.audience_targeting` no longer promises inline member push (#8936). Its presence now means the seller supports `audience_include` and `audience_exclude` in targeting overlays and answers discovery-only `sync_audiences` (called without `audiences`), which a declaring seller MUST do, so a buyer can always read the `audience_id` values it can target. Inline member push is declared by the `sync_audiences` pattern in the experimental `audience_targeting.supported_activation_methods`; when that field is absent, push is supported, as in 3.2. `supported_identifier_types` and `minimum_audience_size` move from `required` to an `if`/`then` that requires them only when the seller accepts inline push, so every capabilities document valid under 3.2 stays valid. A seller whose `supported_activation_methods` omits the `sync_audiences` pattern rejects, with `UNSUPPORTED_FEATURE`, a `sync_audiences` entry that carries `add` or `remove` or that would create a new audience without a `source` reference; `source` references for its declared rails still work. This lets an ad platform that can target the audiences already on an account, but cannot take a customer list, declare audience targeting without claiming member push. Generated types make both fields optional, and a strict 3.2 validator still requires them. Updated: `get_adcp_capabilities`, `sync_audiences`, the targeting guide, the 3.3 release notes and migration guide. diff --git a/docs/media-buy/advanced-topics/targeting.mdx b/docs/media-buy/advanced-topics/targeting.mdx index 06aa5654fc4..264c1767a9e 100644 --- a/docs/media-buy/advanced-topics/targeting.mdx +++ b/docs/media-buy/advanced-topics/targeting.mdx @@ -1264,16 +1264,16 @@ create-time substitute for any result above. - **Example**: `["lapsed_subscribers", "high_value_prospects"]` - **Use cases**: Retargeting known users, loyalty campaigns targeting existing members, CRM-based inclusion on closed platforms (LinkedIn, Meta, TikTok, Google Ads) - **Not for lookalike/expansion**: To find new users *similar to* an audience, describe the intent in your campaign brief ("reach people like our existing customers") — the seller handles expansion strategy -- **Prerequisite**: Audiences must be registered and `ready` via `sync_audiences` before use -- **Note**: Seller must declare support in `get_adcp_capabilities` +- **Prerequisite**: Audiences must be on the account and `ready` before use: pushed through `sync_audiences`, or, on a [seller without inline member push](/docs/media-buy/task-reference/sync_audiences#sellers-without-inline-member-push), listed by a discovery-only `sync_audiences` call +- **Note**: Seller declares support with `media_buy.audience_targeting` in `get_adcp_capabilities`. That declaration does not by itself mean the seller accepts pushed members; `audience_targeting.supported_activation_methods` says whether it does ### audience_exclude - **Description**: Suppress delivery to users who are members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. - **Format**: Array of `audience_id` strings from [`sync_audiences`](/docs/media-buy/task-reference/sync_audiences) - **Example**: `["existing_customers", "recent_purchasers"]` - **Use cases**: Customer suppression in acquisition campaigns, excluding recent converters, suppressing opted-out users -- **Prerequisite**: Audiences must be registered and `ready` via `sync_audiences` before use -- **Note**: Seller must declare support in `get_adcp_capabilities` +- **Prerequisite**: Audiences must be on the account and `ready` before use: pushed through `sync_audiences`, or, on a [seller without inline member push](/docs/media-buy/task-reference/sync_audiences#sellers-without-inline-member-push), listed by a discovery-only `sync_audiences` call +- **Note**: Seller declares support with `media_buy.audience_targeting` in `get_adcp_capabilities`, as for `audience_include` ### signal_targeting_groups - **Description**: Basic Boolean grouping for seller-offered data signals. Use this for both simple include-only signal targeting and grouped include/exclude expressions such as `(A OR B) AND NOT (C OR D)`. diff --git a/docs/media-buy/specification.mdx b/docs/media-buy/specification.mdx index 97e78358703..2873e9224cf 100644 --- a/docs/media-buy/specification.mdx +++ b/docs/media-buy/specification.mdx @@ -1287,7 +1287,9 @@ Manage first-party CRM audiences on a seller account. Upload hashed customer lis **Requirements:** - Orchestrators MUST include `account_id` -- Orchestrators MUST include at least one audience with hashed member data +- Orchestrators MUST include at least one audience with hashed member data when pushing members; a discovery-only call omits `audiences` +- Sales agents that declare `media_buy.audience_targeting` MUST answer discovery-only calls +- Sales agents whose `media_buy.audience_targeting.supported_activation_methods` omits the `sync_audiences` pattern MUST reject, with `UNSUPPORTED_FEATURE`, an audience entry that carries `add` or `remove` or that would create a new audience without a `source` reference ([Sellers without inline member push](/docs/media-buy/task-reference/sync_audiences#sellers-without-inline-member-push)) - Sales agents MUST return per-audience outcomes with matching status - Sales agents SHOULD support `push_notification_config` for async matching completion - Sales agents MUST accept SHA-256 hashed identifiers and MUST reject cleartext email/phone in `hashed_email`/`hashed_phone` fields (PII minimization at the transport boundary; see [Privacy Considerations](/docs/reference/privacy-considerations#unsalted-hashed-identifiers-are-pseudonymous-not-anonymous) for the retention/consent obligations that hashing does not satisfy) diff --git a/docs/media-buy/task-reference/sync_audiences.mdx b/docs/media-buy/task-reference/sync_audiences.mdx index ac429ad7dae..a4506e9b676 100644 --- a/docs/media-buy/task-reference/sync_audiences.mdx +++ b/docs/media-buy/task-reference/sync_audiences.mdx @@ -117,7 +117,7 @@ asyncio.run(main()) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `account` | [account-ref](/docs/building/by-layer/L2/accounts-and-agents#account-references) | Yes | Account reference. Pass `{ "account_id": "..." }` or `{ "brand": {...}, "operator": "..." }` if the seller supports implicit resolution. | -| `audiences` | [Audience](#audience-object)[] | No | Audiences to sync. When omitted, the call is discovery-only and returns all existing audiences without modification. | +| `audiences` | [Audience](#audience-object)[] | No | Audiences to sync. When omitted, the call is discovery-only and returns all existing audiences without modification. Every seller that declares `media_buy.audience_targeting` answers discovery-only calls; member deltas need [inline member push](#sellers-without-inline-member-push). | | `delete_missing` | boolean | No | When true, buyer-managed audiences on the account not in this request are removed (default: false). Does not affect seller-managed audiences. Do not combine with an omitted `audiences` array or all buyer-managed audiences will be deleted. | ### Audience Object @@ -145,7 +145,7 @@ Every member requires an `external_id` (buyer-assigned stable identifier) plus a Providing multiple identifiers for the same person improves match rates. Composite identifiers (e.g. hashed first name + last name + zip) are not yet standardized — use `ext` for platform-specific extensions. -**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. +**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. A seller without inline member push may omit `supported_identifier_types` and `minimum_audience_size`. **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. [External source references](#external-audience-sources-experimental) — pointing this task at a shared dataset or vendor-distributed segment instead of pushing members — are available experimentally on sellers that declare the corresponding activation patterns. @@ -153,6 +153,16 @@ Providing multiple identifiers for the same person improves match rates. Composi **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. +### Sellers without inline member push + +A seller that declares `media_buy.audience_targeting` supports `audience_include` and `audience_exclude` and MUST answer discovery-only calls to this task. Whether it also accepts pushed members is a separate declaration, read from `media_buy.audience_targeting.supported_activation_methods` in [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities#audience_targeting): + +- **Absent:** inline member push is supported, as in 3.2. +- **Includes `{ "pattern": "sync_audiences" }`:** inline member push is supported. +- **Present without the `sync_audiences` pattern:** no inline member push. The seller MUST reject, with [`UNSUPPORTED_FEATURE`](/docs/building/verification/compliance-catalog#error-code-unsupported-feature), an `audiences` entry that carries `add` or `remove`, or that would create a new audience without a [`source`](#external-audience-sources-experimental) reference. Discovery-only calls still work, and so do `source` references for the rails the seller declares. + +The typical case is an ad platform account that already holds the buyer's audiences, built in the platform's own tools, where the platform cannot take a customer list through its API. The seller lists those audiences with a [discovery-only call](#discovery-only), and the buyer targets the returned `audience_id` values with `audience_include` and `audience_exclude`. + ## Response shapes Responses use discriminated unions — a response has exactly one of three shapes, never mixed: @@ -279,7 +289,7 @@ Sellers that only support aggregate match counts omit `match_breakdown` entirely ### Discovery Only -Check status of all existing audiences without making changes. The response includes all audiences on the account — filter by `audience_id` to find the one you care about: +Check status of all existing audiences without making changes. The response includes all audiences on the account — filter by `audience_id` to find the one you care about. Every seller that declares `media_buy.audience_targeting` answers this call, including a [seller without inline member push](#sellers-without-inline-member-push), so it is how a buyer learns which `audience_id` values it can target: @@ -706,6 +716,7 @@ The schema never carries cleartext email or phone — buyers MUST hash before tr | [`SOURCE_ACCESS_FAILED`](/docs/building/verification/compliance-catalog#error-code-source-access-failed) | Seller could not read an external audience source (per-audience, experimental) | `error.field` `source.locator`/`source.segment_ref`: fix the reference; `source`: grant the seller's declared consumer identity and retry; no `error.field`: vendor outage — retry with backoff | | [`CONFLICT`](/docs/building/verification/compliance-catalog#error-code-conflict) | Cross-transport upsert: member deltas against a sourced audience or `source` against a pushed one (`error.field` = `audience_id`) | Transport is fixed at creation — delete and recreate to convert | | [`UNSUPPORTED_FEATURE`](/docs/building/verification/compliance-catalog#error-code-unsupported-feature) | `source` kind whose activation pattern the seller has not declared | Check the seller's `audience_activation` declarations before sending source references | +| [`UNSUPPORTED_FEATURE`](/docs/building/verification/compliance-catalog#error-code-unsupported-feature) | `add` or `remove` member deltas, or a new audience without `source`, sent to a seller whose `supported_activation_methods` omits the `sync_audiences` pattern | Check `media_buy.audience_targeting.supported_activation_methods` before pushing members; use discovery-only calls and target existing audiences instead | ## Next Steps diff --git a/docs/protocol/get_adcp_capabilities.mdx b/docs/protocol/get_adcp_capabilities.mdx index acea09edb42..da8efc9d3e2 100644 --- a/docs/protocol/get_adcp_capabilities.mdx +++ b/docs/protocol/get_adcp_capabilities.mdx @@ -1459,16 +1459,43 @@ See [Audience evidence](/docs/media-buy/product-discovery/media-products#audienc #### audience_targeting -Audience targeting capabilities. Presence of this object indicates the seller supports audience targeting, including [`sync_audiences`](/docs/media-buy/task-reference/sync_audiences) and `audience_include`/`audience_exclude` in targeting overlays. Describes what identifier types the seller accepts for audience matching, size constraints, and expected matching latency. +Audience targeting capabilities. Presence of this object indicates the seller supports `audience_include`/`audience_exclude` in targeting overlays and discovery-only [`sync_audiences`](/docs/media-buy/task-reference/sync_audiences#discovery-only), the call without `audiences` that lists the audiences on the account and the `audience_id` values those overlays reference. A seller that declares `audience_targeting` MUST answer discovery-only `sync_audiences`. Describes what identifier types the seller accepts for audience matching, size constraints, and expected matching latency. + +**Inline member push is declared separately.** Presence of `audience_targeting` alone does not promise that the seller accepts pushed members (`add` and `remove` on `sync_audiences`): + +| `supported_activation_methods` | Inline member push | `supported_identifier_types` and `minimum_audience_size` | +|---|---|---| +| Absent | Supported, as in 3.2 | Required | +| Includes `{ "pattern": "sync_audiences" }` | Supported | Required | +| Present without the `sync_audiences` pattern | Not supported | Optional | + +A seller without inline member push MUST reject, with [`UNSUPPORTED_FEATURE`](/docs/building/verification/compliance-catalog#error-code-unsupported-feature), a `sync_audiences` entry that carries `add` or `remove`, or that would create a new audience without a [`source`](/docs/media-buy/task-reference/sync_audiences#external-audience-sources-experimental) reference. It still answers discovery-only calls, so a buyer can read the `audience_id` values of audiences already on the account, such as ones built in the platform's own tools, and target them. `supported_activation_methods` is experimental, so a seller that declares no inline push lists `media_buy.audience_activation` in `experimental_features`. + +```json +{ + "$schema": "/schemas/protocol/get-adcp-capabilities-response.json", + "status": "completed", + "adcp": { "major_versions": [3], "idempotency": { "supported": false } }, + "supported_protocols": ["media_buy"], + "experimental_features": ["media_buy.audience_activation"], + "media_buy": { + "audience_targeting": { + "supported_activation_methods": [ + { "pattern": "platform_distribution", "vendor": { "domain": "activation-hub.example" } } + ] + } + } +} +``` | Field | Type | Required | Description | | ------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `supported_identifier_types` | string[] | **Required** | PII-derived identifier types accepted for audience matching. Buyers should only send identifiers the seller supports. Values: `hashed_email`, `hashed_phone`. | -| `minimum_audience_size` | integer | **Required** | Minimum matched audience size required for targeting. Audiences below this threshold will have `status: too_small`. Varies by platform (100–1000 is typical). | +| `supported_identifier_types` | string[] | **Required with inline push** | PII-derived identifier types accepted for audience matching. Buyers should only send identifiers the seller supports. Values: `hashed_email`, `hashed_phone`. Required unless `supported_activation_methods` is present without the `sync_audiences` pattern. | +| `minimum_audience_size` | integer | **Required with inline push** | Minimum matched audience size required for targeting. Audiences below this threshold will have `status: too_small`. Varies by platform (100–1000 is typical). Required unless `supported_activation_methods` is present without the `sync_audiences` pattern; a seller without inline push MAY still declare it. | | `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[] | | **Experimental** (`media_buy.audience_activation` — MUST be listed in `experimental_features` when present; see [Experimental status](/docs/reference/experimental-status)). 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. Absence of this field with `media_buy.audience_activation` listed in `experimental_features` means walk the catalog — only a present, non-overlapping union is a fast-fail signal. Each entry is an [activation method](/docs/media-buy/product-discovery/media-products#activation-method-patterns). | +| `supported_activation_methods` | object[] | | **Experimental** (`media_buy.audience_activation` — MUST be listed in `experimental_features` when present; see [Experimental status](/docs/reference/experimental-status)). 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. Absence of this field with `media_buy.audience_activation` listed in `experimental_features` means walk the catalog — only a present, non-overlapping union is a fast-fail signal. When present, it also declares inline member push: the seller accepts `add` and `remove` on `sync_audiences` only when the union includes the `sync_audiences` pattern. Each entry is an [activation method](/docs/media-buy/product-discovery/media-products#activation-method-patterns). | #### conversion_tracking @@ -1990,7 +2017,7 @@ Agents that declare `supported: true` MUST apply the same account/caller authori - `media_buy.execution.targeting.property_list_exclude: true` → At least one product supports property exclusion; inspect that product's `overlay_support.property_list_exclude` - `media_buy.execution.targeting.placement_selection: true` → At least one product supports purchased-placement selection; inspect that product's targetable placements and `overlay_support.placement_selection` - `media_buy.content_standards` object present → Seller MUST apply content standards when provided -- `media_buy.audience_targeting` object present → Seller MUST support [`sync_audiences`](/docs/media-buy/task-reference/sync_audiences) and audience targeting overlays +- `media_buy.audience_targeting` object present → Seller MUST support `audience_include`/`audience_exclude` overlays and answer discovery-only [`sync_audiences`](/docs/media-buy/task-reference/sync_audiences); it MUST also accept inline member push unless `audience_targeting.supported_activation_methods` is present without the `sync_audiences` pattern - `media_buy.conversion_tracking` object present → Seller MUST support [`sync_event_sources`](/docs/media-buy/task-reference/sync_event_sources) and [`log_event`](/docs/media-buy/task-reference/log_event) - AXE URL in `media_buy.execution.axe_integrations` → Seller can execute through that exchange (legacy — new integrations use [TMP](/docs/trusted-match)) diff --git a/docs/reference/experimental-status.mdx b/docs/reference/experimental-status.mdx index 072b7daaf28..951c8932229 100644 --- a/docs/reference/experimental-status.mdx +++ b/docs/reference/experimental-status.mdx @@ -121,7 +121,7 @@ Schemas marked with `x-status: experimental` are the authoritative source. The c | `sponsored_intelligence.core` | [`si_get_offering`](/docs/sponsored-intelligence/tasks/si_get_offering), [`si_initiate_session`](/docs/sponsored-intelligence/tasks/si_initiate_session), [`si_send_message`](/docs/sponsored-intelligence/tasks/si_send_message), [`si_terminate_session`](/docs/sponsored-intelligence/tasks/si_terminate_session); the `sponsored_intelligence` capability field on `get_adcp_capabilities`; the SI identity, capability negotiation, and UI component surfaces defined in the [SI specification](/docs/sponsored-intelligence/specification) | Conversational brand experiences are a new advertising model. Session lifecycle, UI components, identity/consent object shape, and capability negotiation are expected to evolve as first-party AI hosts and brand agents integrate. Planned changes track the [3.1.0 roadmap](https://github.com/adcontextprotocol/adcp/issues/2201). | | `creative.evaluator` | The `evaluator` input on [`build_creative`](/docs/creative/task-reference/build_creative), the per-leaf `eval` block on the build response, and the `creative.supports_evaluator` capability field on `get_adcp_capabilities` (schema: `core/evaluator-spec.json`) | New gate-then-rank creative-feature-oracle surface (#5241 / #5311), not yet field-tested across parties. Evaluator ranking intentionally reuses the existing stable creative-feature catalog rather than minting a parallel evaluator catalog: `rank_by`, `feature_requirement`, and `eval.features[]` all refer to feature IDs from `governance.creative_features`. Evaluator sources are `exemplars` or an allowlisted `agent_url`; the earlier account-arranged `evaluator_id` form was removed in 3.3 (see [Migrating from 3.2 to 3.3](/docs/reference/migration/3-2-to-3-3#experimental-creative-evaluator-drops-evaluator_id)). A separate `supports_evaluator_gate` capability and a hard MUST-enforce-gate semantic are reserved follow-ons that may reshape the evaluator fields. The `evaluator_id` removal in 3.3 waives the 6-week pre-landing notice: beta.0 is the notice vehicle, and GA ships no earlier than 6 weeks after the beta.0 tag. | | `creative.signal_fanout` | The `signal_conditions[]` and `selection_strategy` inputs on [`build_creative`](/docs/creative/task-reference/build_creative), the `creatives[].signal_condition` / `selection_strategy_applied` / `estimate.conditions_total` fields on its response, the `creative.multiplicity.supports_signal_fanout` / `max_signal_conditions_limit` / `selection_strategies` capability fields on `get_adcp_capabilities`, the `enums/creative-selection-strategy.json` enum, and the `SIGNAL_TARGETING_INCOMPATIBLE` error code (#5240 / #5304, folds #5262) | New signal-driven creative fan-out surface introducing a cross-agent reject-at-trafficking MUST (`SIGNAL_TARGETING_INCOMPATIBLE`) spanning creative agent + sales agent — not yet field-tested across parties. The numeric (`value_type: numeric`) condition-compatibility comparison (range-overlap vs exact-match) is still WG-open, and the `proximity` selection strategy's geo-input binding is not yet settled — both stay revisable under experimental. Condition identity itself is resolvable today (`signal_agent_segment_id` / `signal_ref` via `get_signals`), so there is no frozen-identifier problem. | -| `media_buy.audience_activation` | The [`audience_activation`](/docs/media-buy/product-discovery/media-products#audience-activation) declaration on products, the `audience_targeting.supported_activation_methods` capability field on [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities), the `audience_activation_methods` product filter on [`get_products`](/docs/media-buy/task-reference/get_products), and the `core/audience-activation-method.json` schema (#4324). The cluster also covers [external audience source references](/docs/media-buy/task-reference/sync_audiences#external-audience-sources-experimental) on `sync_audiences` — the `source` request field (`core/audience-source.json`), the response `source` echo with `access_status`/`columns_read`, and the `SOURCE_ACCESS_FAILED` error code (#6540). | New activation-path discovery surface (how audience data moves: dataset sharing, clean rooms, platform distribution, file transfer) — not yet field-tested across parties. Pattern-specific field shapes (`consumer_identities[]` qualifiers, `bind_expiry_days` semantics), the grantee-identified admissibility boundary, and filter matching semantics all need integration experience with real Snowflake/Databricks/LiveRamp pipelines before freezing. The runtime leg (#6540) may reshape the declaration fields it consumes. | +| `media_buy.audience_activation` | The [`audience_activation`](/docs/media-buy/product-discovery/media-products#audience-activation) declaration on products, the `audience_targeting.supported_activation_methods` capability field on [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities), the `audience_activation_methods` product filter on [`get_products`](/docs/media-buy/task-reference/get_products), and the `core/audience-activation-method.json` schema (#4324). The cluster also covers [external audience source references](/docs/media-buy/task-reference/sync_audiences#external-audience-sources-experimental) on `sync_audiences` — the `source` request field (`core/audience-source.json`), the response `source` echo with `access_status`/`columns_read`, and the `SOURCE_ACCESS_FAILED` error code (#6540). From 3.3, a present `supported_activation_methods` also declares inline member push through its `sync_audiences` pattern, which decides whether `audience_targeting.supported_identifier_types` and `minimum_audience_size` are required (#8936). | New activation-path discovery surface (how audience data moves: dataset sharing, clean rooms, platform distribution, file transfer) — not yet field-tested across parties. Pattern-specific field shapes (`consumer_identities[]` qualifiers, `bind_expiry_days` semantics), the grantee-identified admissibility boundary, and filter matching semantics all need integration experience with real Snowflake/Databricks/LiveRamp pipelines before freezing. The runtime leg (#6540) may reshape the declaration fields it consumes. | | `media_buy.execution_requirements` | The experimental `Product.execution_requirements` declaration on [`get_products`](/docs/media-buy/task-reference/get_products) and [`list_products`](/docs/media-buy/task-reference/list_products) results (schema: `core/product-execution-requirement.json`), and the `error-details/execution-requirement-unmet.json` details shape for the resulting `VALIDATION_ERROR` on `create_media_buy` and `update_media_buy` (#7763) | First, account-independent half of the execution-readiness RFC. The requirement kinds and their binding points reuse existing request fields, but the vocabulary is expected to grow (lead forms, messaging destinations) and per-account readiness — which resources an account has and which one to use — is the separate `media_buy.execution_readiness` surface below and may reshape how requirements and readiness compose. | | `media_buy.execution_readiness` | The `include_execution_readiness` request field and response-level `execution_readiness` map on [`list_products`](/docs/media-buy/task-reference/list_products#per-account-execution-readiness-experimental) (schemas: `core/product-execution-readiness.json`, `core/execution-requirement-readiness.json`, `enums/execution-readiness-status.json`) (#7763). The 3.3 betas carried it on `get_products`; it moved to `list_products` before GA (#8501). | Second, account-scoped half of the execution-readiness RFC. It reports `ready`, `setup_required`, `selection_required`, `input_required`, or `unknown` per declared requirement, with account-scoped candidates. Identity selection, lead-form and messaging-destination requirements, and proposal bindings are not specified yet and may change how readiness composes with requirements. | | `signals.delivery_methods` | The `signals.delivery_methods[]` capability on [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) (schema: `core/signal-delivery-method.json`), the `delivery_method` pin on agent destinations, and the `delivery_status` (`enums/signal-delivery-status.json`), `delivery`, `delivery_error`, `match_status`, `matched_count`, `effective_match_rate`, `match_rate_basis`, `audience_size` fields on agent [`activate_signal`](/docs/signals/tasks/activate_signal#delivering-membership-to-agent-destinations-experimental) deployments (#6552) | Provider-initiated membership delivery to agent destinations consumes the experimental `media_buy.audience_activation` vocabulary and has a single implementer pull so far (a publisher ad-server seller agent). Rail-selection authority, the arrival-state vocabulary, and match-outcome placement need integration experience across real signal-agent and seller pairs before freezing. Delivery cost is absorbed in the signal price for now; rail-dependent fee declarations may follow. | diff --git a/docs/reference/migration/3-2-to-3-3.mdx b/docs/reference/migration/3-2-to-3-3.mdx index c3e45c18d9d..155ae11d812 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -16,7 +16,7 @@ description: "Role-based migration checklist for adopting the AdCP 3.3 beta whil Read these first: - [Required to claim 3.3 behavior](#required-to-claim-3-3-behavior): rules that narrow what a conformant implementation may do, including [unsupported webhook HMAC and batch bodies](#webhook-signing-mode-and-batch-bodies), [responses that conform to the served release](#responses-conform-to-the-served-release), [refinement that carries compliance forward](#refinement-carries-compliance-forward), [bounded counterparty-asserted domain lists](#counterparty-asserted-domain-lists-are-bounded), [seller revisions that advance on every committed change](#seller-revisions-advance-on-every-committed-change), [flight start for committed buys only](#flight-start-activates-committed-buys-only), [flat totals for multi-qualifier metrics](#multi-qualifier-metrics-omit-flat-totals), [enforceable domain identifiers](#property-domain-identifiers-have-an-enforceable-format), [property list references through AdCP tasks](#property-list-references-resolve-through-adcp-tasks), and [dual emission of platform IDs](#platform-ids-are-emitted-under-both-names), [`request_account` as the single account write](#request_account-is-the-single-account-write-where-supported), [the protocol envelope on every task response](#every-task-response-composes-the-protocol-envelope), [major-only requests served the oldest release](#a-major-only-request-is-served-the-oldest-supported-release), [schemas open by default](#schemas-are-open-by-default), [capabilities bounded by structure](#capabilities-are-bounded-by-structure), [`replace` that transfers assignment settings](#assignment-replace-transfers-settings-to-the-replacement), and [tracker slots that apply only where a format declares them](#tracker-slot-limits-apply-only-where-a-format-declares-tracker-slots). -- [Brand JSON size cap rises to 2 MiB](#brand-json-size-cap-rises-to-2-mib), [audience match counts](#audience-match-counts-may-be-absent), and the [4 MiB response-size default](#client-response-size-default-rises-to-4-mib): three loosened guarantees, so a 3.2 peer can reject or misread what a 3.3 peer sends. +- [Brand JSON size cap rises to 2 MiB](#brand-json-size-cap-rises-to-2-mib), [audience match counts](#audience-match-counts-may-be-absent), [audience targeting without member push](#audience-targeting-without-member-push), and the [4 MiB response-size default](#client-response-size-default-rises-to-4-mib): four loosened guarantees, so a 3.2 peer can reject or misread what a 3.3 peer sends. - [Recommended: bound agent response size](#recommended-bound-agent-response-size): a new SHOULD that tightens what an adopting buyer accepts. - [Send only to 3.3 peers](#send-only-to-3-3-peers): new fields a 3.2 validator rejects. - [Deprecations](#deprecations): `seller_id` on event source and audience results, `principal_kind` and `expected_principal_kind` on the principal tasks, the natural-key account reference after provisioning, the account identity-rekey machinery (`identity_updates`, `operator_identity`, `ACCOUNT_MOVED`, `ACCOUNT_IDENTITY_CONFLICT`, `stable_account_id`), and condition (b) of `request_signature_required`, and the boolean form of `demographics`; removal no earlier than 4.0. @@ -462,6 +462,16 @@ The brand.json body cap rises from 256 KiB to 2 MiB (2,097,152 bytes) on every f In 3.2, a `ready` audience promised `matched_count` and `effective_match_rate`. In 3.3 they MAY be absent when the seller cannot report them, and buyers MUST NOT read absence as zero; `audience_size` and `targetable_size` carry the size as a range instead. A buyer still on 3.2 expects the counts, so sellers keep populating them, where they can, for callers pinned to 3.2. +## Audience targeting without member push + +In 3.2, `media_buy.audience_targeting` promised `sync_audiences` with inline member push, and always required `supported_identifier_types` and `minimum_audience_size`. In 3.3 the object promises `audience_include` / `audience_exclude` and discovery-only `sync_audiences`, which a declaring seller MUST answer. Inline member push is declared by the `sync_audiences` pattern in the experimental `supported_activation_methods`; when that field is absent, push is supported exactly as in 3.2 ([#8936](https://github.com/adcontextprotocol/adcp/issues/8936)). + +- **Sellers that take pushed members** change nothing. A seller that already lists `supported_activation_methods` keeps the `sync_audiences` pattern in it. +- **Sellers that can target audiences already on the account but take no pushed members** can now declare `audience_targeting` with `supported_activation_methods` listing their other patterns and omitting `sync_audiences`, and `media_buy.audience_activation` in `experimental_features`. They can omit `supported_identifier_types` and `minimum_audience_size`, MUST answer discovery-only `sync_audiences`, and MUST reject an entry that carries `add` or `remove`, or that would create a new audience without a `source` reference, with `UNSUPPORTED_FEATURE`. A strict 3.2 validator still requires both fields, and `get_adcp_capabilities` runs before negotiation, so a seller that wants 3.2 readers to validate its document can keep declaring them. +- **Buyers** check `supported_activation_methods` before pushing members, and read both fields as optional. Discovery-only `sync_audiences` lists the `audience_id` values a buyer can target on any declaring seller. + +See [Sellers without inline member push](/docs/media-buy/task-reference/sync_audiences#sellers-without-inline-member-push). + ## Recommended: bound agent response size Clients SHOULD bound the size of every AdCP response they read, enforce the bound while the body is received rather than after buffering or parsing, apply it to streamed (SSE) responses both per event and cumulatively per call, surface an oversized response as an error rather than truncating it, and default to no more than 4 MiB (4,194,304 bytes). This is a recommendation, not a conformance requirement — a 3.2 implementation does not become non-conformant — but SDKs are adopting the default, so the interop effect is real. See [Response size bounds](/docs/building/by-layer/L1/security#response-size-bounds). @@ -566,6 +576,7 @@ These change generated types or bundle shape without changing what a conformant - **Envelope on every response (#8547).** Response types compose `core/protocol-envelope.json`: `status` is required on every task response and async status payload, `message` is bounded at 2,000 characters through `core/task-message.json`, `task_id` is `core/task-id.json` (`minLength: 1`), and `replayed` accepts `false`. Response roots and status branches are open, and 66 local copies of envelope fields are removed so the envelope's declarations govern. Regenerate types; a hand-written response model that omitted `status` must add it. - **Delivery rows (#8108).** `impressions` is optional on `daily_breakdown` and dimensional breakdown rows; `aggregated_totals` still requires it. - **Reporting issue codes (#8099, 3.2.4).** The closed reporting status issue-code enum gains `REVISION_UNREADABLE`, with a `reporting_revision_id` field. Strict readers must accept it. +- **Audience targeting fields (#8936).** `media_buy.audience_targeting.supported_identifier_types` and `minimum_audience_size` are no longer unconditionally required. A schema `if` / `then` requires them only when `supported_activation_methods` is absent or includes the `sync_audiences` pattern, so generated types make both optional. Readers must not assume either is present. - **Spot rows (#8017).** `by_spot[].aired_at` is required only on `aired` and `makegood` rows and on rows without `spot_status`. - **Settings-update entries.** The `sync_accounts` `SettingsUpdateMode` branch permits `brand`, `operator_unit`, `currency`, `timezone`, and `billing`, so generated settings-update types gain those five fields. `operator` stays forbidden. - **New shared schemas.** `core/audience-size.json`, and the enums `spot-status`, `daypart-time-granularity`, `audience-size-precision`, and `audience-match-rate-basis`. diff --git a/docs/reference/release-notes.mdx b/docs/reference/release-notes.mdx index 7539e486b58..8c6927f0a11 100644 --- a/docs/reference/release-notes.mdx +++ b/docs/reference/release-notes.mdx @@ -54,6 +54,7 @@ Each beta is immutable. The `3.3-beta` documentation selector advances to the la - **Trust and signing:** one agent-resolution algorithm for every signing surface (#7882); A2A operation-resolution hardening becomes MUST (#7945) and the `request_signing.operation_sources` capability (#7979); invocation messages with more than one DataPart are rejected (#8050); the brand.json cap rises to 2 MiB (#8057). - **Media buy:** optional `media_buy.features.catalog_ingestion` declarations (#7927); advertise only the `measurement_terms` you accept (#8062); `unsupported-targeting-dimension` details for `UNSUPPORTED_FEATURE` (#8052); seller-level `vendor_metric_optimization.supported_metrics` rollup (#8070); `flight_extension_opportunity` and `scale_budget_opportunity` indicator types (#8033); experimental `collection_lists` and `collection_lists_exclude` targeting (#8061); per-source archive on `sync_event_sources` (#8060). - **Capabilities:** optional `adcp.implementation.sdks[]` SDK identity and integration metadata (#8079). +- **Audiences:** `media_buy.audience_targeting` can declare a seller that targets audiences already on the account and lists them through discovery-only `sync_audiences` but takes no pushed members; `supported_identifier_types` and `minimum_audience_size` are then optional (#8936). - **Creative and collections:** assignment-scoped `landing_page_url` with `creative.supports_assignment_landing_page` (#8180) and assignment-scoped `trackers` with `creative.supports_assignment_trackers` (#8220); experimental collection cards, follower counts, response `collections`, and brand collection links (#8094, #8098, #8141); experimental `list_collections` and collection card webhooks (#8279); `creative.stable_creative_ids`, seller-ID readback, and the `merge` assignment operation (#8175, #8178); `*_as_of` freshness on creative assignment and approval state (#8174); rendered sizes on HTML and display assets, typed `video_brief`, and slot validation under every supported slot name; vendor-scoped `GDPR_CONSENT_` and `ADDTL_CONSENT` macros (#8222); creative-level `provenance` on `list_creatives` (#8063); HTML-markup legacy formats project to `display_tag` inline markup (#8357); `pixel_tracker` playback events for hosted video and audio (#8111). - **Creative and brand rules:** `build_creative` refinement carries the parent's compliance forward and never inherits approval (#7937); the experimental `evaluator_id` source form is removed (#8045); brand-wide `prohibited_terms` in brand.json (#8056); experimental advisory channel restrictions on rights constraints, with `RIGHTS_CHANNEL_VIOLATION` (#8047). - **Response size:** clients SHOULD bound agent response size (#8192), with a 4 MiB default and seller-side guidance to keep discovery responses small (#8200); push and webhook receivers SHOULD bound the inbound body (#8209). @@ -110,6 +111,7 @@ Each beta is immutable. The `3.3-beta` documentation selector advances to the la - **Loosened: tracker slots (#8715).** A seller applies tracker-slot limits only when the effective format declares a tracker slot. Against a format that declares none, such as canonical `image`, it no longer rejects an assignment tracker for lack of a slot; it fires every accepted tracker or rejects the assignment. - **Loosened: brand.json cap 2 MiB (#8057).** A verifier still enforcing 256 KiB rejects a brand.json a 3.3 verifier accepts. - **Loosened: audience match counts (#8024).** A `ready` audience no longer promises `matched_count` and `effective_match_rate`. +- **Loosened: audience targeting without member push (#8936).** `media_buy.audience_targeting` now promises `audience_include` / `audience_exclude` and discovery-only `sync_audiences`, which a declaring seller MUST answer, but not inline member push. The `sync_audiences` pattern in the experimental `supported_activation_methods` declares push; with the field absent, push is supported as in 3.2. `supported_identifier_types` and `minimum_audience_size` are required only when the seller accepts push, and a seller without it rejects `add` / `remove` member deltas with `UNSUPPORTED_FEATURE`. A strict 3.2 validator still requires both fields. - **Loosened: client response-size default 4 MiB (#8200).** A client still on 1 MiB rejects a response a 3.3 client accepts. The new SHOULD to bound responses (#8192) tightens what an adopting buyer accepts. - **Loosened: webhook `authentication` optional (#8177).** `reporting_webhook.authentication` and `create_media_buy.artifact_webhook.authentication` are no longer required on a request served at 3.3 or later; the seller signs deliveries under the registration's signing profile. A request served below 3.3 still requires the block. - **Loosened: `setup_url` pattern (#8548).** `core/agent-reporting-destination-state.json` accepts any `https` URI, including a query string and percent-encoding. A 3.2 sender's value still validates. The rule that the URL carries no credential, userinfo, or signed component remains normative for receivers. diff --git a/docs/reference/versioning.mdx b/docs/reference/versioning.mdx index b64ef874a50..3fa28166dbb 100644 --- a/docs/reference/versioning.mdx +++ b/docs/reference/versioning.mdx @@ -288,7 +288,7 @@ AdCP 3.3 adds optional stable fields, enum values, and capability declarations, | An account is its `account_id` | Every seller MUST return `account_id` from `sync_accounts` once the account is resolved, accept it on every account-scoped task, and never change it. In 3.2, returning it was a SHOULD and accepting it was optional. A provisioning entry never changes an existing account. When it matches exactly one account in the seller's account scope, the seller SHOULD return that `account_id` instead of opening another. `brand.countries`, `currency`, `timezone`, `sandbox`, and `operator_unit` are account attributes that filter a natural-key reference. That reference resolves only when exactly one account matches; otherwise the seller returns `ACCOUNT_AMBIGUOUS`. A seller that opens buyer-declared accounts through `sync_accounts` accepts settings-update entries, which in 3.2 it could reject. It MAY refuse a `currency` or `timezone` change, never changes `sandbox`, and MAY review a `countries` change, reporting `pending_approval` on the entry. No field is removed; settings-update entries accept the attributes. | [#8442](https://github.com/adcontextprotocol/adcp/issues/8442), [Account identity is the account ID](/docs/reference/migration/3-2-to-3-3#account-identity-is-the-account-id) | | Unsupported webhook HMAC is a task error; batches rejected | A seller with `legacy_hmac_fallback: false` rejects a registration carrying `authentication` with `UNSUPPORTED_FEATURE`, not `request_signature_required`. Condition (b) of `request_signature_required` is deprecated and removed in 4.0. A JSON array body is rejected with `request_body_malformed`. | #7563, #7565, [Migrating from 3.2 to 3.3](/docs/reference/migration/3-2-to-3-3#webhook-signing-mode-and-batch-bodies) | -Three other guarantees loosen rather than narrow. The brand.json body cap rises from 256 KiB to 2 MiB (#8057), so a verifier still on the 3.2 cap can reject a brand.json a 3.3 verifier accepts. A `ready` audience no longer promises `matched_count` and `effective_match_rate` (#8024). The recommended client response-size default rises from 1 MiB to 4 MiB (#8200), so a client on the older figure can reject a response a 3.3 client accepts. The new SHOULD that clients bound response size (#8192) is a recommendation, not an exception. See [the migration guide](/docs/reference/migration/3-2-to-3-3#brand-json-size-cap-rises-to-2-mib). +Four other guarantees loosen rather than narrow. The brand.json body cap rises from 256 KiB to 2 MiB (#8057), so a verifier still on the 3.2 cap can reject a brand.json a 3.3 verifier accepts. A `ready` audience no longer promises `matched_count` and `effective_match_rate` (#8024). `media_buy.audience_targeting` no longer promises inline member push, and `supported_identifier_types` and `minimum_audience_size` are required only when the seller accepts it (#8936); a 3.2 validator still requires both ([Audience targeting without member push](/docs/reference/migration/3-2-to-3-3#audience-targeting-without-member-push)). The recommended client response-size default rises from 1 MiB to 4 MiB (#8200), so a client on the older figure can reject a response a 3.3 client accepts. The new SHOULD that clients bound response size (#8192) is a recommendation, not an exception. See [the migration guide](/docs/reference/migration/3-2-to-3-3#brand-json-size-cap-rises-to-2-mib). **Correction: schemas opened.** Some 3.x schemas were published closed with no structural reason, among them the 3.2 proposal-flow task roots and their containers. 3.3 opens them, and a 3.2.x patch opens them too, as a correction under [DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md). Opening a schema rejects nothing that was valid before. New 3.3 fields on these schemas go only to peers that negotiated 3.3. See [the migration guide](/docs/reference/migration/3-2-to-3-3#send-only-to-3-3-peers). diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index 145503ccc8c..aff8ee9b03a 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -205,6 +205,7 @@ Two more guarantees loosen here, and the response-size default a third ([below]( - **Event source archive.** A seller that declares `media_buy.event_source_archive` accepts `archived` on `sync_event_sources` items to archive or restore a source without losing its configuration. See [Archiving an event source](/docs/media-buy/task-reference/sync_event_sources#archiving-an-event-source). - **Creative and brand.** `list_creatives` echoes creative-level `provenance`; brand.json gains a brand-wide `prohibited_terms` list; rights constraints can carry advisory `channels[]` and `excluded_channels[]` (experimental, `brand.rights_lifecycle`); and the HTML-markup legacy formats project to `display_tag` inline markup instead of `html5`. - **Delivery types.** `media_buy.supported_delivery_types` declares whether a seller sells `guaranteed` inventory, `non_guaranteed` inventory, or both, so buyers can skip sellers that don't sell what they're buying before calling `get_products`. A declaring seller returns only products with a listed `delivery_type`. +- **Audience targeting without member push ([#8936](https://github.com/adcontextprotocol/adcp/issues/8936)).** `media_buy.audience_targeting` now means the seller supports `audience_include` and `audience_exclude` and answers discovery-only `sync_audiences`, which a declaring seller MUST do. It no longer promises inline member push. The `sync_audiences` pattern in the experimental `supported_activation_methods` declares push, and when that field is absent push is supported, as in 3.2. A seller that lists other patterns but not `sync_audiences` can omit `supported_identifier_types` and `minimum_audience_size`, and rejects `add` / `remove` member deltas with `UNSUPPORTED_FEATURE`. This fits a platform that can target the audiences already on an account but can't take a customer list. See [Sellers without inline member push](/docs/media-buy/task-reference/sync_audiences#sellers-without-inline-member-push). - **The `ext.adcp` namespace.** `ext.adcp` is a registered, AdCP-owned extension namespace. Its first member is an optional `opportunity` binding for cooperating 3.2 `get_products` integrations. See [AdCP opportunity extension](/docs/building/by-layer/L2/context-sessions#adcp-opportunity-extension). ## Bounded agent responses @@ -323,6 +324,7 @@ These merged on `main` during the 3.3 cycle and were also released on the 3.2 li | Any agent that sends AdCP responses | Emit only properties the served release defines, plus `ext.{namespace}` and open-payload fields. | | A verifier that computes eTLD+1 | Use a Public Suffix List bundled with the verifier and refreshed through dependency updates; never fetch it at runtime. | | A seller that matches identifiers for frequency caps | Optionally declare match keys under `media_buy.match_keys` (experimental), and send `Product.identity.match_keys` only to callers served 3.3. | +| A buyer or SDK that reads `audience_targeting` | Treat `supported_identifier_types` and `minimum_audience_size` as optional, and push members only when `supported_activation_methods` is absent or includes the `sync_audiences` pattern. Discovery-only `sync_audiences` works on every declaring seller. | ## Withdrawn from 3.3, planned for 4.0 diff --git a/package.json b/package.json index 4e14434ac6a..47ed719c377 100644 --- a/package.json +++ b/package.json @@ -76,7 +76,7 @@ "test:targeting-aware-discovery": "node --test --test-force-exit --test-timeout=30000 tests/targeting-aware-discovery.test.cjs tests/product-coverage-filters.test.cjs", "test:geo-region-targeting": "node --test --test-force-exit --test-timeout=30000 tests/geo-region-targeting.test.cjs", "test:demographic-targeting": "node --test --test-force-exit --test-timeout=30000 tests/demographic-targeting.test.cjs", - "test:audience-activation-methods": "node --test --test-force-exit --test-timeout=30000 tests/audience-activation-methods.test.cjs", + "test:audience-activation-methods": "node --test --test-force-exit --test-timeout=30000 tests/audience-activation-methods.test.cjs tests/audience-targeting-member-push.test.cjs", "test:principal": "node --test --test-force-exit --test-timeout=30000 tests/principal-contract.test.cjs", "test:signal-delivery-methods": "node --test --test-force-exit --test-timeout=30000 tests/signal-delivery-methods.test.cjs", "test:audience-external-sources": "node --test --test-force-exit --test-timeout=30000 tests/audience-external-sources.test.cjs", diff --git a/static/schemas/source/media-buy/sync-audiences-request.json b/static/schemas/source/media-buy/sync-audiences-request.json index a880799fc30..5a3c9792d58 100644 --- a/static/schemas/source/media-buy/sync-audiences-request.json +++ b/static/schemas/source/media-buy/sync-audiences-request.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/media-buy/sync-audiences-request.json", "title": "Sync Audiences Request", - "description": "Request parameters for managing CRM-based audiences on an account with upsert semantics. Existing audiences matched by audience_id are updated, new ones are created. Members are specified as delta operations: add appends new members, remove drops existing ones. Recommend no more than 100,000 members per call; for larger lists, chunk and call incrementally using add/remove deltas. When delete_missing is true, buyer-managed audiences on the account not in this request are removed — do not combine with omitted audiences or all buyer-managed audiences will be deleted. When audiences is omitted, the call is discovery-only: it returns all audiences on the account without modification.", + "description": "Request parameters for managing CRM-based audiences on an account with upsert semantics. Existing audiences matched by audience_id are updated, new ones are created. Members are specified as delta operations: add appends new members, remove drops existing ones. Recommend no more than 100,000 members per call; for larger lists, chunk and call incrementally using add/remove deltas. When delete_missing is true, buyer-managed audiences on the account not in this request are removed — do not combine with omitted audiences or all buyer-managed audiences will be deleted. When audiences is omitted, the call is discovery-only: it returns all audiences on the account without modification. Every seller that declares media_buy.audience_targeting in get_adcp_capabilities answers discovery-only calls; inline member push is declared separately (see media_buy.audience_targeting.supported_activation_methods).", "x-tool-summary": "List or synchronize account audiences with upsert, member-delta, and optional replacement semantics.", "type": "object", "allOf": [ @@ -25,7 +25,7 @@ }, "audiences": { "type": "array", - "description": "Audiences to sync (create or update). When omitted, the call is discovery-only and returns all existing audiences on the account without modification.", + "description": "Audiences to sync (create or update). When omitted, the call is discovery-only and returns all existing audiences on the account without modification; every seller that declares media_buy.audience_targeting answers it. A seller whose media_buy.audience_targeting.supported_activation_methods omits the sync_audiences pattern does not accept inline member push: it rejects, with UNSUPPORTED_FEATURE, an entry that carries add or remove or that would create a new audience without a source reference.", "minItems": 1, "items": { "type": "object", diff --git a/static/schemas/source/protocol/get-adcp-capabilities-response.json b/static/schemas/source/protocol/get-adcp-capabilities-response.json index 468b6968615..ee97db1032d 100644 --- a/static/schemas/source/protocol/get-adcp-capabilities-response.json +++ b/static/schemas/source/protocol/get-adcp-capabilities-response.json @@ -2490,11 +2490,11 @@ }, "audience_targeting": { "type": "object", - "description": "Audience targeting capabilities. Presence of this object indicates the seller supports audience targeting, including sync_audiences and audience_include/audience_exclude in targeting overlays.", + "description": "Audience targeting capabilities. Presence of this object indicates the seller supports audience_include and audience_exclude in targeting overlays, and discovery-only sync_audiences (called without audiences), which lists the audiences on the account and the audience_id values those overlays reference. A seller that declares this object MUST answer discovery-only sync_audiences. Presence alone does not promise inline member push: the sync_audiences pattern in supported_activation_methods declares it, and when supported_activation_methods is absent inline member push is supported, as in 3.2. A seller whose supported_activation_methods omits the sync_audiences pattern MUST reject, with UNSUPPORTED_FEATURE, an audiences entry that carries add or remove member deltas or that would create a new audience without a source reference. supported_identifier_types and minimum_audience_size are required only when the seller accepts inline member push.", "properties": { "supported_identifier_types": { "type": "array", - "description": "PII-derived identifier types accepted for audience matching. Buyers should only send identifiers the seller supports.", + "description": "PII-derived identifier types accepted for audience matching. Buyers should only send identifiers the seller supports. Required when the seller accepts inline member push, that is when supported_activation_methods is absent or includes the sync_audiences pattern.", "items": { "type": "string", "enum": ["hashed_email", "hashed_phone"] @@ -2517,13 +2517,13 @@ }, "minimum_audience_size": { "type": "integer", - "description": "Minimum matched audience size required for targeting. Audiences below this threshold will have status: too_small. Varies by platform (100–1000 is typical).", + "description": "Minimum matched audience size required for targeting. Audiences below this threshold will have status: too_small. Varies by platform (100–1000 is typical). Required when the seller accepts inline member push, that is when supported_activation_methods is absent or includes the sync_audiences pattern. A seller without inline member push MAY still declare it.", "minimum": 1 }, "supported_activation_methods": { "type": "array", "x-status": "experimental", - "description": "Union of audience_activation.methods across the seller's products. Fast-fail discovery: a buyer reads this once and skips the catalog walk when nothing overlaps its pipeline. Per-product declarations are the source of truth; sellers MUST keep this consistent with the catalog. Operational coordinates are account-scoped: the union MAY omit consumer_identities and destination_ref until bilateral account setup establishes them, and MUST NOT expose another account's coordinates. Absence of this field with media_buy.audience_activation listed in experimental_features means walk the catalog; only a present, non-overlapping union is a fast-fail signal. Experimental (x-status: experimental): sellers implementing audience activation declarations MUST list media_buy.audience_activation in experimental_features. Per docs/reference/experimental-status, this surface MAY change between 3.x releases with notice.", + "description": "Union of audience_activation.methods across the seller's products. Fast-fail discovery: a buyer reads this once and skips the catalog walk when nothing overlaps its pipeline. Per-product declarations are the source of truth; sellers MUST keep this consistent with the catalog. Operational coordinates are account-scoped: the union MAY omit consumer_identities and destination_ref until bilateral account setup establishes them, and MUST NOT expose another account's coordinates. Absence of this field with media_buy.audience_activation listed in experimental_features means walk the catalog; only a present, non-overlapping union is a fast-fail signal. When present, the field also declares inline member push: the seller accepts add and remove member deltas on sync_audiences only when the union includes the sync_audiences pattern. Experimental (x-status: experimental): sellers implementing audience activation declarations MUST list media_buy.audience_activation in experimental_features. Per docs/reference/experimental-status, this surface MAY change between 3.x releases with notice.", "items": { "$ref": "/schemas/core/audience-activation-method.json" }, @@ -2546,7 +2546,27 @@ "additionalProperties": true } }, - "required": ["supported_identifier_types", "minimum_audience_size"], + "if": { + "description": "The seller accepts inline member push: supported_activation_methods is absent, as in 3.2, or includes the sync_audiences pattern.", + "anyOf": [ + { "not": { "required": ["supported_activation_methods"] } }, + { + "properties": { + "supported_activation_methods": { + "contains": { + "type": "object", + "properties": { "pattern": { "const": "sync_audiences" } }, + "required": ["pattern"] + } + } + }, + "required": ["supported_activation_methods"] + } + ] + }, + "then": { + "required": ["supported_identifier_types", "minimum_audience_size"] + }, "additionalProperties": true }, "supported_optimization_metrics": { diff --git a/tests/audience-targeting-member-push.test.cjs b/tests/audience-targeting-member-push.test.cjs new file mode 100644 index 00000000000..8ac7416a7e0 --- /dev/null +++ b/tests/audience-targeting-member-push.test.cjs @@ -0,0 +1,151 @@ +/** + * audience_targeting without inline member push (#8936). + * + * supported_identifier_types and minimum_audience_size describe matching of + * pushed members, so they are required only when the seller accepts inline + * member push: supported_activation_methods is absent (the 3.2 meaning) or + * includes the sync_audiences pattern. A seller that declares + * supported_activation_methods without that pattern can declare + * audience_targeting with neither field. + */ +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const { describe, it, before } = require('node:test'); +const Ajv = require('ajv'); +const addFormats = require('ajv-formats'); + +const SCHEMA_ROOT = path.join(__dirname, '..', 'static', 'schemas', 'source'); +const CAPABILITIES_URI = '/schemas/protocol/get-adcp-capabilities-response.json'; + +function readSchema(uri) { + assert.match(uri, /^\/schemas\//); + return JSON.parse(fs.readFileSync(path.join(SCHEMA_ROOT, uri.slice('/schemas/'.length)), 'utf8')); +} + +function newAjv() { + const ajv = new Ajv({ allErrors: true, strict: false, loadSchema: async uri => readSchema(uri) }); + addFormats(ajv); + return ajv; +} + +const SYNC_AUDIENCES = { pattern: 'sync_audiences' }; +const DATASET_QUERY = { pattern: 'dataset_query', vendor: { domain: 'data-cloud.example' } }; +const PLATFORM_DISTRIBUTION = { pattern: 'platform_distribution', vendor: { domain: 'activation-hub.example' } }; +const MATCHING = { supported_identifier_types: ['hashed_email'], minimum_audience_size: 100 }; + +function capabilities(audienceTargeting) { + return { + status: 'completed', + adcp: { major_versions: [3], idempotency: { supported: false } }, + supported_protocols: ['media_buy'], + ...(audienceTargeting.supported_activation_methods && { + experimental_features: ['media_buy.audience_activation'], + }), + media_buy: { audience_targeting: audienceTargeting }, + }; +} + +describe('audience_targeting member-push requirements', () => { + let validateAudienceTargeting; + let validateCapabilities; + + before(async () => { + const response = readSchema(CAPABILITIES_URI); + const audienceTargeting = response.properties.media_buy.properties.audience_targeting; + validateAudienceTargeting = await newAjv().compileAsync(audienceTargeting); + validateCapabilities = await newAjv().compileAsync(response); + }); + + function accepts(value, message) { + assert.equal(validateAudienceTargeting(value), true, `${message}: ${JSON.stringify(validateAudienceTargeting.errors)}`); + assert.equal(validateCapabilities(capabilities(value)), true, `${message}: ${JSON.stringify(validateCapabilities.errors)}`); + } + + function rejects(value, message) { + assert.equal(validateAudienceTargeting(value), false, message); + assert.equal(validateCapabilities(capabilities(value)), false, message); + const missing = validateAudienceTargeting.errors + .filter(error => error.keyword === 'required') + .map(error => error.params.missingProperty); + assert.ok(missing.length > 0, `${message}: expected a missing required field, got ${JSON.stringify(validateAudienceTargeting.errors)}`); + } + + describe('positive vectors', () => { + it('accepts the 3.2 shape: no supported_activation_methods, both matching fields', () => { + accepts({ ...MATCHING, matching_latency_hours: { min: 1, max: 24 } }, '3.2 shape'); + }); + + it('accepts inline push with both matching fields', () => { + accepts({ ...MATCHING, supported_activation_methods: [SYNC_AUDIENCES, DATASET_QUERY] }, 'push declared'); + }); + + it('accepts a seller without inline push that omits both matching fields', () => { + accepts({ supported_activation_methods: [PLATFORM_DISTRIBUTION] }, 'no push, no matching fields'); + accepts({ supported_activation_methods: [DATASET_QUERY, PLATFORM_DISTRIBUTION] }, 'no push, two rails'); + }); + + it('accepts a seller without inline push that still declares matching fields', () => { + accepts({ ...MATCHING, supported_activation_methods: [DATASET_QUERY] }, 'no push, both fields'); + accepts({ minimum_audience_size: 1000, supported_activation_methods: [DATASET_QUERY] }, 'no push, size only'); + }); + }); + + describe('negative vectors', () => { + it('still requires both matching fields when supported_activation_methods is absent', () => { + rejects({}, 'empty object keeps 3.2 required fields'); + rejects({ supported_identifier_types: ['hashed_email'] }, 'missing minimum_audience_size'); + rejects({ minimum_audience_size: 100 }, 'missing supported_identifier_types'); + }); + + it('requires both matching fields when the sync_audiences pattern is declared', () => { + rejects({ supported_activation_methods: [SYNC_AUDIENCES] }, 'push declared, no matching fields'); + rejects( + { minimum_audience_size: 100, supported_activation_methods: [DATASET_QUERY, SYNC_AUDIENCES] }, + 'push declared, missing supported_identifier_types' + ); + rejects( + { supported_identifier_types: ['hashed_phone'], supported_activation_methods: [SYNC_AUDIENCES] }, + 'push declared, missing minimum_audience_size' + ); + }); + + it('keeps the field shapes when they are optional', () => { + assert.equal( + validateAudienceTargeting({ supported_identifier_types: [], supported_activation_methods: [DATASET_QUERY] }), + false, + 'supported_identifier_types keeps minItems' + ); + assert.equal( + validateAudienceTargeting({ minimum_audience_size: 0, supported_activation_methods: [DATASET_QUERY] }), + false, + 'minimum_audience_size keeps minimum' + ); + assert.equal( + validateAudienceTargeting({ supported_activation_methods: [] }), + false, + 'an empty supported_activation_methods is not a no-push declaration' + ); + }); + + it('still requires the experimental feature id for supported_activation_methods', () => { + const document = capabilities({ supported_activation_methods: [PLATFORM_DISTRIBUTION] }); + delete document.experimental_features; + assert.equal(validateCapabilities(document), false); + }); + }); + + it('states the discovery and push rules in the schema descriptions', () => { + const response = readSchema(CAPABILITIES_URI); + const audienceTargeting = response.properties.media_buy.properties.audience_targeting; + assert.match(audienceTargeting.description, /MUST answer discovery-only sync_audiences/); + assert.match(audienceTargeting.description, /does not promise inline member push/); + assert.match(audienceTargeting.description, /UNSUPPORTED_FEATURE/); + assert.equal(audienceTargeting.required, undefined, 'matching fields are required only through if/then'); + assert.deepEqual(audienceTargeting.then.required, ['supported_identifier_types', 'minimum_audience_size']); + + const request = readSchema('/schemas/media-buy/sync-audiences-request.json'); + assert.match(request.properties.audiences.description, /UNSUPPORTED_FEATURE/); + assert.match(request.description, /answers discovery-only calls/); + }); +});