[theoplayer-bot]

This PR contains the Web API reference for OptiView Ads SDK version 1.2.1.

[theoplayer-bot]

Documentation preview
🚀 View preview at https://docs-preview.optiview.dolby.com/pr-936/
Deployed from commit e8980bb at 2026-10-23 13:57 UTC.

[MaartenRimaux]

Automated review (Devin pr-review: Claude Fable, Gemini Argon, GPT Astra) of e09a621

documentation#936 — OptiView Ads SDK 1.2.1 Verdict: REQUEST CHANGES (light — one small commit on this branch; the generated drop itself is sound)
Bot-generated replacement of ads/static/ads/v2/api-reference/ for SDK 1.2.1 (4,327 files; first drop since 1.0.0, so it carries the 1.1.0–1.2.1 API delta and the first Roku reference). The generated output is faithful and consistent: all five landing pages say 1.2.1, every authored deep link into the reference still resolves, 0 broken internal links in the web (4,215 hrefs) and React Native (2,816) trees, the 10 deleted DocC pages are superseded initializer signatures with replacements, and no local paths/credentials leaked. What is missing is the authored-docs side for the new Roku platform; two further content gaps are upstream SDK issues that this PR merely mirrors.

Blockers / Should-fix (confirmed)

1. [SHOULD-FIX] New Roku API reference is unreachable and contradicted by authored docs — roku/index.html is new, but ads/api/index.mdx#L37-L40 and sidebarsAds.ts#L99-L123 list only Web/Android/iOS/React Native; optiview-ads-sdk/index.mdx#L14 says the SDK is "available for Web, Android, iOS, and React Native", and google/dai.mdx#L14 / workflow-integration.md#L44 still say Roku "cannot run the server-guided flow" / "a client-side SDK is not an option", while the new page documents client-side GAM pod stitching (SGAI) on Roku and the 1.2.1 changelog makes Roku non-experimental. Fix: add a Roku bullet + sidebar link to pathname:///ads/v2/api-reference/roku/ and update the three sentences, as a commit on this branch (precedent: Preview — OptiView Ads SDK API reference 1.0.0-beta.6 (feature/ADS-465-api-docs-preview) #866 and OptiView Ads SDK 1.0.0 #878 updated ads/api/index.mdx and sidebarsAds.ts on the bot's release branch). (Fable, Gemini, Astra)
2. [SHOULD-FIX, upstream dolby-ads-sdk] Web/React Native references show new 1.2.x public types as unlinked text with no page — web/interfaces/Targeting.html#L37-L43 (Os, OsVersionRange, Platform — the OS/platform targeting feature incl. vizio/xbox values has no documented value set), web/classes/OptiViewAds.html#L120-L135 (getExternalVendorConfiguration() returns an undocumented ExternalVendorConfiguration), web/types/OptiViewAdsEventMap.html#L86 (ExternalVendorConfigurationChangeEvent), web/types/VendorConfiguration.html#L13 (ExternalVendorConfigurationEntry); RN: OptiViewAdsReactNativeConfig.html#L203 (LiveStartPushbackConfig), OptiViewAdsConnector.html#L24 (ExternalVendorConfiguration). The player-free OptiViewAdsExternalVendors class (shown in the SDK README as import { OptiViewAdsExternalVendors } from '@dolby-optiview/ads-sdk') has no web page at all. Root cause verified at SDK v1.2.1 (origin/main 2105695a0): @dolby-optiview/ads-sdk does export * from '@dolby-optiview/ads-sdk-core', but the TypeDoc entry point packages/sdk/src/public-api.ts omits Os, Platform, OsVersionRange, ExternalVendorConfiguration, OptiViewAdsExternalVendors(Config); react-native/src/public-api.ts omits ExternalVendorConfiguration and LiveStartPushbackConfig; ExternalVendorConfigurationChangeEvent/ExternalVendorConfigurationEntry are not exported from packages/core/src/index.ts. Fix: SDK ticket to add those exports, then re-publish web + RN to this branch (API_DOCS_PLATFORMS="web react-native" scripts/ci-publish-api-docs.sh publish …). Not fixable in this repo; does not block merging. (Fable, Gemini, Astra)
3. [SHOULD-FIX, upstream dolby-ads-sdk] Android and iOS TransitionConfig / TransitionType.FADE pages describe behaviour removed in 1.2.0 — android …/-transition-config/index.html#L96 and -transition-type/-f-a-d-e/index.html#L96 say "The default is a 300ms cross-fade" / "Content and ad cross-fade into each other (the default)"; the iOS DocC transitionconfig.json and transitiontype/fade.json carry the same text. The 1.2.0 changelog says "The switch between content and an ad is now a cut on web, Android, iOS and tvOS: no cross-fade in or out; the transition setting only times the two-box layout reflow", and the v1.2.1 Android runtime (OverlayAdReveal.kt:7-9) states "The content <-> ad switch is a cut, never a fade". The stale text is the KDoc in android/ads-sdk/src/main/kotlin/com/dolby/optiview/ads/sdk/OptiViewAdsConfig.kt:157-184 (and the Swift counterpart). Fix upstream, then regenerate. (Astra; iOS extent found during verification)

