Skip to content

OptiView Ads SDK 1.6.0 - #975

Merged
MaartenRimaux merged 4 commits into
mainfrom
release/ads-sdk-1.6.0
Nov 13, 2026
Merged

MaartenRimaux merged 4 commits into
mainfrom
release/ads-sdk-1.6.0

Conversation

@theoplayer-bot

Copy link
Copy Markdown
Contributor

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

@theoplayer-bot
theoplayer-bot Bot requested a review from a team as a code owner November 12, 2026 16:04
@theoplayer-bot

This comment has been minimized.

@MaartenRimaux MaartenRimaux left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

documentation#975 — OptiView Ads SDK 1.6.0 Verdict: REQUEST CHANGES (one wording defect; otherwise safe to merge)
Bot-generated replacement of the five OptiView Ads SDK API references (web, React Native, Android, iOS, Roku) for dolby-ads-sdk v1.6.0, taking the site from 1.4.0 straight to 1.6.0 (it supersedes the still-open #961 / 1.5.0 and #962 / 1.5.1 — close those after merging). Verified against the SDK source at the tag: every spot-checked doc comment matches, 1.6.0 on every landing page and Dokka footer (the remaining 1.4.0/1.5.0 strings are manifest-spec versions), every 1.5.x/1.6.0 API delta is present, nothing outside ads/static/ads/v2/api-reference/** changes, 0 broken links/anchors across 54 174 hrefs in web/RN/Android/Roku, 0 unresolved DocC references (13 299) and 0 shell↔JSON mismatches in iOS, no : filenames; of the 2 759 "modified" iOS JSON files 2 650 are key-order re-serialisation only (parsed and compared) and 1 198 of 1 238 Android files are version-stamp bumps. The one real problem is that the new manifestUrlDiscovery text says "web and Android" on every platform, including the iOS reference, while 1.6.0's headline feature is iOS support — a 3-line upstream comment fix plus republish on this branch (as done for #946), or merge now and fix with the next publish.

Blockers / Should-fix (confirmed)

  1. [SHOULD-FIX] manifestUrlDiscovery documented as web-and-Android only; 1.6.0 added iOS — ads/static/ads/v2/api-reference/web/interfaces/OptiViewAdsConfig.html:233 (same sentence on the RN, Android and iOS pages) — contradicts the changelog and the iOS adapter (AdsManifestUrlDiscovery, THEOplayer ≥ 11.15.0); fix the three source comments in dolby-ads-sdk and republish (Fable, Gemini, Astra)

Nits (confirmed, posted inline):
2. [NIT] SessionConfig.manifestUrl omits the manifestUrlDiscovery opt-in precondition — web/interfaces/SessionConfig.html:86 (Astra, Fable)
3. [NIT] Roku OptiViewAdsInterceptor snippet references an undefined integration — roku/index.html:289 (Fable)
4. [NIT] iOS ScheduledBreak / ScheduledBreakPosition public in both Core and SDK → duplicate hash-suffixed Runtime pages, ambiguous type for import OptiViewAdsRuntime — ios/OptiViewAdsRuntime/.../scheduledbreak-6zja6.json:1 — SDK follow-up (Fable, Gemini)
5. [NIT] Android KDoc links [resolveLshapeAnchor] / [endOverlay] land on package index pages — android/ads-sdk-core/.../-break-variant/anchor.html:97 — SDK follow-up (Gemini)
6. [NIT] Core references publish new 1.6.0 internals (SlateClock, resolveSlateFill, ScheduledBreaksTracker, …) despite the SDK's hidden-symbol policy; suppressed symbols leak into a signature — android/ads-sdk-core/.../-scheduled-breaks-tracker/index.html:97 — SDK follow-up (Gemini)
7. [NIT] Hand-written guides lag the reference (manifestUrl "Required", iOS "THEOplayer 11" vs 11.15.0 + THEOlive integration, slate/anchor/pause-rotation/scrubber markers, Roku adtimeupdate/interceptor) — ads/player-integration/optiview-ads-sdk/index.mdx:59, ios.mdx:93, concepts/breaks.mdx:161, :178 — separate docs PR (Fable, Gemini, Astra)

Requirements: (1) regenerated from v1.6.0 and matching the source — met (~25 symbols per platform spot-checked across TS/Kotlin/Swift/Roku JSON; removed iOS pages are signatures that changed — slate:, anchor:, manifestUrlDiscovery:, onSlateIssue:, toBridge*(slateAsset:) — and their replacements exist); (2) 1.6.0 everywhere — met; (3) all 1.5.x/1.6.0 API deltas present (manifestUrlDiscovery/DiscoveredAdsManifestUrl/PlayerAdapter.discoveredAdsManifestUrl, optional SessionConfig.manifestUrl, LshapeAnchor/anchor, BreakManifest.slate/Slate, ScheduledBreak/getScheduledBreaks()/scheduledbreakschange, AdBreakPhase complete, Roku adtimeupdate/eventId/content-url-required/OptiViewAdsInterceptor/DA-MANIFEST-EVENT-INVALID) — met; (4) scope, links, DocC routes, filenames — met; (5) text accurate for customers — partial (finding 1; findings 2–3 are precision issues).

Uncertain: none. Not checked by anyone: the binary DocC index files (index/data.mdb, navigator.index, availability.index) and the rendered site — see the preview at https://docs-preview.optiview.dolby.com/pr-975/.

Rejected reviewer claims: 0 — all claims checked out; re-graded: Gemini's duplicate-ScheduledBreak and Astra's SessionConfig.manifestUrl SHOULD-FIXes are NITs here because the generated pages render the SDK source faithfully and the fixes live in dolby-ads-sdk.

Reviewers: Fable APPROVE WITH NITS · Gemini REQUEST CHANGES · Astra REQUEST CHANGES

Findings outside the changed lines

  • [SHOULD-FIX] manifestUrlDiscovery documented as web-and-Android only; 1.6.0 added iOS

    [SHOULD-FIX] manifestUrlDiscovery is documented as "web and Android" only, but 1.6.0 added iOS support

    Problem: The new manifestUrlDiscovery property says the discovered-URL flow applies to "THEOplayer with a THEOlive source on web and Android". The same sentence is rendered on every platform — including the iOS reference (ios/OptiViewAdsSDK/data/documentation/optiviewadssdk/optiviewadsconfig/manifesturldiscovery.json, ios/OptiViewAdsRuntime/.../manifesturldiscovery.json), React Native (react-native/interfaces/OptiViewAdsReactNativeConfig.html:221, OptiViewAdsWebConfig.html:246) and Android (android/ads-sdk/com.dolby.optiview.ads.sdk/-opti-view-ads-config/manifest-url-discovery.html:97, "Android and web"). An iOS (or RN-on-iOS) integrator reading their own reference concludes the 1.6.0 headline feature does not work on iOS.

    Evidence: dolby-ads-sdk v1.6.0 changelog: "starts THEOlive ads sessions from the player-discovered manifest URL on web, Android and iOS, with THEOplayer 11.15.0 or later required on iOS"; ios/adapter-theoplayer/Sources/OptiViewAdsAdapterTHEOplayer/THEOplayerAdapter.swift:23 conforms to AdsManifestUrlDiscovery, ios/adapter-theoplayer/Package.swift:20 pins theoplayer-sdk-apple from: "11.15.0" with THEOplayerTHEOliveIntegration, and both React Native bridges parse the flag (android/ads-sdk-react-bridge/.../BridgeConfigParsing.kt:106, ios/OptiViewAdsReactBridge/.../BridgeConfigParsing.swift:92). The generator rendered the source comments faithfully: packages/core/src/types/OptiViewAdsConfig.ts:457, ios/OptiViewAdsSDK/Sources/OptiViewAdsSDK/OptiViewAdsConfig.swift:105-106 and android/ads-sdk/src/main/kotlin/com/dolby/optiview/ads/sdk/OptiViewAdsConfig.kt:311 all still carry the pre-iOS wording.

    Fix (upstream, then republish on this branch as was done for 1.3.0 in #946): change the three doc comments to "…on web, Android and iOS (THEOplayer 11.15.0 or later on iOS)" and re-run scripts/ci-publish-api-docs.sh publish for release/ads-sdk-1.6.0. Alternatively merge as is (the site is two releases behind) and fix with the next publish — your call; this is the only confirmed defect that misstates behaviour.

    Raised by Fable, Gemini and Astra; verified by the orchestrator against the SDK source at v1.6.0.

    ads/static/ads/v2/api-reference/web/interfaces/OptiViewAdsConfig.html:233

  • [NIT] SessionConfig.manifestUrl omits the manifestUrlDiscovery opt-in precondition

    [NIT] SessionConfig.manifestUrl says omitting it uses the discovered URL, without the manifestUrlDiscovery opt-in

    Problem: "When omitted, the SDK uses the ads manifest URL the content player discovered" reads as unconditional. A reader who only opens this page and calls startSession({}) with the default config gets a rejection instead. Same text in react-native/interfaces/SessionConfig.html:86; Android (-session-config/manifest-url.html) and iOS (sessionconfig/manifesturl.json) phrase it as "Omit it … when the content player discovers the ads manifest URL itself" — also without the flag.

    Evidence: packages/core/src/session/DiscoveredManifestUrl.ts:51-56 at v1.6.0 throws DA-MANIFEST-URL-UNAVAILABLE with reason: 'disabled' whenever manifestUrlDiscovery is off, even if the adapter already reports an available URL (packages/core/src/__tests__/OptiViewAds.discovery.test.ts:357-367). The precondition is only stated on the OptiViewAdsConfig.manifestUrlDiscovery page.

    Fix (upstream, same follow-up as the manifestUrlDiscovery wording): "When omitted and manifestUrlDiscovery is enabled, the SDK uses …" in packages/core/src/types/OptiViewAdsConfig.ts:525, OptiViewAdsConfig.kt:390 and OptiViewAdsConfig.swift:189.

    Raised by Astra and Fable; verified by the orchestrator.

    ads/static/ads/v2/api-reference/web/interfaces/SessionConfig.html:86

  • [NIT] Roku OptiViewAdsInterceptor snippet references an undefined integration

    [NIT] Roku OptiViewAds:OptiViewAdsInterceptor usage snippet references an undefined integration

    Problem: The new snippet ends with ssai: { integration: integration.integrationKind } but never creates integration; that variable only exists in the separate OptiViewAdsSDKIntegration snippet above (line 265). Pasted on its own, the sample fails at runtime, and the section text does not say the two components are used together.

    Evidence: rendered from roku/api/OptiViewAds.json (components[1].usage) at dolby-ads-sdk v1.6.0 — the generator is faithful; the source snippet is incomplete.

    Fix (upstream in roku/api/OptiViewAds.json): add integration = createObject("roSGNode", "OptiViewAds:OptiViewAdsSDKIntegration") (or a one-line note that integration is the registered OptiViewAdsSDKIntegration node) before the player.source = … line.

    Raised by Fable; verified by the orchestrator.

    ads/static/ads/v2/api-reference/roku/index.html:289

  • [NIT] iOS: ScheduledBreak / ScheduledBreakPosition exist twice (Core + SDK) — duplicate Runtime pages, ambiguous type

    [NIT] ScheduledBreak / ScheduledBreakPosition are declared public in both OptiViewAdsCore and OptiViewAdsSDK — the Runtime reference lists each twice and the type is ambiguous for import OptiViewAdsRuntime

    Problem: New in 1.6.0 (no hash-suffixed top-level page existed in Runtime at 1.4.0): OptiViewAdsRuntime shows scheduledbreak-6zja6 (Core, externalID s:15OptiViewAdsCore14ScheduledBreakV) next to scheduledbreak-r09p (SDK) and scheduledbreakposition-3yrp5 / -61uo0, all with the same display name and empty abstracts; OptiViewAds.getScheduledBreaks() links to -r09p and the reader has no way to tell them apart. Android mirrors this: ads-sdk-core/…/-scheduled-break and ads-sdk/…/-scheduled-break both appear in the Dokka navigation.

    Evidence: ios/OptiViewAdsCore/Sources/OptiViewAdsCore/ScheduledBreaks.swift:4,14 and ios/OptiViewAdsSDK/Sources/OptiViewAdsSDK/ScheduledBreak.swift:2,12 both declare public types of the same name; ios/OptiViewAdsRuntime/Sources/OptiViewAdsRuntime/Exports.swift does @_exported import of both, so unqualified ScheduledBreak is ambiguous in apps that follow the landing page's import OptiViewAdsRuntime — the SDK's own iOS test app has to write OptiViewAdsSDK.ScheduledBreak (apps/test-app-ios/SDKBridge/Sources/E2EAgentSDKBridge/BreakSnapshot.swift:5). Android: android/ads-sdk-core/.../ScheduledBreaks.kt:8,14 are public without @OptiViewInternalApi.

    Fix (dolby-ads-sdk, not this PR): keep one public pair — reuse the Core types in the SDK (as Break, Asset, SessionDeliveryMode do) or mark the Core ones @_spi(OptiViewInternal) / @OptiViewInternalApi @suppress (+ ios/docc-hidden-symbols.txt) — then regenerate. Nothing to change in this repo.

    Raised by Fable and Gemini; verified by the orchestrator.

    ads/static/ads/v2/api-reference/ios/OptiViewAdsRuntime/data/documentation/optiviewadsruntime/scheduledbreak-6zja6.json:1

  • [NIT] Core references publish new 1.6.0 internals (slate helpers, ScheduledBreaksTracker) despite the hidden-symbol policy

    [NIT] Android/iOS Core references publish 1.6.0 internals that the SDK's hidden-symbol policy is meant to keep out

    Problem: New public pages for SlateClock, SlateFillDecision, SlateSkipReason, SlateResolution, resolveSlate, resolveSlateFill, DEFAULT_SLATE_MIN_DURATION_SEC / defaultSlateMinDurationSec, buildScheduledBreaks, ScheduledBreaksObserver and ScheduledBreaksTracker appear in ads-sdk-core (Android) and OptiViewAdsCore (iOS). The web reference exposes only the Slate manifest model. This ScheduledBreaksTracker constructor signature even inlines suppressed symbols as a default value: canPlay: (Break) -> Boolean = { breakPlanEmptyReason(buildSeqBreak(it), EffectiveInsertionMode.OVERLAY) == null } — none of breakPlanEmptyReason, buildSeqBreak, EffectiveInsertionMode has a page.

    Evidence: the SDK hides Core internals deliberately — 134 @OptiViewInternalApi annotations in android/ads-sdk-core/src/main and ios/docc-hidden-symbols.txt ("a symbol cannot silently become public reference material"); the sibling 1.6.0 helpers LshapeAnchorResolution / resolveLshapeAnchor are hidden (LshapeAnchor.kt:41-58, LshapeAnchor.swift:34,63), the slate/scheduled-breaks helpers in Slate.kt, Slate.swift, ScheduledBreaks.kt, ScheduledBreaksTracker.kt are not.

    Fix (dolby-ads-sdk): annotate those declarations @OptiViewInternalApi + @suppress / @_spi(OptiViewInternal) and add the Swift names to ios/docc-hidden-symbols.txt, then regenerate. Nothing to change in this repo.

    Raised by Gemini; verified by the orchestrator.

    ads/static/ads/v2/api-reference/android/ads-sdk-core/com.dolby.optiview.ads.core/-scheduled-breaks-tracker/index.html:97

  • [NIT] Hand-written guides now lag the 1.6.0 reference (follow-up docs PR)

    [NIT] Hand-written guides now contradict or lag the 1.6.0 reference — follow-up docs PR, not a reason to hold this one

    • ads/player-integration/optiview-ads-sdk/index.mdx:59 — manifestUrl "Required.": optional since 1.6.0 when manifestUrlDiscovery is enabled with a discovery-capable adapter.
    • ads/player-integration/optiview-ads-sdk/ios.mdx:93 — "Requires the THEOplayer iOS SDK 11 or later": ios/adapter-theoplayer/Package.swift:20 now requires 11.15.0 plus the THEOplayerTHEOliveIntegration product (was 11.0.0 at v1.4.0).
    • ads/concepts/breaks.mdx:161 — when ad content is shorter than duration "the player returns early": with a channel slate the slate now fills the remainder and the break ends at duration (1.6.0 changelog, BreakManifest.slate).
    • ads/concepts/breaks.mdx:178 — a pause break "fires every time the viewer pauses": 1.6.0 stops after the rotation is exhausted (packages/core/src/services/PauseAdController.ts:215-228, changelog "Stop showing pause ads after the rotation is exhausted").
    • ads/concepts/breaks.mdx L-shape sections / ads/concepts/break-manifest.mdx — no mention of the anchor field (LshapeAnchor, spec 1.11.0) or the top-level slate (spec 1.12.0).
    • ads/player-integration/optiview-ads-sdk/roku.mdx — no adtimeupdate, event eventId, or OptiViewAds:OptiViewAdsInterceptor.
    • No guide yet for getScheduledBreaks() / scheduledbreakschange (scrubber markers).

    Raised by Fable, Gemini and Astra; verified by the orchestrator.

    ads/player-integration/optiview-ads-sdk/index.mdx:59

<div class="cover ">
<h1 class="cover"><span><span>anchor</span></span></h1>
</div>
<div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":ads-sdk-core/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="anchor.html">anchor</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html">String</a><span class="token operator">?</span></div><p class="paragraph">The L-shape <code class="lang-kotlin">anchor</code> as written in the manifest (<a href="../-break-format/-l-s-h-a-p-e_-a-d/index.html">BreakFormat.LSHAPE_AD</a> / <a href="../-break-format/-l-s-h-a-p-e_-c-o-n-t-e-n-t/index.html">BreakFormat.LSHAPE_CONTENT</a> only; null when absent or not a string). Kept raw, like <a href="../-targeting/index.html">Targeting</a>, so an unrecognised value can be reported; resolve via <a href="../../../ads-sdk-core/com.dolby.optiview.ads.core/index.html">resolveLshapeAnchor</a>.</p></div></div>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[NIT] Android KDoc links [resolveLshapeAnchor] / [endOverlay] point at package index pages

[NIT] Android KDoc links to internal symbols resolve to package index pages

Problem: BreakVariant.anchor tells the reader to "resolve via resolveLshapeAnchor" and links it to ../../../ads-sdk-core/com.dolby.optiview.ads.core/index.html — the package page, where resolveLshapeAnchor does not appear because it is @OptiViewInternalApi @suppress (android/ads-sdk-core/.../LshapeAnchor.kt:55-58). Same pattern on the new OverlayAdRenderer.abandonContentHandBack page (android/ads-sdk-runtime/com.dolby.optiview.ads.runtime/-overlay-ad-renderer/abandon-content-hand-back.html:97), where [endOverlay] (an internal extension) links to the runtime package index. The iOS BreakVariant.anchor abstract carries the same "resolve via resolveLshapeAnchor" sentence for an @_spi(OptiViewInternal) function.

Evidence: resolve via <a href="../../../ads-sdk-core/com.dolby.optiview.ads.core/index.html">resolveLshapeAnchor</a> on this line; the package index.html exists, so the SDK's unlinkMissingDokkaTargets step does not catch it.

Fix (upstream): point BreakVariant.anchor at the public LshapeAnchor.from (BreakManifest.kt:306, BreakManifest.swift:283) and write endOverlay as plain code in OverlayAdRenderer.kt:460; optionally make the unlink step flag links whose target is a package index while the anchor text is not the package name.

Raised by Gemini; verified by the orchestrator.

This was referenced Nov 13, 2026
@stefdaems

Copy link
Copy Markdown

Thanks for the review. Status per item (commit 7e813062 on this branch; SDK source fixes in dolby-ads-sdk PR #1073, not yet merged):

  1. [SHOULD-FIX] manifestUrlDiscovery platforms: fixed. It now reads "web, Android and iOS" on the web, React Native, Android and iOS pages (22a105fd). Source comments are fixed in #1073.
  2. SessionConfig.manifestUrl: fixed. It now says it is optional only when manifestUrlDiscovery is on (22a105fd; source in #1073).
  3. Roku OptiViewAdsInterceptor snippet: fixed. It uses ssai: { integration: "optiview-ads-sdk" } instead of the undefined integration (7e813062; source in #1073).
  4. iOS ScheduledBreak / ScheduledBreakPosition duplicates: not fixed. It changes which symbols are public, so it needs an SDK change and an API-owner decision. Follow-up.
  5. Android KDoc links: fixed. BreakVariant.anchor now points to LshapeAnchor.from (Android and iOS) and endOverlay is plain code (22a105fd; source in #1073).
  6. Core internals in the references: not fixed. Needs @OptiViewInternalApi / @_spi(OptiViewInternal) annotations in the SDK and a regenerate. Follow-up.
  7. Hand-written guides: fixed in this PR (7e813062): manifestUrl no longer always "Required", iOS needs THEOplayer 11.15.0 plus the THEOlive integration, slate and pause-ad rotation in breaks.mdx, anchor and slate documented, Roku adtimeupdate, eventId and the interceptor, and a scheduled breaks section. The docs site build and link check were not run.

The generated reference edits will be overwritten by the next bot republish unless #1073 is in the tag it builds from.

@MaartenRimaux
MaartenRimaux merged commit dd76d07 into main Nov 13, 2026
3 checks passed
@MaartenRimaux
MaartenRimaux deleted the release/ads-sdk-1.6.0 branch November 13, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants