Repository navigation
OptiView Ads SDK 1.6.0 - #975
Conversation
This comment has been minimized.
This comment has been minimized.
MaartenRimaux
left a comment
There was a problem hiding this comment.
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)
- [SHOULD-FIX]
manifestUrlDiscoverydocumented 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]
manifestUrlDiscoveryis documented as "web and Android" only, but 1.6.0 added iOS supportProblem: The new
manifestUrlDiscoveryproperty 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:23conforms toAdsManifestUrlDiscovery,ios/adapter-theoplayer/Package.swift:20pinstheoplayer-sdk-applefrom: "11.15.0"withTHEOplayerTHEOliveIntegration, 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-106andandroid/ads-sdk/src/main/kotlin/com/dolby/optiview/ads/sdk/OptiViewAdsConfig.kt:311all 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 publishforrelease/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.manifestUrlsays omitting it uses the discovered URL, without themanifestUrlDiscoveryopt-inProblem: "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 inreact-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-56at v1.6.0 throwsDA-MANIFEST-URL-UNAVAILABLEwithreason: 'disabled'whenevermanifestUrlDiscoveryis 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 theOptiViewAdsConfig.manifestUrlDiscoverypage.Fix (upstream, same follow-up as the
manifestUrlDiscoverywording): "When omitted andmanifestUrlDiscoveryis enabled, the SDK uses …" inpackages/core/src/types/OptiViewAdsConfig.ts:525,OptiViewAdsConfig.kt:390andOptiViewAdsConfig.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:OptiViewAdsInterceptorusage snippet references an undefinedintegrationProblem: The new snippet ends with
ssai: { integration: integration.integrationKind }but never createsintegration; that variable only exists in the separateOptiViewAdsSDKIntegrationsnippet 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): addintegration = createObject("roSGNode", "OptiViewAds:OptiViewAdsSDKIntegration")(or a one-line note thatintegrationis the registeredOptiViewAdsSDKIntegrationnode) before theplayer.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/ScheduledBreakPositionare declaredpublicin both OptiViewAdsCore and OptiViewAdsSDK — the Runtime reference lists each twice and the type is ambiguous forimport OptiViewAdsRuntimeProblem: New in 1.6.0 (no hash-suffixed top-level page existed in Runtime at 1.4.0):
OptiViewAdsRuntimeshowsscheduledbreak-6zja6(Core,externalID s:15OptiViewAdsCore14ScheduledBreakV) next toscheduledbreak-r09p(SDK) andscheduledbreakposition-3yrp5/-61uo0, all with the same display name and empty abstracts;OptiViewAds.getScheduledBreaks()links to-r09pand the reader has no way to tell them apart. Android mirrors this:ads-sdk-core/…/-scheduled-breakandads-sdk/…/-scheduled-breakboth appear in the Dokka navigation.Evidence:
ios/OptiViewAdsCore/Sources/OptiViewAdsCore/ScheduledBreaks.swift:4,14andios/OptiViewAdsSDK/Sources/OptiViewAdsSDK/ScheduledBreak.swift:2,12both declarepublictypes of the same name;ios/OptiViewAdsRuntime/Sources/OptiViewAdsRuntime/Exports.swiftdoes@_exported importof both, so unqualifiedScheduledBreakis ambiguous in apps that follow the landing page'simport OptiViewAdsRuntime— the SDK's own iOS test app has to writeOptiViewAdsSDK.ScheduledBreak(apps/test-app-ios/SDKBridge/Sources/E2EAgentSDKBridge/BreakSnapshot.swift:5). Android:android/ads-sdk-core/.../ScheduledBreaks.kt:8,14are public without@OptiViewInternalApi.Fix (dolby-ads-sdk, not this PR): keep one public pair — reuse the Core types in the SDK (as
Break,Asset,SessionDeliveryModedo) 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,ScheduledBreaksObserverandScheduledBreaksTrackerappear inads-sdk-core(Android) andOptiViewAdsCore(iOS). The web reference exposes only theSlatemanifest model. ThisScheduledBreaksTrackerconstructor signature even inlines suppressed symbols as a default value:canPlay: (Break) -> Boolean = { breakPlanEmptyReason(buildSeqBreak(it), EffectiveInsertionMode.OVERLAY) == null }— none ofbreakPlanEmptyReason,buildSeqBreak,EffectiveInsertionModehas a page.Evidence: the SDK hides Core internals deliberately — 134
@OptiViewInternalApiannotations inandroid/ads-sdk-core/src/mainandios/docc-hidden-symbols.txt("a symbol cannot silently become public reference material"); the sibling 1.6.0 helpersLshapeAnchorResolution/resolveLshapeAnchorare hidden (LshapeAnchor.kt:41-58,LshapeAnchor.swift:34,63), the slate/scheduled-breaks helpers inSlate.kt,Slate.swift,ScheduledBreaks.kt,ScheduledBreaksTracker.ktare not.Fix (dolby-ads-sdk): annotate those declarations
@OptiViewInternalApi+@suppress/@_spi(OptiViewInternal)and add the Swift names toios/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 whenmanifestUrlDiscoveryis 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:20now requires11.15.0plus theTHEOplayerTHEOliveIntegrationproduct (was11.0.0at v1.4.0).ads/concepts/breaks.mdx:161— when ad content is shorter thanduration"the player returns early": with a channelslatethe slate now fills the remainder and the break ends atduration(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.mdxL-shape sections /ads/concepts/break-manifest.mdx— no mention of theanchorfield (LshapeAnchor, spec 1.11.0) or the top-levelslate(spec 1.12.0).ads/player-integration/optiview-ads-sdk/roku.mdx— noadtimeupdate, eventeventId, orOptiViewAds: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> |
There was a problem hiding this comment.
[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.
|
Thanks for the review. Status per item (commit
The generated reference edits will be overwritten by the next bot republish unless #1073 is in the tag it builds from. |
This PR contains the Web API reference for OptiView Ads SDK version 1.6.0.