diff --git a/.changeset/add-tracker-execution-contracts.md b/.changeset/add-tracker-execution-contracts.md new file mode 100644 index 0000000000..0e06a2bdb9 --- /dev/null +++ b/.changeset/add-tracker-execution-contracts.md @@ -0,0 +1,9 @@ +--- +"adcontextprotocol": minor +--- + +Add format-scoped production tracker execution contracts for first-class pixel, +VAST, and DAAST tracker assets. Pin effective commitments, execution versions, +placement scope, and digests in immutable package format snapshots so buyers can +distinguish supported, unsupported, and undeclared tracker behavior before +spend without coupling the production promise to preview observation. diff --git a/docs/contributing/x-entity-annotation.md b/docs/contributing/x-entity-annotation.md index 75e7ef075d..79a5784f25 100644 --- a/docs/contributing/x-entity-annotation.md +++ b/docs/contributing/x-entity-annotation.md @@ -106,7 +106,7 @@ High-level groupings (see the registry for full descriptions). *Categories below | Brand & rights | `advertiser_brand`, `rights_holder_brand`, `rights_grant` | | Account & party | `account`, `operator` | | Media buy | `media_buy`, `package`, `product`, `proposal`, `product_pricing_option`, `spot_airing` | -| Creative | `creative`, `creative_revision`, `creative_representation`, `macro_declaration`, `creative_locale_variant`, `creative_format`, `build_variant`, `served_variant` | +| Creative | `creative`, `creative_revision`, `creative_representation`, `macro_declaration`, `tracker_execution_selector`, `creative_locale_variant`, `creative_format`, `build_variant`, `served_variant` | | Data & targeting | `audience`, `audience_evidence`, `audience_evidence_snapshot`, `signal`, `signal_activation_id`, `demographic_interval_id`, `event_source` | | Lists & catalogs | `collection_list`, `property_list`, `catalog`, `catalog_generation`, `catalog_item`, `property` | | Plans & governance | `media_plan`, `governance_plan`, `governance_registry_policy`, `governance_inline_policy`, `governance_check`, `governance_delivery_statement`, `governance_delivery_observation`, `governance_outcome`, `governance_adjustment`, `governance_adjustment_evidence`, `seller_adjustment`, `content_standards`, `task`, `attestation_credential` | diff --git a/docs/creative/asset-types.mdx b/docs/creative/asset-types.mdx index 90b4706ca2..e0ec4340f6 100644 --- a/docs/creative/asset-types.mdx +++ b/docs/creative/asset-types.mdx @@ -34,7 +34,7 @@ The full set of asset types valid in a v2 format `slots` declaration's `asset_ty | `zip` | Zip archive (HTML5 banner bundle) | `/schemas/core/assets/zip-asset.json` | | `vast_tracker` | Single VAST `Tracking` event URL (decomposed) | `/schemas/core/assets/vast-tracker-asset.json` | | `daast_tracker` | Single DAAST `Tracking` event URL (decomposed) | `/schemas/core/assets/daast-tracker-asset.json` | -| `pixel_tracker` | Renderer-fired HTTP tracker (image pixel or JS include) for any web-rendered canonical. `event` (impression / viewable_mrc_* / viewable_video_50 / audible_video_complete / click / custom) × `method` (img / js). Maps to IAB OpenRTB Native 1.2 `imptrackers[]` / `jstracker` / `eventtrackers[]` / `link.clicktrackers[]` event-type registry (types 1, 2, 3, 4, 500) | `/schemas/core/assets/pixel-tracker-asset.json` | +| `pixel_tracker` | Renderer-fired HTTP tracker (image pixel or JS include) for any web-rendered canonical. `event` (impression / viewable_mrc_* / viewable_video_50 / audible_video_complete / click / custom) × `method` (img / js). Maps to IAB OpenRTB Native 1.2 `imptrackers[]` / `jstracker` / `eventtrackers[]` / `link.clicktrackers[]`; standardized event types 1-4 are reused, while audible completion is an AdCP-defined event and `custom` can carry exchange/vendor extensions | `/schemas/core/assets/pixel-tracker-asset.json` | | `object` | Structured object (image_carousel `cards`, `video_brief` for generative video) — sub-shape declared by the canonical | (no standalone schema; per-canonical sub-shape) | In a v2 manifest's `assets` map, the **slot key** is the canonical's `asset_group_id` (e.g., `image_main`, `video_main`, `script`, `cards`, `landing_page_url`) and the **value** carries the matching asset payload with its `asset_type` discriminator. The format declaration's `slots[].asset_type` tells the validator which payload schema applies. @@ -335,7 +335,7 @@ VAST (Video Ad Serving Template) tags for third-party video ad serving. - `tracking_events`: Array of supported tracking events. Valid values are defined by the [VAST Tracking Event](https://adcontextprotocol.org/schemas/v3/enums/vast-tracking-event.json) enum. Aligned to the IAB VAST 4.2 XSD `TrackingEvents_type/Tracking/@event` enumeration (vast_4.2.xsd lines 112–136), plus AdCP-flattened representations of `Impression`, `Error`, `VideoClicks`, and `ViewableImpression` elements: - **Playback**: `impression` (billing event), `creativeView`, `loaded`, `start`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete` - **Interaction**: `mute`, `unmute`, `pause`, `resume`, `rewind`, `skip`, `playerExpand`, `playerCollapse`, `fullscreen` (VAST 2.x/3.x compat), `exitFullscreen` (VAST 2.x/3.x compat), `otherAdInteraction`, `interactiveStart` (SIMID) - - **Non-linear / companion**: `acceptInvitation`, `adExpand`, `adCollapse`, `minimize`, `overlayViewDuration` + - **Non-linear**: `acceptInvitation`, `adExpand`, `adCollapse`, `minimize`, `overlayViewDuration` - **Progress**: `progress` (for custom progress points via VAST `offset` attribute) - **Click & close**: `clickTracking`, `customClick`, `close`, `closeLinear` - **Verification**: `viewable`, `notViewable`, `viewUndetermined`, `measurableImpression` (AdCP extension), `viewableImpression` @@ -373,8 +373,8 @@ A single URL bound to a VAST `TrackingEvents` event. Use this when the creative **Properties:** - `vast_event`: The event this URL fires on. Any VAST tracking-event enum value **except** `impression`, `clickTracking`, `customClick`, `error`, or any of `viewable` / `notViewable` / `viewUndetermined` / `measurableImpression` / `viewableImpression` — those live in dedicated VAST elements (`Impression`, `VideoClicks`, `Error`, `ViewableImpression`), not under `TrackingEvents` (see Tracker routing normative rule below). Common values: `start`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete`, `pause`, `resume`, `mute`, `unmute`, `skip`, `progress`. - `url`: Tracker URL. Supports [AdCP universal macros](/docs/creative/universal-macros). -- `offset`: Required for `vast_event: "progress"`. VAST 4.2 offset format (`Tracking@offset`): `HH:MM:SS` or `HH:MM:SS.mmm` (two-digit hours, minutes 00–59, seconds 00–59, exactly 3 fractional digits when present) for absolute time, or an integer percentage 0–100 suffixed with `%`. Negative offsets are NOT permitted — the VAST 4.2 XSD pattern does not allow a leading minus. -- `target`: Which VAST creative element scopes this tracker — `linear` (default), `non_linear`, or `companion`. VAST 4.2 places `` under three different parents (``, ``, `/`) with different valid event sets — e.g., `acceptInvitation` is meaningful on `non_linear`/`companion`, `closeLinear` only on `linear`. Sales agents read this to place the tracker correctly during VAST assembly. +- `offset`: Required for `vast_event: "progress"`. On other events it is ignored for compatibility with existing 3.x manifests and removed before tracker-contract matching. VAST 4.2 offset format (`Tracking@offset`): `HH:MM:SS` or `HH:MM:SS.mmm` (two-digit hours, minutes 00–59, seconds 00–59, exactly 3 fractional digits when present) for absolute time, or an integer percentage 0–100 suffixed with `%`. Negative offsets are NOT permitted — the VAST 4.2 XSD pattern does not allow a leading minus. +- `target`: Which VAST creative element scopes this tracker — `linear` (default), `non_linear`, or `companion`. Existing 3.x manifests remain structurally permissive. When a product declares a tracker execution contract, matching applies the closed standards matrix: `acceptInvitation` is non-linear, `creativeView` is the only companion event, and `closeLinear` is linear. Sales agents read this to place the tracker correctly during VAST assembly. **Target with non-linear event:** ```json @@ -451,8 +451,8 @@ Audio-side analogue of `vast_tracker`: a single URL bound to a DAAST `TrackingEv **Properties:** - `daast_event`: Any DAAST tracking-event enum value **except** `impression`, `clickTracking`, `customClick`, `error`, or any of `viewable` / `notViewable` / `viewUndetermined` / `measurableImpression` / `viewableImpression` (same element-routing rule as `vast_tracker` — those values belong in `Impression` / `` / `Error` / AdCP-extension verification slots, not `TrackingEvents`). Common values: `start`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete`, `pause`, `resume`, `mute`, `unmute`, `rewind`, `skip`, `progress`. - `url`: Tracker URL. Supports AdCP universal macros. -- `offset`: Required for `daast_event: "progress"` (DAAST 1.1 §3.2.4.3). Same format as VAST 4.2 `Tracking@offset`. Negative offsets are NOT permitted. -- `target`: Which DAAST creative element scopes this tracker — `linear` (default, DAAST 1.1 §3.2.1.7) or `companion` (DAAST 1.1 §3.2.2.7, where the only valid event is `creativeView`). DAAST has no `` element — audio is linear or accompanied by a visual companion. +- `offset`: Required for `daast_event: "progress"` (DAAST 1.1 §3.2.4.3). On other events it is ignored for compatibility with existing 3.x manifests and removed before tracker-contract matching. Same format as VAST 4.2 `Tracking@offset`. Negative offsets are NOT permitted. +- `target`: Which DAAST creative element scopes this tracker — `linear` (default, DAAST 1.1 §3.2.1.7) or `companion` (DAAST 1.1 §3.2.2.7). Existing 3.x manifests remain structurally permissive; a tracker execution contract restricts companion matching to `creativeView`. DAAST has no `` element — audio is linear or accompanied by a visual companion. ### Pixel Tracker Asset @@ -469,10 +469,10 @@ Renderer-fired HTTP tracker — image pixel or JavaScript include — bound to a ``` **Properties:** -- `event`: `impression` | `viewable_mrc_50` | `viewable_mrc_100` | `viewable_video_50` | `audible_video_complete` | `click` | `custom`. Event enum mirrors IAB OpenRTB Native 1.2 event-type registry (types 1, 2, 3, 4, 500). `audible_video_complete` is distinct from `viewable_video_50` — the former is full-completion with audio on; the latter is 50% pixels for ≥2 seconds with audio on. Meaningful on non-VAST video formats (Meta Reels, YouTube Shorts, TikTok Spark); VAST formats use `vast_tracker` with `vast_event: complete` instead. +- `event`: `impression` | `viewable_mrc_50` | `viewable_mrc_100` | `viewable_video_50` | `audible_video_complete` | `click` | `custom`. The first four measurement values map to IAB OpenRTB Native 1.2 event types 1-4. Native type 4 is 50% pixels for at least two seconds and does not require audio. `audible_video_complete` is a distinct AdCP-defined full-completion event with audio on; Native leaves event types 500+ exchange-specific rather than assigning this event a standard numeric type. These video events are meaningful on non-VAST video formats; VAST formats use `vast_tracker` with `vast_event: complete` and separate audible measurement where needed. - `method`: `img` (fired as `` pixel) or `js` (fired as `