Skip to content

OptiView Ads SDK 1.6.1 - #987

Open
theoplayer-bot[bot] wants to merge 1 commit into
mainfrom
release/ads-sdk-1.6.1
Open

theoplayer-bot[bot] wants to merge 1 commit into
mainfrom
release/ads-sdk-1.6.1

Conversation

@theoplayer-bot

Copy link
Copy Markdown
Contributor

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

@theoplayer-bot
theoplayer-bot Bot requested a review from a team as a code owner November 20, 2026 11:58
@theoplayer-bot

Copy link
Copy Markdown
Contributor Author
Documentation preview
🚀 View preview at
https://docs-preview.optiview.dolby.com/pr-987/

Deployed from commit c094f63 at 2026-11-20 12:12 UTC.

@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 c094f63

documentation#987 — OptiView Ads SDK 1.6.1 Verdict: APPROVE WITH NITS
Bot-generated replacement of the five OptiView Ads SDK API references (TypeDoc web + React Native, Dokka Android, DocC iOS, single-page Roku) under ads/static/ads/v2/api-reference/ for SDK release 1.6.1 (released 2026-11-20). The generated output is complete and safe to merge: every landing page says 1.6.1 with no 1.6.0 remnants, ~60k local links/anchors resolve (web 9,031 · RN 5,467 · Android 36,720 · Roku 8 · 13,976 DocC references, 0 broken), every DocC JSON page has its HTML shell and vice versa, all 13 links from the hand-written guides into the reference still resolve, no internal hosts/paths/secrets, nothing outside the reference tree changes, and the 1.6.1 public API (MediaLoadOptions, wrappedPlayer, watchFrames, Asset.mimeType, Roku configure/contentUrl, …) is present; CI build, lint and create-pr are green. The two should-fix items are companion/follow-up work (hand-written guides in this repo; symbol visibility in the SDK repo), not defects in this diff.

Blockers / Should-fix (confirmed)

  1. [SHOULD-FIX] Hand-written integration guides not updated for SDK 1.6.1 — ads/player-integration/optiview-ads-sdk/ios.mdx:25 — iOS/RN Podfile snippets lack the Dolby-OptiView/cocoapods-specs source that 1.6.1's unbundled Lens pod needs (and the Xcode 26.2+ note), web.mdx lacks the Lens peer-dependency note, roku.mdx predates the interceptor configure mode, VOD pages still promise snapback for every layout; fix with a small docs commit on this branch or a follow-up PR (Fable, Gemini, Astra)
  2. [SHOULD-FIX] Internal scheduler/media helpers and a Jira key published as public Android/iOS API — …/-pre-marker-state/index.html:96 — PreMarkerState (consumeForTest, "internal; public for SDK tests", abstract starts with ADS-1089:), PRE_MARKER_MAX_EARLY_MS and the AssetMedia*/resolveAssetMedia conformance helpers are new public pages on Android (73) and iOS (~320) while web exports none of them; the SDK's @OptiViewInternalApi/docc-hidden-symbols.txt guard was not applied — fix in dolby-ads-sdk, regenerates at the next release (Fable, Gemini, Astra)

Nits

  • [NIT] HlsJsAdapter.load(url) inherits a doc sentence about an options parameter it does not take — web/classes/HlsJsAdapter.html:337; RN OptiViewAdsConnector.seek text is also stale (pre-existing) — fix in SDK JSDoc (Fable, Gemini, Astra)
  • [NIT] Dokka renders the nullable cancel function (() -> Unit)? as () -> Unit? on watchFrames/watchPosition — …/-player-adapter/watch-frames.html:97 — use a typealias in the SDK; downgraded from Astra's SHOULD-FIX (Astra)
  • [NIT] AssetMedia summary misstates the fallback for unrecognised image//video/ subtypes (MIME family decides kind before mediaType) — …/-asset-media/index.html:96 — reword KDoc/DocC in the SDK (Astra)
  • [NIT] Non-deterministic DocC JSON key order (2,990 of 3,040 modified iOS JSON files are parse-identical) and binary LMDB indexes inflate every release PR (~36 MB of this 41 MB diff) — ios/OptiViewAdsCore/metadata.json:1 — sort keys in docc-sanitize-paths.mjs (Fable, Gemini)
  • [NIT] Bot PR body says "Web API reference" for a five-platform update — .github/workflows/ads-sdk-release.yml:46 (Fable)

