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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/audience-targeting-without-member-push.md
Original file line number Diff line number Diff line change
@@ -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.
8 changes: 4 additions & 4 deletions docs/media-buy/advanced-topics/targeting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)`.
Expand Down
4 changes: 3 additions & 1 deletion docs/media-buy/specification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1293,7 +1293,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)
Expand Down
17 changes: 14 additions & 3 deletions docs/media-buy/task-reference/sync_audiences.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -145,14 +145,24 @@ 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.

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

### 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:
Expand Down Expand Up @@ -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:

<CodeGroup>

Expand Down Expand Up @@ -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

Expand Down
Loading
Loading