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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/adjacent-code-3-4.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": minor
---

Propose AdCP 3.4 adjacent-code disclosure on products and application-state readback on creative assignments. Add the delivery-affecting `adjacent_code_changed` assignment invalidation while preserving creative approval semantics. Provider references are opaque and seller-scoped. WG approval is pending. Fragment delivery and assembly signing remain a separate proposal.
172 changes: 172 additions & 0 deletions docs/creative/adjacent-code.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
---
title: Adjacent code
description: Product disclosure and assignment readback for seller-side code alongside a buyer creative.
---

<Warning>
Proposed for AdCP 3.4 under [#6700](https://github.com/adcontextprotocol/adcp/issues/6700).
Working Group approval is pending. This draft follows
[Bokelley's proposed split](https://github.com/adcontextprotocol/adcp/issues/6700#issuecomment-6921184576).
Fragment delivery and assembly signing remain a separate proposal, with no release commitment.
</Warning>

`adjacent_code` describes seller-side code applied alongside a buyer creative,
including the seller's own first-party measurement code. It gives buyers a
product declaration before purchase and a current application snapshot for each
package–creative assignment. Buyer-supplied assignment `trackers` and code already
inside the creative remain on their existing surfaces and MUST NOT be included
in this array.

## Product declaration

In AdCP 3.4, `canonical-product` and `product` MAY carry `adjacent_code[]`.
When present, it MUST be the complete declaration of adjacent code for the
product. Omission means undeclared; it MUST NOT be interpreted as no code.
`[]` explicitly declares no adjacent code.

Each entry contains:

| Field | Meaning |
| --- | --- |
| `provider` | An opaque reference scoped to the selling agent. `seller` is reserved for that agent's own first-party code. Other references identify providers without publishing an integration endpoint or global vendor directory. |
| `purpose` | A buyer-readable description such as `measurement` or `verification`; the vocabulary is open. |
| `required` | Whether the seller requires the code for delivery. This is an explicit boolean, with no default. |

Provider references MUST remain stable across a seller's product declarations
and assignment snapshots, and MUST NOT be reused for a different provider.
They are meaningful only together with the selling agent's identity. A provider
reference is not a BrandRef, an authentication credential, or a URL to resolve.
Integration URLs and configuration MUST remain seller-local, including when
using `ext` or future extension properties.

```json
{
"$schema": "https://adcontextprotocol.org/schemas/latest/core/canonical-product.json",
"product_id": "display_homepage",
"name": "Homepage display",
"adjacent_code": [
{ "provider": "seller", "purpose": "measurement", "required": true },
{ "provider": "provider_7", "purpose": "verification", "required": false }
]
}
```

Buyers that need this information SHOULD request `adjacent_code` in the product
`fields` projection. Projection does not imply a negative declaration: a field
excluded by projection remains unknown. Buyers MUST NOT send the new projection
value to a seller serving a release before 3.4. The field follows existing
product feed and cache invalidation rules when its declaration changes.

## Assignment readback

The assignment snapshot is available at:

- `list_creatives.creatives[].assignments.assigned_packages[].adjacent_code`
- `get_media_buys.media_buys[].packages[].creative_approvals[].adjacent_code`

A seller disclosing adjacent code for a product MUST include the complete array
on returned assignments for that product. If it exposes both reads, their
arrays MUST agree for the same relationship and current state. `get_media_buys`
remains the complete relationship read; `list_creatives` remains a bounded
reverse projection and retains its existing truncation rules. Omission means
undeclared, and `[]` reports no adjacent code for this assignment.

Each entry carries the declaration fields plus `position` and `status`.
`position` is `prepend` or `append` relative to the unchanged buyer creative in
the seller's delivery representation. Pending or omitted entries report their
intended position. Array order is not an instruction to the seller and does not
guarantee browser execution order. Multiple applications of one provider's
code may appear as separate entries.

| `status` | Meaning |
| --- | --- |
| `applied` | The seller has applied the code to this assignment's current delivery representation. |
| `pending` | Application has not completed. |
| `omitted` | The code is absent from that representation. Retain the entry so omission is visible. |

For example, this entry can coexist with assignment `approval_status: "approved"`
and library creative `status: "approved"`:

```json
{
"$schema": "https://adcontextprotocol.org/schemas/latest/core/adjacent-code-application.json",
"provider": "seller",
"purpose": "measurement",
"required": true,
"position": "append",
"status": "pending"
}
```

This snapshot is the seller's assertion about its current delivery
representation. It does not prove that the code executed in a browser or that
measurement succeeded. It is not a historical per-impression log. In particular,
`approval_status_as_of` remains the freshness clock for creative review, not
for adjacent-code application.

## Delivery and changes after purchase

When any entry is `required: true` and has `status: pending` or `omitted`, the
seller MUST hold delivery of that assignment. The hold applies both before
initial delivery and after delivery has begun. It MUST NOT change the creative's
library status or the assignment's `approval_status`, which describes creative
review. The per-entry status represents this hold; no new general assignment
status or approval enum value is introduced.

Optional pending or omitted code does not create this hold. When all required
entries become `applied`, this particular hold ends; existing approval and
serving constraints still apply. Other assignments remain subject to their own
eligibility and existing package-level rules. Sellers MUST NOT erase an
unavailable required entry or silently downgrade `required` to bypass the hold.
Retry scheduling, hold deadlines, and vendor failure feedback are seller-local.

After purchase, readback MUST reflect the effective policy and application state
of the existing assignment. A product declaration describes the current offer;
changing it does not retrospectively rewrite an assignment's application state.
A seller changing an existing assignment's effective policy MUST update that
assignment's readback and apply the delivery rule above. Removing a requirement
through an authorized policy change can release the hold and is subject to the
notification rule below.

These fields do not change accepted commercial terms or grant consent to add
code. Publisher and seller-operator authorization remain prerequisites managed
outside this buyer-facing contract. Existing commercial agreements continue to
govern permitted changes; this proposal adds no buyer acceptance token or
binding commercial-term field. It introduces no new prohibition on legacy
purchase paths. The same readback rules apply to existing assignments regardless
of how they were purchased, when the seller serves this 3.4 feature.

## Delivery-affecting invalidation

Sellers supporting the existing `creative.assignment_changed` notification use
`change_kind: "adjacent_code_changed"` when required adjacent-code state affects
an assignment's delivery. Publish the updated readback before firing. Apply the
existing account subscription, authentication, and deduplication rules; this
change adds no signing profile. Receivers reread `get_media_buys` instead of
applying state from the invalidation payload.

| Transition | Emit `adjacent_code_changed`? |
| --- | --- |
| Required code enters or leaves `pending` | Yes, including recovery to `applied` or transition to `omitted`. |
| Required code becomes `omitted`, or recovers from `omitted` to `applied` | Yes. |
| Adding, removing, or changing a requirement blocks or releases the assignment | Yes. |
| An unrelated configuration or purpose edit; optional code changes state | No. |
| The seller rereads identical state | No. |

A required entry's pending/omitted transition still fires when another required
entry also blocks the assignment: buyers need the updated reason for the hold.
An assignment's initial creation and removal continue to use `assigned` and
`unassigned`; they do not require a second adjacent-code event for the same
creation or removal. Creative approval changes retain `approval_changed`.

Subscriptions remain prospective. A buyer establishes its baseline using the
existing complete-read procedure and can poll when notifications are unsupported.
The new change kind is introduced in 3.4 and follows the protocol's existing
unknown-enum tolerance rule; an unknown kind must not be treated as an approval
outcome. Product and readback fields follow served-release conformance under
[DR-0024](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0024-responses-conform-to-served-release.md).

The schemas are open for additive extensions under
[DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md).
This proposal adds no fragment task, vendor registration API, or assembly
attestation. Those require separate WG review.
4 changes: 4 additions & 0 deletions docs/creative/task-reference/list_creatives.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -321,6 +321,10 @@ To manage one of these creatives, a buyer uses its `creative_id` as-is. See [sel

`platform_id` is the seller's identifier for the creative in its source of truth, the same value `sync_creatives` returns. It lets operators match a creative to the seller's own UI and reports without keeping the sync response. Buyers address creatives by `creative_id`, never by `platform_id`.

### Adjacent-code readback

Proposed for AdCP 3.4, with WG approval pending: each `assignments.assigned_packages[]` row MAY carry `adjacent_code[]`, mirroring [`get_media_buys`](/docs/media-buy/task-reference/get_media_buys) for the same assignment. Supporting sellers report the complete array, including pending or omitted code. Required code that is not applied holds assignment delivery while creative `status` and assignment `approval_status` retain their review meanings. Omission means undeclared; `[]` explicitly reports none. See [adjacent code](/docs/creative/adjacent-code) for provider scope and notification rules.

### Assignment indicators

In AdCP 3.3, sellers advertising `creative.supports_assignment_trackers` MUST return `assignments.assigned_packages[].trackers`: the complete assignment-scoped tracker list, or `[]` when none are attached. Preserve event names, URL templates, order, and duplicate occurrences. The list excludes the creative's own trackers in `assets`; both sets fire on this placement. See [assignment trackers](/docs/creative/task-reference/sync_creatives#assignment-trackers).
Expand Down
1 change: 1 addition & 0 deletions docs/media-buy/task-reference/get_media_buys.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,7 @@ been deleted. `ext.streamhaus.ad_set_id` here is a seller-defined extension:
| `trackers` | Added in 3.3. Complete assignment-scoped measurement tracker list, preserving events, URL templates, order, and duplicate occurrences. Supporting sellers MUST return it, using `[]` when none exist. Excludes the creative's own trackers in `assets`; both sets fire. See [assignment trackers](/docs/creative/task-reference/sync_creatives#assignment-trackers). |
| `landing_page_url` | Added in 3.3. Effective serving destination for this creative on this package, including an assignment override. Supporting sellers return the URL (or macro-bearing template) when unique; omit when no destination exists or an unoverridden creative has multiple destinations, whose URLs remain in its creative assets. See [assignment landing pages](/docs/creative/task-reference/sync_creatives#assignment-landing-pages). |
| `installment_refs` | Added in 3.3, experimental (`media_buy.installment_creative_assignment`). The installments this assignment is limited to. Sellers that list the feature return it on every assignment with an installment scope and omit it when the assignment applies to every installment. See [assigning to specific installments](/docs/creative/task-reference/sync_creatives#assigning-to-specific-installments-experimental). |
| `adjacent_code` | Proposed in 3.4; WG approval pending. Complete current seller-side code application snapshot for this assignment, including `provider`, `purpose`, `required`, `position`, and `status`. Omission means undeclared; `[]` reports none. Required pending or omitted code blocks assignment delivery without changing creative approval. Mirrors [`list_creatives`](/docs/creative/task-reference/list_creatives) readback. See [adjacent code](/docs/creative/adjacent-code). |
| `approval_status` | `pending_review`, `approved`, `partially_approved`, or `rejected` |
| `rejection_reason` | Explanation of rejection (when `approval_status` is `rejected`) |
| `approval_scopes` | Complete publisher/placement outcomes when `approval_status` is `partially_approved` |
Expand Down
4 changes: 4 additions & 0 deletions docs/media-buy/task-reference/get_products.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -702,6 +702,10 @@ The `catalog` field uses the same [Catalog](/docs/creative/catalogs) object used

Products in the response include `catalog_types` (what catalog types they support) and `catalog_match` (which items matched).

## Adjacent-code disclosure

Proposed for AdCP 3.4, with WG approval pending: returned products MAY carry `adjacent_code[]`. Each entry contains an opaque seller-scoped `provider`, a buyer-readable `purpose`, and `required`. Request the field explicitly when using `fields`; omission means undeclared and `[]` explicitly declares none. This disclosure introduces no new restriction on the legacy purchase path. See [adjacent code](/docs/creative/adjacent-code) for assignment readback and delivery holds.

## Response

Returns an array of `products` and optionally `proposals`. When the seller's
Expand Down
4 changes: 4 additions & 0 deletions docs/media-buy/task-reference/list_products.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,10 @@ For scheduled media, request `installments` in `fields` to see which episodes, i

Absence is only meaningful inside a projection that asked for the field: a product that declares `collections` and omits `installments` **in a response that returned `installments` for other products** is run-of-collection. In a projection that never requested `installments`, absence says nothing, so a buyer deciding between "specific slots" and "run-of-collection" requests the field explicitly. See [Installments in the compact lifecycle](/docs/media-buy/product-discovery/collections-and-installments#installments-in-the-compact-lifecycle).

## Adjacent-code disclosure

Proposed for AdCP 3.4, with WG approval pending: request `adjacent_code` in `fields` to read optional seller-side code declarations. Each entry identifies an opaque seller-scoped provider and purpose, with an explicit `required` policy. Omission means undeclared; `[]` explicitly declares none. This adds no purchase-path restriction or acceptance token. See [adjacent code](/docs/creative/adjacent-code) for assignment readback and changes after purchase.

## Response

Every response has an explicit `outcome`:
Expand Down
Loading
Loading