Requirements

  • Five complete, self-consistent references at 1.6.1 — met (web/index.html:12, react-native/index.html:12, roku/index.html:6, android/index.html:46, ios/index.html:15; 0 files still mention 1.6.0; link/anchor/JSON↔HTML checks above all 0 broken)
  • Nothing outside ads/static/ads/v2/api-reference/, no stale pages — met (4,910 files, all under the five platform dirs; the 4 deletions are the superseded iOS Asset/CompanionAsset initializers replaced by the mimeType: variants; the 4 "R100" are git pairing identical DocC shells)
  • Site keeps working, no internal hosts/paths/secrets — met (13 guide links incl. Roku anchors resolve; no xagget/xnappet/sneezysparrow/bitbucket/local paths; CI build + lint green)
  • 1.6.1 public API changes visible in the reference — met (web MediaLoadOptions, PlayerAdapter.load/preload(…, options?), wrappedPlayer on all adapters; Android/iOS Asset.mimeType, isImage, PlayerAdapter.wrappedPlayer/watchFrames; Roku configure, playerSupportsAsync, discoveryResponse, contentUrl in ready/operationresult, 512-break ROKU-RESOURCE-LIMIT)
  • Hand-written guides consistent with 1.6.1 — partial (should-fix 1)

Rejected reviewer claims: 2

  • Astra [SHOULD-FIX] "Roku contentUrl field directs SGAI users to an SSAI-only value" → rejected: the field row (roku/index.html:111) states that a channel ID declares an SSAI-only session and fails with content-url-required if SGAI is selected, and L297-299 document the SGAI alternatives (URL contentUrl for app-started, configure for interceptor-started); the roku.mdx part is folded into should-fix 1.
  • Astra [NIT] "Four existing DocC initializer permalinks lose their targets" → rejected: expected consequence of the changed init(…mimeType:…) signatures; DocC static output has no redirect mechanism and every previous release behaved the same.

Reviewers: Fable APPROVE WITH NITS · Gemini APPROVE WITH NITS · Astra REQUEST CHANGES (its blocker is should-fix 1: a companion guide change outside this bot diff, not a defect in the generated reference)

