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
11 changes: 11 additions & 0 deletions .changeset/dooh-impression-basis.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
"adcontextprotocol": minor
---

Add the experimental DOOH impression basis (`media_buy.dooh_impression_basis`, RFC #7253). A DOOH `impressions` figure is `plays × audience multiplier`, and the new `enums/impression-estimation-basis.json` says where the multiplier comes from: `currency_measured`, `seller_modeled`, `sensor_measured` or `hybrid`.

- Delivery: `dooh_metrics` carries `impression_basis`, `audience_multiplier` and `basis_metric`, the `vendor_metric_values[]` row a sensor audience comes from. A row mixing tiers reports `impression_basis_breakdown[]` instead: at least two entries with distinct tiers, summing exactly to the row, and no row-level tier or multiplier. `venue_breakdown[]` rows may carry the tier and `plays`, one per screen that played the spot, and no multiplier: a venue's audience per play is its `impressions / plays`.
- Forecast: forecast points, canonical ones included, carry `impression_basis`, `audience_multiplier` and `impression_basis_breakdown[]`, outside `metrics`. A breakdown includes the fallback the seller expects.
- Discovery: `dooh_placement_attributes` carries the planned tier and multiplier.

`impressions` is authoritative and the multiplier is `impressions / plays`, rounded. `hybrid` is a seller model calibrated by sensors on the seller's own screens, never a published currency nor a mix of tiers. All fields are optional. `ooh_metrics.estimation_basis` is unchanged.
57 changes: 57 additions & 0 deletions docs/creative/channels/dooh.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -256,6 +256,63 @@ Proof-of-play reporting uses `plays` for the raw playout count and `impressions`
}
```

## Impression basis (experimental)

A DOOH `impressions` figure is `plays × audience multiplier`, and the multiplier can come from a measurement currency, the seller's own model, or a sensor counting the audience at each play. Sellers that declare `media_buy.dooh_impression_basis` in `experimental_features` say which, with the tiers of `enums/impression-estimation-basis.json`. Everywhere below, `impressions` is authoritative and `audience_multiplier` is `impressions / plays`, rounded: a receiver never rejects a multiplier that differs only by rounding.

- **Discovery.** `dooh_placement_attributes.impression_basis` is the tier the seller plans to use for a placement, and `audience_multiplier` the audience per play its forecasts apply. A product mixing sensor-equipped screens and screens without a sensor declares each placement's tier. Discovery declares no fallback tier: the fallback a sensor-equipped placement expects shows in its forecast, and the realised one in delivery.
- **Forecast.** A single-tier point carries `impression_basis` and its planning `audience_multiplier`. A point covering plays expected on different tiers carries an `impression_basis_breakdown` instead, each entry with its planning multiplier. That breakdown SHOULD include the fallback the seller expects: the plays sensor-equipped screens are expected to estimate on `seller_modeled` while their sensor is not reporting. The same fields appear on the forecasts of `get_products`, `list_products` and the proposal tasks.
- **Delivery.** `dooh_metrics.impression_basis` is the tier of every play in the row. A row whose plays were estimated on different tiers reports `impression_basis_breakdown` instead. That includes a sensor-equipped screen that falls back to the seller's model while its sensor is not reporting. `basis_metric` points to the `vendor_metric_values[]` row the sensor audience comes from, whose `measurable_plays` is the sensor's coverage. A `venue_breakdown[]` row carries its tier and its `plays`, one per screen that played the spot, but no multiplier: its audience per play is `impressions / plays`.

`hybrid` is a seller model calibrated by sensors on the seller's own screens, whoever supplies them, never a published currency figure and never a mix of plays on different tiers, which the breakdown reports.

### Rows mixing tiers

When a delivery row's plays were estimated on different tiers, the seller MUST:

1. Omit the row's `impression_basis`. Never substitute `hybrid` or the majority tier.
2. Report one `impression_basis_breakdown` entry per tier present: at least two entries, with distinct tiers, whose `plays` and `impressions` sum exactly to the row's.
3. Report the fallback plays of a sensor-equipped screen, estimated while its sensor was not reporting, as `seller_modeled`.
4. Make each tier entry of a parent row (the totals, a package) equal the sum of its child rows' entries for that tier, a child with a single tier counting as one entry.
5. Omit the tier on a `venue_breakdown[]` row that mixes tiers.

A row never carries both `impression_basis` and a breakdown, and SHOULD omit its own `audience_multiplier`, each entry carrying its own. A forecast point covering several tiers follows the same rules.

### Reading the basis

- **Tiers are different units.** A sensor counts the people in its zone, a currency usually publishes a visibility-adjusted "likely to see" figure, and a seller model is traffic-based. There is no exchange rate between them: compare impressions within a tier, and plays and spend across tiers. Within `sensor_measured`, compare only rows with the same `basis_metric`: a sensor counting people in front of a screen and a turnstile counting entries are different units too.
- **Billing is unchanged.** A CPM bills the row's total `impressions`, all tiers together.
- **A blended multiplier misleads.** A multiplier over plays on several tiers mixes those units, which is why a row with a breakdown omits it.
- **A filter on `impression_basis` misses mixed rows.** A row with a breakdown has no row-level tier: read the breakdown.
- **The tier is not OpenRTB's `qty.sourcetype`.** `sourcetype` says who supplies the multiplier, the tier says how it is derived. A third-party sensor vendor is `sourcetype` 1 and `sensor_measured`.

A placement row whose sensor-equipped screens fell back to the seller's model for part of the flight:

```json
{
"placement_id": "concourse_screens",
"impressions": 510333,
"spend": 4082.66,
"plays": 27805,
"dooh_metrics": {
"screens_used": 85,
"impression_basis_breakdown": [
{ "impression_basis": "sensor_measured", "plays": 21340, "impressions": 397808, "audience_multiplier": 18.64 },
{ "impression_basis": "seller_modeled", "plays": 6465, "impressions": 112525, "audience_multiplier": 17.41 }
],
"basis_metric": { "vendor": { "domain": "metro-media.example" }, "metric_id": "people_counted" }
},
"vendor_metric_values": [{
"vendor": { "domain": "metro-media.example" },
"metric_id": "people_counted",
"value": 397808,
"unit": "persons",
"measurable_plays": 21340,
"vendor_relationship": "first_party"
}]
}
```

## Structured location for planning and mapping

Coordinates and street address are location metadata, not placement identity: a missing, imprecise, or later-corrected `location` MUST NOT change `placement_id` or `identifiers[]`. Two disclosure shapes cover the concrete and aggregate cases from [#5538](https://github.com/adcontextprotocol/adcp/issues/5538):
Expand Down
3 changes: 2 additions & 1 deletion docs/media-buy/media-buys/optimization-reporting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -231,13 +231,14 @@ A delivery or audience figure can carry several independent provenance fields. E
| `completion_source` | Who **attested to the completion event** behind `completion_rate`? | `seller_attested` or `vendor_attested` | `qualifier.completion_source` on commitments, missing metrics, and delivery values | The `completion_rate` metric only |
| `demographic_system` | What **notation** is the demographic code written in? | Notation enum (for example `nielsen`, `barb`, `nmo`, `videoamp`, `custom`) | `by_demographic` rows, demographic reporting capability, forecasts, and `cpp` pricing | One demographic code. Notation only: it does not say whose panel produced the number. |
| `estimation_basis` | How was `estimated_impressions` **derived** (static OOH)? | `currency_measured` or `seller_modeled` | `ooh_metrics.estimated_impressions` (experimental) | One OOH delivery row |
| `impression_basis` | How was the audience multiplier behind DOOH `impressions` **derived**? | `currency_measured`, `seller_modeled`, `sensor_measured`, or `hybrid`; a row mixing tiers reports `impression_basis_breakdown` instead | `dooh_metrics` on delivery rows, forecast points, and `dooh_placement_attributes` (experimental, [DOOH impression basis](/docs/creative/channels/dooh#impression-basis-experimental)) | One DOOH delivery row, forecast point, or placement |
| `circulation_basis` | How was `circulation_delivered` **derived** (print)? | `audited` or `seller_modeled` | `print_metrics.circulation_basis` on `by_installment` rows (experimental) | One print installment |
| `match_rate_basis` | Did the platform **report** `effective_match_rate`, or did the seller compute it? | `platform_reported` or `derived` | Each audience in a [`sync_audiences`](/docs/media-buy/task-reference/sync_audiences) result, beside `audience_size` and `targetable_size` | One audience match result |

How the fields combine:

- **Provider versus vendor.** `measurement_source` names a provider as a slug on a measured-channel row. `vendor` names a vendor as a BrandRef on a vendor-defined metric, and `vendor_relationship` says how that vendor stands relative to the seller. Neither is a quality ranking, and neither implies the other.
- **Tier, not provider.** `estimation_basis` and `circulation_basis` record how a figure was derived. The provider rides `measurement_source`, so an `audited` circulation figure still names its auditor there. Currencies change over time, so tier values stay stable while provider slugs vary.
- **Tier, not provider.** `estimation_basis`, `impression_basis` and `circulation_basis` record how a figure was derived. The provider rides `measurement_source`, so an `audited` circulation figure still names its auditor there. Currencies change over time, so tier values stay stable while provider slugs vary.
- **Notation, not provenance.** `demographic_system` only fixes how `P25-54` or `M25-54` is written. Report the provider that measured the audience in `measurement_source`.
- **Attestation.** `completion_source` and `vendor_relationship` both distinguish seller-produced from independent figures. `completion_source` applies to `completion_rate` only. `vendor_relationship` applies to every vendor-defined metric.
- **Basis of a rate.** `match_rate_basis` qualifies a rate, not a count: a `derived` rate computed from approximate or bucketed `audience_size` values is itself approximate.
Expand Down
2 changes: 2 additions & 0 deletions docs/media-buy/product-discovery/media-products.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -455,6 +455,8 @@ Digital out-of-home placements can declare structured selling-unit metadata via
| `loop_duration_seconds` | integer | Duration of the full ad loop rotation in seconds. Buyers derive nominal slot share as `slot_duration_seconds / loop_duration_seconds`. This is the canonical source; the pricing-layer field in `flat-rate-option` is superseded |
| `screen_resolution` | object | Physical screen resolution (`{ width, height }` in pixels). Buyers derive aspect ratio from `width / height`. Omit for audio-only placements |
| `motion` | string | Motion capability of a visual screen: `full_motion` (video), `partial_motion` (animated stills), or `static` (images only). Omit for audio-only placements |
| `impression_basis` | string | Experimental (`media_buy.dooh_impression_basis`), product and canonical placements only: the tier the seller plans to estimate the audience on (`currency_measured`, `seller_modeled`, `sensor_measured`, `hybrid`). See [DOOH impression basis](/docs/creative/channels/dooh#impression-basis-experimental) |
| `audience_multiplier` | number | Experimental (`media_buy.dooh_impression_basis`), product and canonical placements only: planning audience per play, the `impressions / plays` the seller's forecasts apply |

All fields are optional. A single visual screen/frame placement can include all fields; an audio-only placement can declare only its slot and loop timing. A package or network placement should include only fields that are uniform across the included inventory. After publisher and product declarations are resolved, `slot_duration_seconds` MUST NOT exceed `loop_duration_seconds`.

Expand Down
1 change: 1 addition & 0 deletions docs/reference/experimental-status.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,7 @@ Schemas marked with `x-status: experimental` are the authoritative source. The c
| `media_buy.collection_lists` | The `collection_lists` and `collection_lists_exclude` fields on `targeting.json` and `targeting-input.json`, and the matching `overlay_support` / `required_overlay_support` keys with `max_references` ([#7834](https://github.com/adcontextprotocol/adcp/issues/7834)). See [Combining several collection lists](/docs/governance/collection/index#combining-several-collection-lists-experimental). | One buyer-side adopter so far, and the WG has not ratified the intersection/union semantics or the `max_references` shape. The singular `collection_list` fields are stable and unchanged. |
| `signing.web_bot_auth` | The [Web Bot Auth request-signing profile](/docs/building/by-layer/L1/wba-profile): the `web-bot-auth` value in `request_signing.profiles` and `webhook_signing.profiles` on [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities), and `signing_profile` on every webhook registration, adopted by DR-0023 | The profile follows an IETF draft that is still changing. The draft revision it pins and the `Signature-Agent` form may change before graduation. |
| `media_buy.offline_delivery_metrics` | The `ooh_metrics` delivery block on `core/delivery-metrics.json` (panels, posting periods, posting records, share of voice, modeled `estimated_impressions` with `estimation_basis`; added in 3.2 and documented in [Out-of-home](/docs/creative/channels/ooh)), and the `print_metrics` delivery block (`page_delivered`, `position_delivered`, `circulation_delivered`, `circulation_basis`, `evidence`; added in 3.3 and documented in [Print creative](/docs/creative/channels/print#delivery-evidence-and-circulation)). Both carry `x-status: experimental`, both are addressable as `ooh_metrics` / `print_metrics` in the `available-metric` enum, and both reuse the channel-neutral `core/placement-evidence.json` artifact. | Delivery reporting for channels with no play or impression event — static OOH posting records and print proof-of-insertion with circulation — rests on one named adopter per channel and on contract conventions (OAAA proof of performance, tearsheets, circulation audits) that have not been field-tested across parties. `ooh_metrics` shipped in 3.2 without a registry row; this row registers it with `print_metrics` as a clarification, so a seller on 3.3 that reports either block declares the id. A seller on a 3.2 schema that already reports `ooh_metrics` is not made non-conformant retroactively. Field shapes, the `estimation_basis` / `circulation_basis` tier vocabularies, and the shared evidence artifact may change before they freeze. |
| `media_buy.dooh_impression_basis` | The `enums/impression-estimation-basis.json` tier enum (`currency_measured`, `seller_modeled`, `sensor_measured`, `hybrid`); on DOOH delivery rows of `core/delivery-metrics.json`, `dooh_metrics.impression_basis`, `audience_multiplier`, `basis_metric` and `impression_basis_breakdown[]` (`core/impression-basis-breakdown-entry.json`), and `impression_basis` / `plays` on `venue_breakdown[]` rows; the same declaration and planning multiplier on `core/forecast-point.json` and `core/canonical-forecast-point.json`; and the planned `impression_basis` / `audience_multiplier` in the product and canonical `dooh_placement_attributes` ([RFC #7253](https://github.com/adcontextprotocol/adcp/issues/7253)). See [Impression basis](/docs/creative/channels/dooh#impression-basis-experimental). | Tells a buyer what kind of number a DOOH `impressions` figure is (`plays × audience multiplier`). One production adopter so far, whose network mixes sensor-measured and seller-modeled screens. Decided in the working-group brief on #7253: `hybrid` is a seller model calibrated by sensors on the seller's own screens, never a currency and never a mix of tiers; a row mixing tiers reports a breakdown of at least two distinct tiers, never beside a row-level tier; the multiplier is SHOULD on `sensor_measured` and `hybrid` rows, optional on `currency_measured` ones. `impression_basis` becomes required for the `sales-dooh` claim in 4.0. `ooh_metrics.estimation_basis` keeps its inline two-value enum. `list_products` and the proposal tasks carry the forecast fields through the canonical forecast point. |
| `account.invoice_lines` | The optional `lines[]`, `invoice_kind` (`enums/invoice-kind.json`), and `adjusts_invoice_id` on `invoices[]` items of [`get_account_financials`](/docs/accounts/tasks/get_account_financials), and the `core/invoice-line.json` shape ([#8184](https://github.com/adcontextprotocol/adcp/issues/8184)) | Ties each invoice amount to the media buys, packages, official reporting revisions, and reporting adjustments it bills, so a buyer can reconcile what it was charged for against what was finalized. Reference only: it never creates, approves, or settles invoices. Single-adopter so far, and the ids it references come from `media_buy.reporting_delivery`. May change: itemised `lines[]` keyed to `reporting_revision_ids`, credit notes as `invoice_kind: credit_note` with a non-negative `amount` rather than a negative amount. The line shape is reusable so a later account-change-feed invoice notification can carry `lines` unchanged. |
| `signals.pricing_groups` | The optional `pricing_group` field on the shared signal-listing fields (`get_signals` results and `Product.signal_targeting_options[]`), and `signal_pricing_group_rules[]` (schema: `core/signal-pricing-group-rule.json`) on `signal_targeting_rules` and the `get_signals` response (#7898) | Defines how fees of signals sharing a pricing group combine, a new commercial rule backed so far by one adopter (one adopter applies `highest` today as a platform default). Decided 2026-10-24 for 3.3 beta.1 ([#7898](https://github.com/adcontextprotocol/adcp/issues/7898)): a group with no rule is charged `each`, and `percent_of_media` is always `each` (no conversion rule). The `signal_charges[]` echo of per-signal charges on package state is a follow-up, so buyers reconcile against the published rules for now. |

Expand Down
Loading
Loading