Ads docs v2 by MaartenRimaux · Pull Request #817 · THEOplayer/documentation

MaartenRimaux · 2026-08-18T09:50:45Z

No description provided.

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

…ition Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…g to Break Manifest

- Simplify break identity, remove stored fields and internal mechanics - Rework scheduling: timebases, cued breaks, template snapshots, event preparation, constraints rationale - Rename lifecycle to Break Lifecycle with customer-facing states and diagram - Rename cue-and-punch to Break punching - Restructure break configuration: general, event based triggers, controls, layouts, variants, asset model - Add clickable layout overview with docs-colored visuals - Use regional production domains and UUIDs in examples - Align related resources tables across pages Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Reframe the page around the backend/player contract and side-loading (with a data-flow diagram), simplify the endpoint and caching text, document the 1.1.0 envelope properties, and defer break details to the Breaks page. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Simplify the intro around vendor assets, keep the supported vendors table without fan-out wording, and replace the Ads V2 model mapping with a related resources section. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…and DAI subpages Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…erving page Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…) and OptiView Player (legacy) Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

turbidwater

Still working my way through, but here's what I have so far.

turbidwater · 2026-08-18T17:00:32Z

+
+- **Breaks cannot overlap.** A scheduled break cannot overlap another break on the same channel. Players render one break at a time; overlapping breaks would make the ad timeline ambiguous for your viewers.
+- **The start cannot lie in the past.** A break must start ahead of the current live position of the channel. Players need to receive the break through the [Break Manifest](./break-manifest.mdx) before its start time; a break scheduled behind the live position would never be seen.
+- **Ad decisioning needs lead time.** Breaks delivered through an ad server integration such as [Google Ad Manager](../integrations/google/index.mdx) need a small extra margin before their start, so the ad decisioning can complete before the break begins. Scheduling closer than that margin is rejected rather than risking an empty break.


question: @MaartenRimaux do we have a recommended margin length? That would be a good thing to add here, if we do.

Good idea — the default decisioning margin is 5 seconds. Added that with a link to the decisioning margin section on the Google Ad Manager page in 84add53.

turbidwater · 2026-08-18T23:21:51Z

+
+#### Pause
+
+A `pause` break is a **pause ad**: it fires every time the viewer pauses playback and is dismissed when the viewer resumes. Use it to monetize the pause screen, typically with an image overlay. With a `delay`, the break appears after the viewer has been paused for that many seconds; resuming before the delay elapses cancels the pending break. When multiple `pause` breaks are defined, each pause shows the next one in order.


Suggested change

A `pause` break is a **pause ad**: it fires every time the viewer pauses playback and is dismissed when the viewer resumes. Use it to monetize the pause screen, typically with an image overlay. With a `delay`, the break appears after the viewer has been paused for that many seconds; resuming before the delay elapses cancels the pending break. When multiple `pause` breaks are defined, each pause shows the next one in order.

A `pause` break is a **pause ad**: it fires every time the viewer pauses playback and is dismissed when the viewer resumes. Use it to monetize the pause screen, typically with an image overlay. With a `delay`, the break appears after the viewer has been paused for that many seconds. If the viewer resumes before the delay elapses, it cancels the pending break. When multiple `pause` breaks are defined, each pause shows the next one in order.

Applied the suggestion in 84add53.

turbidwater · 2026-08-18T23:22:50Z

+
+#### End
+
+An `end` break is a **post-roll**: it fires when playback has ended, once per session. Use it to show an ad after the content finishes. With a `delay`, the break fires that many seconds after playback ended; replaying before the delay elapses cancels the pending break.


Suggested change

An `end` break is a **post-roll**: it fires when playback has ended, once per session. Use it to show an ad after the content finishes. With a `delay`, the break fires that many seconds after playback ended; replaying before the delay elapses cancels the pending break.

An `end` break is a **post-roll**: it fires when playback has ended, once per session. Use it to show an ad after the content finishes. With a `delay`, the break fires that many seconds after playback ended. Replaying the asset before the delay elapses will cancel the pending break.

Applied the suggestion in 84add53.

turbidwater · 2026-08-18T23:29:14Z

+
+![Overlay format](../assets/img/breaks/format-overlay.svg)
+
+`format: "overlay"` renders a non-linear ad on top of the content, which keeps playing. In addition to `assets`, an overlay requires a `position` and a `size`, and accepts an optional `opacity`. All values are fractions of the player surface from `0` through `1`:


question: @MaartenRimaux This doesn't seem to match with the descriptions below:
All values are fractions of the player surface from 0through1:
It sounds like it would describe the opacity value, but not related to the player surface. Does this need to be updated? The code sample doesn't match the line items.

Good catch — reworded in 84add53: the fraction-of-the-player-surface range now sits on position and size only, and opacity is described as 0 (fully transparent) through 1 (fully opaque), matching the Break Manifest spec.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

… variants, backdrops Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…l example Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…ection" This reverts commit 4f3984d.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…bleshooting Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

MaartenRimaux and others added 30 commits August 14, 2026 08:48

Version Ads docs: freeze current docs as v1, working copy becomes v2

6aa9c98

ADS-112 document Ads channels

bd48eb8

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-112 clarify channel service fallbacks

fe9c61c

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-112 use autogenerated concepts sidebar, keep Getting started first

08c307d

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-113 document ad breaks

676c9a2

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-116 document ad templates

dc9bc46

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-114 document ad events

7d868de

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-115 document marker detection

6594233

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-117 document ad vendors

a542d76

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-120 document break manifest

a05f03e

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-112..120: add Vendors category and order concepts via sidebar_pos…