Findings outside the changed lines

  • [SHOULD-FIX] Hand-written integration guides not updated for SDK 1.6.1 (companion change)

    Problem. This PR publishes the 1.6.1 reference, but the hand-written guides next to it still describe 1.6.0 (the bot only replaces ads/static/ads/v2/api-reference/<platform>). Per the SDK 1.6.1 changelog and the SDK's own install docs, a developer following the site after this merges hits:

    • iOS/tvOS + React Native CocoaPods — 1.6.1 unbundles Lens: OptiViewAdsSDK now depends on the OptiViewLensSDK 0.7.0 pod from https://github.com/Dolby-OptiView/cocoapods-specs.git. The Podfile snippets in ios.mdx L25-26 and react-native.mdx L46-47 list only THEOplayer/cocoapods-specs + the CDN, so pod 'OptiViewAdsRuntime', '1.6.1' cannot resolve its Lens dependency. Neither page mentions the new Xcode 26.2+ requirement for iOS/tvOS builds.
    • Web — @dolby-optiview/lens-sdk 0.7.0 became a shared peer dependency; web.mdx should mention that Yarn classic / pnpm (or --legacy-peer-deps) users add it explicitly.
    • Roku — roku.mdx L119-127 still describes OptiViewAdsInterceptor as SSAI-only with a manual startSession, while the regenerated reference documents the new configure(config) discovery-started mode, playerSupportsAsync, discoveryResponse and SGAI support.
    • VOD snapback (pre-existing since 1.6.0, still wrong): vod/index.mdx L76 and breaks.mdx L190 say any break with snapback pulls the viewer back; since 1.6.x only Single and L-Shape Ad breaks do — Double Box, L-Shape Content and Overlay play on after a seek.

    Evidence. SDK main (1.6.1) web/demo/docs/17-install.md L45-46: source 'https://github.com/Dolby-OptiView/cocoapods-specs.git' # the Lens SDK pods; its Lens note: "CocoaPods needs the https://github.com/Dolby-OptiView/cocoapods-specs.git source … Lens requires Xcode 26.2 or newer." CHANGELOG 1.6.1 Changed: "The Android, iOS and tvOS SDKs now depend on the public Lens SDK 0.7.0 instead of bundling it … CocoaPods apps add the https://github.com/Dolby-OptiView/cocoapods-specs.git source, and building for iOS or tvOS requires Xcode 26.2 or newer." and "VOD snapback now applies only to Single and L-Shape Ad breaks".

    Fix. Land a small docs commit on this branch (or a follow-up PR right after): add the Dolby-OptiView specs source to both Podfile snippets, e.g.

    source 'https://github.com/THEOplayer/cocoapods-specs.git'
    source 'https://github.com/Dolby-OptiView/cocoapods-specs.git'  # the Lens SDK pods
    source 'https://cdn.cocoapods.org/'

    note Xcode 26.2+ in ios.mdx, the Lens peer dependency in web.mdx, the configure-driven interceptor mode in roku.mdx, and the layout rule for snapback in the VOD/breaks pages. (Raised by all three reviewers for the Podfile; Roku by Gemini/Fable; snapback by Astra.)

    ads/player-integration/optiview-ads-sdk/ios.mdx:25

  • [SHOULD-FIX] Internal scheduler/media helpers and a Jira key published as public Android/iOS API

    Problem. New in this release (0 hits on main): the Android and iOS Core references now publish internal implementation surface as customer-facing API — PreMarkerState (with consumeForTest, offer "internal; public for SDK tests"), PRE_MARKER_MAX_EARLY_MS / preMarkerMaxEarlyMs, and the AssetMedia* / resolveAssetMedia / resolveMedia / normalizeMimeType / collectAssetMediaIssues conformance helpers (73 Dokka pages, ~320 DocC files). The PreMarkerState abstract starts with the ticket key ADS-1089:. The web reference deliberately exports none of these (0 pages mention AssetMedia or PreMarker), so the platforms are now inconsistent and an integrator browsing Android/iOS sees test hooks next to supported API.

    Evidence. this page: class PreMarkerState — ADS-1089: the next pending VOD break for the platform's pre-marker trigger…; consume-for-test.html L97: fun consumeForTest(breakId: String, timeDiffMs: Double): Boolean — Test hook: …; iOS optiviewadscore/premarkerstate.json abstract "ADS-1089: the next pending VOD break …". The SDK already has the guard for exactly this (@OptiViewInternalApi + @suppress on BreakScheduler et al.; ios/docc-hidden-symbols.txt, whose header says scripts/build-docs-ios.sh fails when a listed symbol appears in the Core archive) — these symbols were simply not added. SDK AGENTS.md rule 9 also forbids ticket keys in doc comments.

    Fix (SDK repo, not this PR). In dolby-ads-sdk: annotate PreMarkerState, PRE_MARKER_MAX_EARLY_MS and the internal AssetMedia.kt declarations with @OptiViewInternalApi + @suppress (or make consumeForTest internal with @VisibleForTesting), mark the Swift twins @_spi(OptiViewInternal) and add them to ios/docc-hidden-symbols.txt, drop the ADS-1089: prefix from the KDoc/DocC comments, and regenerate at the next release. Nothing to change in this generated diff. (Raised by all three reviewers.)

    ads/static/ads/v2/api-reference/android/ads-sdk-core/com.dolby.optiview.ads.core/-pre-marker-state/index.html:96

  • [NIT] HlsJsAdapter.load(url) inherits a doc sentence about an options parameter it does not take

    Problem. HlsJsAdapter.load is declared load(url: string): Promise<void> (no options), but because the override has no JSDoc of its own TypeDoc copies the updated PlayerAdapter.load comment, so the page tells readers that "options carries the manifest's MIME type" for a parameter that does not exist here. ShakaAdapter.load and THEOplayerAdapter.load correctly show load(url, options?: MediaLoadOptions).

    Evidence. L331-337: signature load(url: string): Promise<void>, parameters list only url, description ends with For an ad, <code>options</code> carries the manifest's MIME type when it declares one.

    Related stale text, pre-existing (not changed by this PR): the React Native OptiViewAdsConnector.seek doc still says "suppressed during breaks with controls.snapback" (L283-286) while web/Android/iOS seek were updated to "a crossed unwatched snapback break plays first".

    Fix (SDK repo). Either accept _options?: MediaLoadOptions in HlsJsAdapter.load or give the override its own JSDoc ("loads the HLS source; the MIME hint is not used"); update the RN connector seek JSDoc to match web. Regenerates automatically at the next release. (Raised by all three reviewers.)

    ads/static/ads/v2/api-reference/web/classes/HlsJsAdapter.html:337

  • [NIT] Dokka renders the nullable cancel function (() -> Unit)? as () -> Unit?

    Problem. The Kotlin source declares fun watchFrames(onFrame: (Double) -> Unit): (() -> Unit)? = null (nullable function), but the generated page shows () -> Unit? — a non-null function returning a nullable Unit — right before the sentence "Null when the player cannot report frames". Same for watchPosition (L97) and the ExoPlayerAdapter/THEOplayerAdapter overrides; the search index scripts/pages.json even drops the ? entirely. An adapter author copying the return type gets a compile error on the override.

    Evidence. L97: open fun watchFrames(onFrame: (Double) -> Unit): () -> Unit? vs SDK main PlayerAdapter.kt L167 (() -> Unit)?. The iOS twin is rendered correctly: func watchFrames(_ onFrame: @escaping (Double) -> Void) -> (() -> Void)?.

    Fix (SDK repo). Known Dokka rendering limitation for nullable function types; sidestep it with a named type, e.g. typealias Cancel = () -> Unit and return Cancel?, so the page reads : Cancel?. Downgraded from Astra's SHOULD-FIX: the prose states the nullability and the compiler catches a wrong override. (Raised by Astra.)

    ads/static/ads/v2/api-reference/android/ads-sdk-core/com.dolby.optiview.ads.core/-player-adapter/watch-frames.html:97

  • [NIT] Non-deterministic DocC JSON key order and binary LMDB indexes inflate every release PR

    Problem. 2,990 of the 3,040 modified iOS .json files in this PR are semantically identical to main — only the key order changed (DocC serialises dictionaries without sorted keys, so every xcodebuild docbuild reorders them). That is ~36 MB of the 41 MB diff and ~16 MB of new blobs in repo history per release, and it buries the 50 JSON files with real changes. The 6 index/data.mdb, navigator.index, availability.index files (~2 MB, binary) are Xcode's native LMDB navigator index; the web DocC renderer loads index/index.json.

    Evidence. This file: same three keys, reordered. optiviewadscore/break.json: old key order hierarchy, identifier, kind, …, new metadata, sections, hierarchy, …, parsed content equal. Verified by parsing every modified JSON at origin/main and HEAD.

    Fix (SDK repo). In scripts/lib/docc-sanitize-paths.mjs (already rewrites every DocC .json) re-serialise with recursively sorted keys (JSON.stringify with sorted replacer, or jq -cS), and drop the LMDB index files from the published tree in scripts/build-docs-ios.sh if the rendered site does not need them. Future bot PRs then show only real API changes. (Raised by Fable and Gemini.)

    ads/static/ads/v2/api-reference/ios/OptiViewAdsCore/metadata.json:1

  • [NIT] Bot PR body says "Web API reference" for a five-platform update

    Problem. The auto-generated description reads "This PR contains the Web API reference for OptiView Ads SDK version 1.6.1", but the branch replaces the web, Android, iOS/tvOS, React Native and Roku references (4,910 files, 3,408 of them iOS).

    Evidence. ads-sdk-release.yml L46: --body "This PR contains the Web API reference for OptiView Ads SDK version ${ads_sdk_version}."

    Fix (workflow, separate PR). --body "This PR contains the Web, Android, iOS/tvOS, React Native and Roku API references for OptiView Ads SDK version ${ads_sdk_version}." (Raised by Fable.)

    .github/workflows/ads-sdk-release.yml:46