Nits

• AdBreakSkippedEvent (new in 1.2.0) is summarised as "Base event interface." with undocumented break/reason/format — web/interfaces/AdBreakSkippedEvent.html#L14, react-native/…/AdBreakSkippedEvent.html#L14; the interface in SDK packages/core/src/types/Events.ts:24 has no doc comment so TypeDoc inherits the parent's. Upstream. (Fable, Gemini)
• Dokka pages link to non-existent --root--.html for KDoc [param] references, e.g. -ad-error-event/index.html#L96 — 43 pages at HEAD vs 42 at base, so pre-existing, not introduced here. Upstream. (Fable)
• PR body says "Web API reference" although the drop covers five platforms — template in .github/workflows/ads-sdk-release.yml#L41, not touched by this PR. (Fable)

Requirements (no Jira ticket; derived from dolby-ads-sdk/RELEASING.md)

• Reference reflects SDK 1.2.1 on web/android/ios/react-native/roku with consistent versions — met (content caveats: items 2–3). SDK origin/main is at chore(release): v1.2.1; the v1.2.1 tag was not yet present at review time, which is expected since release-finish tags after publish-api-docs.
• Authored docs link any newly added platform — missing (item 1).
• Existing authored deep links still resolve — met (all 9 targets exist at HEAD).
• No local paths / credentials in generated output — met.

Rejected reviewer claims: 0 — every finding was confirmed against the PR head and the SDK v1.2.1 sources; Astra's cross-fade finding was extended to iOS during verification.
Reviewers: Fable APPROVE WITH NITS · Gemini REQUEST CHANGES · Astra REQUEST CHANGES

[MaartenRimaux]

Automated review (Devin pr-review: Claude Fable, Gemini Argon, GPT Astra) of e8980bb

documentation#936 — OptiView Ads SDK 1.2.1 Verdict: REQUEST CHANGES (light — two small edits on this branch; the generated drop and the new Roku guide are sound)
Re-review after the e09a621 review: on top of the bot's 1.2.1 regeneration of ads/static/ads/v2/api-reference/ (second bot commit 4b15be9 is an iOS-only DocC re-run — 400/400 sampled JSON files identical after key sorting), commits ccad219/e8980bb add the Roku bullet on ads/api/index.mdx#L41, the sidebar links, the two platform-list updates and a new roku.mdx guide. The guide checks out against dolby-ads-sdk v1.2.1 (roku/npm/README.md, roku/api/OptiViewAds.json, roku/sdk/components/OptiViewAds.xml, scripts/lib/roku-npm-package.mjs) and the THEOplayer getVideoNode claim against theoplayer-next/roku/src/components/THEOplayer/THEOplayer.xml:37; all 10 authored deep links into the reference resolve at HEAD; CI build + lint are green. What remains is the authored-docs consistency the earlier review asked for (four "Roku cannot" sentences untouched) and one copy-paste defect in the new snippet.

Blockers / Should-fix (confirmed — each posted as an inline comment)

1. [SHOULD-FIX] Four other authored pages still say Roku cannot run SGAI / a client-side SDK — anchored on roku.mdx:10; the stale text is at google/dai.mdx:14, google/index.mdx:13, google/index.mdx:59, workflow-integration.md:44 (Fable, Gemini, Astra)
2. [SHOULD-FIX] Integration snippet uses m.video, which is never assigned — roku.mdx:55-57 vs L77-L78; copied as-is the first ready result throws on invalid (Fable, Gemini, Astra)

Nits

