Repository navigation
OptiView Ads SDK 1.6.1 - #987
theoplayer-bot[bot] wants to merge 1 commit into
Conversation
|
MaartenRimaux
left a comment
There was a problem hiding this comment.
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)
- [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 theDolby-OptiView/cocoapods-specssource that 1.6.1's unbundled Lens pod needs (and the Xcode 26.2+ note),web.mdxlacks the Lens peer-dependency note,roku.mdxpredates the interceptorconfiguremode, 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) - [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 withADS-1089:),PRE_MARKER_MAX_EARLY_MSand theAssetMedia*/resolveAssetMediaconformance helpers are new public pages on Android (73) and iOS (~320) while web exports none of them; the SDK's@OptiViewInternalApi/docc-hidden-symbols.txtguard 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 anoptionsparameter it does not take —web/classes/HlsJsAdapter.html:337; RNOptiViewAdsConnector.seektext is also stale (pre-existing) — fix in SDK JSDoc (Fable, Gemini, Astra) - [NIT] Dokka renders the nullable cancel function
(() -> Unit)?as() -> Unit?onwatchFrames/watchPosition—…/-player-adapter/watch-frames.html:97— use atypealiasin the SDK; downgraded from Astra's SHOULD-FIX (Astra) - [NIT]
AssetMediasummary misstates the fallback for unrecognisedimage//video/subtypes (MIME family decides kind beforemediaType) —…/-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 indocc-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 iOSAsset/CompanionAssetinitializers replaced by themimeType: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?),wrappedPlayeron all adapters; Android/iOSAsset.mimeType,isImage,PlayerAdapter.wrappedPlayer/watchFrames; Rokuconfigure,playerSupportsAsync,discoveryResponse,contentUrlinready/operationresult, 512-breakROKU-RESOURCE-LIMIT) - Hand-written guides consistent with 1.6.1 — partial (should-fix 1)
Rejected reviewer claims: 2
- Astra [SHOULD-FIX] "Roku
contentUrlfield 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 withcontent-url-requiredif SGAI is selected, and L297-299 document the SGAI alternatives (URLcontentUrlfor app-started,configurefor interceptor-started); theroku.mdxpart 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:
OptiViewAdsSDKnow depends on theOptiViewLensSDK0.7.0 pod fromhttps://github.com/Dolby-OptiView/cocoapods-specs.git. The Podfile snippets inios.mdxL25-26 andreact-native.mdxL46-47 list onlyTHEOplayer/cocoapods-specs+ the CDN, sopod '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-sdk0.7.0 became a shared peer dependency;web.mdxshould mention that Yarn classic / pnpm (or--legacy-peer-deps) users add it explicitly. - Roku —
roku.mdxL119-127 still describesOptiViewAdsInterceptoras SSAI-only with a manualstartSession, while the regenerated reference documents the newconfigure(config)discovery-started mode,playerSupportsAsync,discoveryResponseand SGAI support. - VOD snapback (pre-existing since 1.6.0, still wrong):
vod/index.mdxL76 andbreaks.mdxL190 say any break withsnapbackpulls 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.mdL45-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 inweb.mdx, theconfigure-driven interceptor mode inroku.mdx, and the layout rule forsnapbackin 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 - iOS/tvOS + React Native CocoaPods — 1.6.1 unbundles Lens:
-
[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(withconsumeForTest,offer"internal; public for SDK tests"),PRE_MARKER_MAX_EARLY_MS/preMarkerMaxEarlyMs, and theAssetMedia*/resolveAssetMedia/resolveMedia/normalizeMimeType/collectAssetMediaIssuesconformance helpers (73 Dokka pages, ~320 DocC files). ThePreMarkerStateabstract starts with the ticket keyADS-1089:. The web reference deliberately exports none of these (0 pages mentionAssetMediaorPreMarker), 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.htmlL97:fun consumeForTest(breakId: String, timeDiffMs: Double): Boolean — Test hook: …; iOSoptiviewadscore/premarkerstate.jsonabstract"ADS-1089: the next pending VOD break …". The SDK already has the guard for exactly this (@OptiViewInternalApi+@suppressonBreakScheduleret al.;ios/docc-hidden-symbols.txt, whose header saysscripts/build-docs-ios.shfails 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: annotatePreMarkerState,PRE_MARKER_MAX_EARLY_MSand the internalAssetMedia.ktdeclarations with@OptiViewInternalApi+@suppress(or makeconsumeForTestinternalwith@VisibleForTesting), mark the Swift twins@_spi(OptiViewInternal)and add them toios/docc-hidden-symbols.txt, drop theADS-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
optionsparameter it does not takeProblem.
HlsJsAdapter.loadis declaredload(url: string): Promise<void>(nooptions), but because the override has no JSDoc of its own TypeDoc copies the updatedPlayerAdapter.loadcomment, so the page tells readers that "optionscarries the manifest's MIME type" for a parameter that does not exist here.ShakaAdapter.loadandTHEOplayerAdapter.loadcorrectly showload(url, options?: MediaLoadOptions).Evidence. L331-337: signature
load(url: string): Promise<void>, parameters list onlyurl, description ends withFor 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.seekdoc still says "suppressed during breaks with controls.snapback" (L283-286) while web/Android/iOSseekwere updated to "a crossed unwatched snapback break plays first".Fix (SDK repo). Either accept
_options?: MediaLoadOptionsinHlsJsAdapter.loador give the override its own JSDoc ("loads the HLS source; the MIME hint is not used"); update the RN connectorseekJSDoc 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 nullableUnit— right before the sentence "Null when the player cannot report frames". Same forwatchPosition(L97) and theExoPlayerAdapter/THEOplayerAdapteroverrides; the search indexscripts/pages.jsoneven 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 SDKmainPlayerAdapter.ktL167(() -> 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 = () -> Unitand returnCancel?, 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
.jsonfiles in this PR are semantically identical tomain— only the key order changed (DocC serialises dictionaries without sorted keys, so everyxcodebuild docbuildreorders 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 6index/data.mdb,navigator.index,availability.indexfiles (~2 MB, binary) are Xcode's native LMDB navigator index; the web DocC renderer loadsindex/index.json.Evidence. This file: same three keys, reordered.
optiviewadscore/break.json: old key orderhierarchy, identifier, kind, …, newmetadata, sections, hierarchy, …, parsed content equal. Verified by parsing every modified JSON atorigin/mainandHEAD.Fix (SDK repo). In
scripts/lib/docc-sanitize-paths.mjs(already rewrites every DocC.json) re-serialise with recursively sorted keys (JSON.stringifywith sorted replacer, orjq -cS), and drop the LMDB index files from the published tree inscripts/build-docs-ios.shif 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.ymlL46:--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> |
There was a problem hiding this comment.
[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 PR contains the Web API reference for OptiView Ads SDK version 1.6.1.