<div class="breadcrumbs"><a href="../../index.html">ads-sdk-core</a><span class="delimiter">/</span><a href="../index.html">com.dolby.optiview.ads.core</a><span class="delimiter">/</span><span class="current">AssetMedia</span></div>
<div class="cover ">
<h1 class="cover"><span>Asset</span><wbr><span><span>Media</span></span></h1>
<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">data </span><span class="token keyword">class </span><a href="index.html">AssetMedia</a><span class="token punctuation">(</span><span class="parameters "><span class="parameter "><span class="token keyword">val </span>kind<span class="token operator">: </span><a href="../-asset-media-kind/index.html">AssetMediaKind</a><span class="token operator">?</span><span class="token punctuation">, </span></span><span class="parameter "><span class="token keyword">val </span>format<span class="token operator">: </span><a href="../-asset-media-format/index.html">AssetMediaFormat</a><span class="token operator">?</span><span class="token punctuation">, </span></span><span class="parameter "><span class="token keyword">val </span>mimeType<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><span class="token punctuation">, </span></span><span class="parameter "><span class="token keyword">val </span>source<span class="token operator">: </span><a href="../-asset-media-source/index.html">AssetMediaSource</a><span class="token operator">?</span><span class="token punctuation">, </span></span><span class="parameter "><span class="token keyword">val </span>issue<span class="token operator">: </span><a href="../-asset-media-issue/index.html">AssetMediaIssue</a><span class="token operator">?</span></span></span><span class="token punctuation">)</span></div><p class="paragraph">How the SDK handles an asset's media (mirrors the TS <code class="lang-kotlin">AssetMedia</code>). A declared <code class="lang-kotlin">mimeType</code> the SDK recognises decides <span>kind</span> and <span>format</span>; otherwise <code class="lang-kotlin">mediaType</code> decides <span>kind</span>, and the URL or the file content decides the format.</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] AssetMedia summary misstates the fallback for unrecognised image//video/ subtypes

Problem. The class summary says "A declared mimeType the SDK recognises decides kind and format; otherwise mediaType decides kind". The resolver does something else for an unrecognised but well-formed MIME type: image/avif with mediaType: "video" resolves to kind = image (format undetermined, issue IMAGE_TYPE_UNSUPPORTED), not video. Same text in the iOS AssetMedia abstract.

Evidence. L96 vs the resolver's own doc on resolve-asset-media.html L97: "another video/ or image/ subtype decides the kind only". SDK main AssetMedia.kt L134: val kind = recognised?.first ?: declared?.let(::kindOfFamily) — the MIME family wins before mediaType is consulted.

Fix (SDK repo). Reword the AssetMedia KDoc/DocC (and the TS mirror) to: "a recognised mimeType decides kind and format; another image//video/ subtype decides kind only; otherwise mediaType decides kind and the URL or file decides the format." (Raised by Astra.)

This branch has not been deployed

No deployments
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.

1 participant