• [NIT] Prerequisites: network code is organization-level, not "on the channel"; PDT/format/rendition limits are SGAI-only per the reference's capabilities — roku.mdx:16-17 (Astra; network-code part found during verification)
• [NIT] SDK overview generalisations (adapter, container, customAssetKey) no longer hold for Roku — optiview-ads-sdk/index.mdx:14 (Fable, Astra)
• [NIT] Platform-guide lists in two other pages still omit Roku — player-integration/index.mdx:12; missing in workflow-integration.md:36 and getting-started/index.mdx:85 (Fable, Gemini)

Carried over from the e09a621 review (confirmed still present at HEAD, upstream dolby-ads-sdk — not re-posted inline): web/React Native references show Os, OsVersionRange, Platform, ExternalVendorConfiguration, LiveStartPushbackConfig as unlinked text with no page (web/interfaces/Targeting.html#L37-L43); Android/iOS TransitionConfig / TransitionType.FADE still describe the 300 ms cross-fade removed in 1.2.0 (android …/-transition-config/index.html#L96); AdBreakSkippedEvent summarised as "Base event interface."; Dokka --root--.html links. Fix upstream, then regenerate. (3/3)

Requirements (no Jira ticket; derived)

• Reference reflects SDK 1.2.1 on web/android/ios/react-native/roku, nothing leaked — met (content caveats: carried-over upstream items)
• Authored deep links into the reference resolve — met (10/10)
• New Roku platform reachable from the authored docs — met (API page, sidebar, SDK overview, player-integration overview)
• roku.mdx factually correct against the SDK and in sibling structure — met, with items 2 and the prerequisites nit
• Build + spellcheck — met (CI green at e8980bb; ropm added to the dictionary; brightscript is a registered Prism language)
• Other Roku-mentioning pages consistent with the guide — missing (item 1, nit 3)

Rejected reviewer claims: 0 — every finding was confirmed against the PR head, the SDK v1.2.1 sources and the THEOplayer Roku SDK; severities were re-graded (the m.video snippet to SHOULD-FIX, the overview and prerequisite points to NIT).
Reviewers: Fable REQUEST CHANGES (light) · Gemini REQUEST CHANGES · Astra REQUEST CHANGES

[MaartenRimaux]

[SHOULD-FIX] Four other authored pages still say Roku cannot run SGAI / a client-side SDK

This bullet documents client-side Google Ad Manager pod stitching (SGAI) on Roku, and the SDK 1.2.1 changelog makes the Roku SDK non-experimental — but four sentences elsewhere in ads/ still tell readers the opposite, and none of those files is in this PR:

• ads/integrations/google/dai.mdx:14 — "Use Google DAI for platforms that cannot run the server-guided Google Pod Serving flow — such as Roku and older connected TV devices."
• ads/integrations/google/index.mdx:13 — "Use this for platforms that cannot run the server-guided flow, such as Roku and older connected TV devices."
• ads/integrations/google/index.mdx:59 — "Server-side insertion for platforms without server-guided support, such as Roku and older CTV devices."
• ads/how-to-guides/workflow-integration.md:44 — "For platforms where a client-side SDK is not an option — such as Roku or older connected TV devices — OptiView Ads also supports server-side ad insertion (SSAI) through Google DAI."

Scenario: a Roku developer reading the Google integration or workflow guide is steered to Google DAI only, then lands on this page, which says the SDK stitches GAM pods client-side on Roku. This was flagged on e09a621 too; commits ccad219/e8980bb fixed the API-reference page, the sidebar and two platform lists, but not these sentences.

Fix: drop Roku from the "cannot" examples in all four sentences (e.g. "such as older connected TV devices without an OptiView Ads SDK"); optionally add that on Roku the SDK itself follows the Break Manifest's delivery rule and plays the Google DAI stream when SSAI is selected, as line 11 here already says.

[MaartenRimaux]

[SHOULD-FIX] Integration snippet uses m.video, which is never assigned

The OnAdsOperation handler below (lines 77–78) does m.video.content = content / m.video.control = "play", but this setup snippet only binds m.ads.videoNode = m.top.FindNode("video") and never assigns m.video. Copied as-is into a component with <Video id="video" />, m.video is invalid and the first status = "ready" result throws Dot Operator attempted with invalid BrightScript Component or interface reference instead of starting playback. The SDK's own test app keeps the node in a variable and binds that (roku/test-app/components/SdkTestTheo.brs:41,51 at dolby-ads-sdk v1.2.1).

Suggested change

	m.ads = CreateObject("roSGNode", "OptiViewAds")
	m.top.AppendChild(m.ads)
	m.ads.videoNode = m.top.FindNode("video")
	m.video = m.top.FindNode("video")
	m.ads = CreateObject("roSGNode", "OptiViewAds")
	m.top.AppendChild(m.ads)
	m.ads.videoNode = m.video

[MaartenRimaux]

[NIT] Prerequisites: network code is organization-level; PDT/format/rendition limits are SGAI-only

Two precision issues in the prerequisites:

• Line 16 says to configure the networkCode "on the channel". Per ads/integrations/google/index.mdx:19-23 the network code is organization-level (set up by the account team); only the custom asset key is configured on the channel (pod-serving.mdx:52-54), after which the Break Manifest carries both — which is what the Roku SDK reads (roku/sdk/source/OptiViewAds/ManifestPolicy.brs:9 at v1.2.1).
• Line 17 states the EXT-X-PROGRAM-DATE-TIME / MPEG-TS-or-CMAF / eight-rendition requirements unconditionally, but they are stitching (SGAI) requirements: the generated Roku reference's capabilities say sourceProgramDateTimeRequired — "SGAI needs EXT-X-PROGRAM-DATE-TIME on the content" and maxRenditions: 8 — "Maximum number of renditions stitched together" (roku/index.html:226,234); when the first manifest selects SSAI the SDK discards pending stitching failures and plays the Google DAI stream (SessionSsai.brs:122-137 at v1.2.1). The clear-content (no DRM) requirement is unqualified in the capabilities, so it stays general.

Suggested change

	2. For [Google Pod Serving](../../integrations/google/pod-serving.mdx), configure the Google Ad Manager `networkCode` and `customAssetKey` on the channel. The Roku SDK reads them from the Break Manifest.
	3. The content must be clear (not DRM-protected) live HLS with `EXT-X-PROGRAM-DATE-TIME` tags, in MPEG-TS or CMAF, with up to eight renditions.
	2. For [Google Pod Serving](../../integrations/google/pod-serving.mdx), enable it on the channel by configuring the channel's `customAssetKey`. The Roku SDK reads the Google Ad Manager `networkCode` and `customAssetKey` from the Break Manifest.
	3. The content must be clear (not DRM-protected) live HLS. For client-side stitching (SGAI) it also needs `EXT-X-PROGRAM-DATE-TIME` tags, MPEG-TS or CMAF segments, and at most eight renditions.

[MaartenRimaux]

[NIT] SDK overview generalisations (adapter, container, customAssetKey) no longer hold for Roku

With Roku added to this list, the rest of the page still speaks for every platform: line 11 "renders the scheduled ads, including the different break layouts, on top of your content player" (on Roku the ads replace content in-stream and there are no layouts), line 18 "All player interaction goes through a small player adapter interface … ready-made adapters for popular players on each platform" (Roku binds a Video node; roku.mdx:8 says "Instead of a player adapter"), lines 31–32 player / container Required, and line 44 customAssetKey in the session configuration (Roku's startSession takes contentUrl / manifestUrl and reads the key from the manifest — roku/api/OptiViewAds.json startConfig at v1.2.1). A one-sentence qualifier here keeps the page accurate without rewriting it:

Suggested change

The SDK is available for [Web](./web.mdx), [Android](./android.mdx), [iOS](./ios.mdx), [React Native](./react-native.mdx), and [Roku](./roku.mdx).

The SDK is available for [Web](./web.mdx), [Android](./android.mdx), [iOS](./ios.mdx), [React Native](./react-native.mdx), and [Roku](./roku.mdx). The adapter and configuration model below applies to Web, Android, iOS, and React Native; on Roku the SDK is a SceneGraph component that binds your `Video` node directly and reads the Google configuration from the Break Manifest — see the [Roku page](./roku.mdx).

[MaartenRimaux]

[NIT] Platform-guide lists in two other pages still omit Roku

The same list update is still missing in ads/how-to-guides/workflow-integration.md:36 ("see the platform guides for Web, Android, iOS, and React Native") and ads/getting-started/index.mdx:85 ("Follow the platform guide for Web, Android, iOS, or React Native"), so the new Roku guide is not discoverable from the getting-started or workflow entry points.

Fix: add [Roku](../player-integration/optiview-ads-sdk/roku.mdx) to the workflow guide's list (relative .mdx links, like its neighbours) and [Roku](/ads/player-integration/optiview-ads-sdk/roku) to the getting-started list (absolute paths, like its neighbours).