f8b7cff

…ition Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-112 rework channels concept per feedback

35101c5

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-112 rephrase integrations as SSAI with Google DAI

d06e795

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-112 move related resources to end with links

1a1b5de

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-112 channels feedback round 2

b75f7fb

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-112 order related resources like sidebar

704e625

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Restructure channels doc, rename Vendors to Integrations, move pollin…

b2c876c

…g to Break Manifest

Rework templates page and align concept pages for customer-facing docs

d53bf9c

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Rework events page sections per review feedback

91b493e

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Apply origins and break detection review feedback

6531d8e

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Restructure Google Ad Manager docs into parent page with Pod Serving …

e057922

…and DAI subpages Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Remove targeting tiers section and player parameter detail from Pod S…

3d1cdb8

…erving page Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-112..117/120 Document Ads core concepts and vendors (#744)

fe4d1c7

ADS-118 document player integration

c534437

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-118 fix links after rebase onto ADS-112

d2a3c38

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-118 format pod-serving links table

bae4356

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-118 restructure player integration: OptiView Ads SDK (recommended…

154a0ea

…) and OptiView Player (legacy) Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

turbidwater reviewed Aug 18, 2026

View reviewed changes

MaartenRimaux and others added 3 commits August 19, 2026 08:44

Rework Ads introduction page and remove limitations page

9be2695

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ADS-121 rework how-to guides: workflow, impressions, assetParameters,…

271d60c

… variants, backdrops Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Remove Limitations and known issues page from v1 docs

27a4561

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot temporarily deployed to preview August 19, 2026 11:10 Inactive

devin-ai-integration Bot and others added 7 commits August 19, 2026 12:00

ADS-119 publish Ads API reference

c6626cc

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-119 make API builds self-contained

033a53f

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

ADS-119 omit excluded channel setting

e0b04a2

Co-Authored-By: maarten.rimaux <maarten.rimaux@dolby.com>

Fix merge conflict marker in _lint.yml

44a298e

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Add dispatch-triggered workflow to update the Ads API reference

88dc146

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Fetch the Ads OpenAPI spec from the public API docs endpoint

ea8d1cf

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Pin random UUID defaults so API reference regeneration is deterministic

c63f9c5

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot temporarily deployed to preview August 19, 2026 12:15 Inactive

Remove HESP from introduction diagram and simplify schedule-break cur…

41a671a

…l example Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot temporarily deployed to preview August 20, 2026 09:54 Inactive

Add OptiView Ads SDK events reference to the API references section

4f3984d

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot temporarily deployed to preview August 20, 2026 10:04 Inactive

Remove Web API reference link from the Ads API references sidebar

6ecc605

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot temporarily deployed to preview August 20, 2026 12:59 Inactive

MaartenRimaux and others added 2 commits August 21, 2026 14:36

Revert "Add OptiView Ads SDK events reference to the API references s…

b8ade7d

…ection" This reverts commit 4f3984d.

Fix formatting after SDK events revert

820a511

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot temporarily deployed to preview August 21, 2026 14:46 Inactive

MaartenRimaux and others added 2 commits August 21, 2026 15:07

Remove duplicate API version badge from the Ads API reference intro page

83ad827

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Refresh Ads API reference from the deployed contract

7e9b855

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot temporarily deployed to preview August 21, 2026 15:16 Inactive

Document service account credential error reasons in Pod Serving trou…

6590798

…bleshooting Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot temporarily deployed to preview August 21, 2026 15:31 Inactive

Address review feedback on breaks concept page

84add53

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Jeroen-Veltmans approved these changes Aug 21, 2026

View reviewed changes

devin-ai-integration Bot deployed to preview August 21, 2026 15:50 View deployment

Navigation Menu

Uh oh!

Ads docs v2 - #817

Ads docs v2#817
MaartenRimaux wants to merge 63 commits into
mainfrom
ads-docs-v2

MaartenRimaux commented Aug 18, 2026

Uh oh!

turbidwater left a comment

Uh oh!

turbidwater Aug 18, 2026

Uh oh!

devin-ai-integration Bot Aug 21, 2026

Uh oh!

turbidwater Aug 18, 2026

Uh oh!

devin-ai-integration Bot Aug 21, 2026

Uh oh!

turbidwater Aug 18, 2026

Uh oh!

devin-ai-integration Bot Aug 21, 2026

Uh oh!

turbidwater Aug 18, 2026

Uh oh!

devin-ai-integration Bot Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		#### Pause

		A `pause` break is a pause ad: it fires every time the viewer pauses playback and is dismissed when the viewer resumes. Use it to monetize the pause screen, typically with an image overlay. With a `delay`, the break appears after the viewer has been paused for that many seconds; resuming before the delay elapses cancels the pending break. When multiple `pause` breaks are defined, each pause shows the next one in order.


		#### End

		An `end` break is a post-roll: it fires when playback has ended, once per session. Use it to show an ad after the content finishes. With a `delay`, the break fires that many seconds after playback ended; replaying before the delay elapses cancels the pending break.


		![Overlay format](../assets/img/breaks/format-overlay.svg)

		`format: "overlay"` renders a non-linear ad on top of the content, which keeps playing. In addition to `assets`, an overlay requires a `position` and a `size`, and accepts an optional `opacity`. All values are fractions of the player surface from `0` through `1`:

Uh oh!

Conversation

MaartenRimaux commented Aug 18, 2026

Uh oh!

turbidwater left a comment

Choose a reason for hiding this comment

Uh oh!

turbidwater Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

turbidwater Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

turbidwater Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

turbidwater Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants