RFC: add time-based video view metrics (time_based_views) to delivery reporting

[pkras]

Problem

Delivery reporting exposes video completion only on a completion-percentage basis (quartile_data.q1_views–q4_views = 25/50/75/100%). But a large class of video inventory reports "views" on a time basis, not a completion basis:

• Meta — 2-second view
• TikTok / YouTube — 6-second view
• IAB video viewability standard is itself time-based — 2 continuous seconds at 50% in view

None of these are representable today, so a seller running this inventory literally cannot return its primary view metric. views is a single billable-threshold scalar and can't carry multiple time thresholds; quartile_data is percentage-based and doesn't apply.

This is not just social

The behavioral class is autoplay / skippable / scroll-away video, where a time threshold — not completion — is the native view currency. Against enums/channels.json, that spans:

• social — Meta 2s, TikTok 6s.
• olv — the biggest beneficiary after social. Its own enum description is "pre-roll, outstream, in-app video"; outstream/in-feed web video and skippable pre-roll (YouTube's 6s threshold is olv) are counted on 2s/6s views.
• display and retail_media — where they carry in-feed / in-app autoplay video (rich-media and native video, sponsored in-feed video on commerce apps). Same behavior.

Explicitly not a CTV/cinema metric. ctv, cinema, and largely gaming are lean-back, full-screen, sound-on, mostly non-skippable — completion (quartiles / completion rate) is the right currency there and time_based_views adds little. This RFC does not propose it as their primary view metric.

Proposed change (additive, backward-compatible)

Add a declarative array to core/delivery-metrics.json rather than hardcoding platform thresholds:

"time_based_views": {
  "type": "array",
  "description": "Time-based video view counts. Each entry reports views that met a continuous in-view duration threshold, rather than a completion-percentage threshold (percentage-based completion is quartile_data). 2 and 6 are RECOMMENDED cross-platform standards (Meta 2s / IAB viewable minimum; TikTok & YouTube 6s); any publisher-defined threshold is permitted. At most one entry per threshold_seconds.",
  "items": {
    "type": "object",
    "properties": {
      "threshold_seconds": { "type": "number", "exclusiveMinimum": 0 },
      "views": { "type": "number", "minimum": 0 }
    },
    "required": ["threshold_seconds", "views"]
  }
}

Add time_based_views to the enums/available-metric.json enum so sellers declare support, exactly like every other capability-gated delivery metric (quartile_data, viewability, dooh_metrics already set the precedent for object/array-shaped declared metrics).

Why an array over discrete views_2s / views_6s fields: time thresholds are open-ended and platform-specific — a fixed-shape pair hardcodes today's platforms and forces a schema PR for every new threshold. The array is future-proof. Trade-off: like quartile_data, the array is not sortable/breakdownable (only flat numeric fields are in sort-metric.json). If per-threshold sorting ever becomes a hard requirement, targeted flat fields can be added then.

Backward compatibility: purely additive. quartile_data unchanged; all new fields optional and capability-gated.

Open questions for maintainers

1. threshold_seconds — open numeric (RECOMMEND 2/6 in prose) or constrained to a recommended set (2/6/15/30)? Leaning open-numeric.
2. number vs integer for threshold_seconds? (number keeps sub-second thresholds open and matches viewability.viewed_seconds.)
3. Duplicate-threshold handling: draft-07 uniqueItems compares whole objects, so it can't enforce one-entry-per-threshold. Enforce via normative prose ("buyers MAY treat duplicates as a seller conformance bug"), like the vendor_metric_values dedup rule?
4. Audio analog: the same pattern (count an engagement at N continuous seconds) generalizes to audio — the classic ~30s stream/"play" qualification, verified listen vs. raw download — but "views" is the wrong word for streaming_audio / podcast / radio. Keep this video-only and add a separate audio concept later, or generalize now to a channel-neutral "time-based engagements" shape? Leaning video-only to keep the term honest.

Prior art

IAB Viewable Video (50% pixels / 2 continuous seconds); existing viewability.viewed_seconds + viewability.standard are the in-repo precedent for time/threshold-governed view metrics.

Split from a broader proposal; the individually-addressable-quartiles half is a separate RFC.

[pkras]

Split companion: #6431 (first-class / individually-addressable quartiles). This issue is the additive, uncontroversial half and is the priority.

[bokelley]

Triage

Classification: Feature request (RFC)
Bucket(s): spec / protocol, media-buy
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Gap is real; array shape fits existing schema patterns (by_event_type[], by_action_source[]); vendor_metric_values is wrong path (IAB/MRC 2s and 6s thresholds are industry-standard, not vendor-specific, and routing them through the vendor envelope breaks cross-seller aggregation). Blocker: the relationship between time_based_views[N].views and completed_views is unspecified when optimization-goal.view_duration_seconds = N — normative prose must define this. Recommends integer + constrained enum [2, 6, 15, 30] + ext over open number to protect cross-seller aggregation. Ships minor on main (not a 3.1.x patch).
• adtech-product-expert: Confirms the gap; vendor_metric_values destroys inter-platform comparability so standardization is warranted. Blocker: without a billing-anchor signal buyer agents can't identify which array entry corresponds to the billing threshold — suggests a primary: true flag per entry or a primary_view_seconds companion scalar. Notes the near-term realistic adopters are premium OLV sellers (managed programmatic video), not walled-garden social platforms. Prioritizing this over RFC: make video completion quartiles individually addressable (quartile_25..100) #6431 is correct. Raises streaming audio (Spotify/Pandora 15s listen) as structurally identical — RFC should explicitly exclude it to avoid immediate follow-ups.

My take: Both experts agree the direction is correct and the gap is real; the two blockers converge on the same need — buyers must be able to identify the billing threshold within the array. Two design questions require WG votes before implementation.

---

Decision memo (proposed — pre-ratification)

id: DR-[TBD]
title: time_based_views delivers per-threshold video view counts as an optional capability-gated array in delivery-metrics
class: normative
status: proposed
date: 2026-08-12
refs: ["#6430"]
dissent: none recorded

Ruling: Add time_based_views (optional array, items: {threshold_seconds, views}) to core/delivery-metrics.json and add time_based_views to enums/available-metric.json. Field is video-scoped; streaming_audio / podcast / radio are explicitly excluded and may follow as a separate RFC. Ships as minor on main (→ 3.2.0-beta.N). Two design questions (below) require WG decision before the implementation PR opens.

Rationale: optimization-goal.view_duration_seconds lets a buyer declare a 2s or 6s view threshold, but the delivery-reporting side has no counterpart for per-threshold view counts. views is a single billing scalar; quartile_data is completion-percentage-based; vendor_metric_values requires vendor-specific metric IDs that break cross-seller aggregation. Array shape follows existing multi-value metric precedent in the schema.

Implications: Non-breaking and additive. quartile_data and completed_views are unchanged. Implementations that do not support the capability omit it from available_metrics and the delivery response.

---

WG vote required — Q1/Q2: threshold_seconds type and range

Option A — Open number (RFC author's lean):

// allows any positive value; sub-second and future thresholds without schema PR
"time_based_views": [
  { "threshold_seconds": 2, "views": 14200000 },
  { "threshold_seconds": 6, "views": 8300000 }
]

Risk: unbounded values fragment cross-seller aggregation (seller A reports 2.0, seller B reports 2; map matching becomes heuristic).

Option B — Constrained integer enum [2, 6, 15, 30] + ext (protocol expert lean):

// threshold_seconds: integer, enum [2, 6, 15, 30]; ext available for non-standard values
"time_based_views": [
  { "threshold_seconds": 2, "views": 14200000 },
  { "threshold_seconds": 6, "views": 8300000, "ext": { "label": "TikTok 6s" } }
]

Forces conformant sellers onto the same bucket labels so buyers can aggregate across sellers without heuristics. New standardized thresholds require a schema PR (minor cost).

---

WG vote required — Q3: billing-threshold anchor

Option C — Normative prose alignment, no schema change (protocol expert lean):

When a package's optimization-goal.view_duration_seconds = N, time_based_views[threshold_seconds=N].views MUST equal completed_views.

Self-consistent with existing normative-prose dedup patterns (vendor_metric_values). Requires buyers to join back to the package's optimization goal to find the billing row.

Option D — primary: true flag in array items (product expert lean):

"time_based_views": [
  { "threshold_seconds": 2, "views": 14200000, "primary": true },
  { "threshold_seconds": 6, "views": 8300000 }
]

Self-describing for buyer agents reading a delivery row in isolation. Adds a field + normative prose ("exactly one entry SHOULD carry primary: true when the package is CPV-billed at a time threshold").

---

Q4 (dedup via normative MUST prose) and Q5 (video-only scope) are settled by expert convergence: prose rule "Each threshold_seconds value MUST appear at most once" and video-only with explicit streaming-audio exclusion in the field description.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_019cXuVSHz64tLL98Fzc8pCH

---

Generated by Claude Code

[bokelley]

Implementation is open: PR #6621 (stacked on #6618). Two changes versus this RFC's proposed shape, both resolving its open questions: (1) each entry now carries a required basis discriminator (play_time | in_view, new view-threshold-basis enum) — Meta's 2-second view is play-time while IAB/MRC viewable video is in-view time, and collapsing them onto one threshold axis would have baked in cross-platform incomparability; (2) threshold_seconds stays open-numeric with 2/6 RECOMMENDED (question 1), duplicate handling is normative prose per the vendor_metric_values pattern (question 3), and audio stays out for now — but the basis enum is extensible, so an audible-playback basis can ship later without reshaping the array (question 4).