[theoplayer-bot]

Summary

This PR updates the OptiView Ads SDK API references to version 1.3.0 for Web, Android, iOS, React Native, and Roku.

Roku is now accessible under Player integration → OptiView Ads SDK → Roku and API references → Ads SDK Roku API. The new integration guide covers the signed component-library setup, application-owned Video node, session events, supported workflows, and shutdown order. The ad workflows page no longer lists Roku as a platform without a client-side SDK.

The references include the fixes from the automated review: no dead links in the Android reference, pages for every 1.3.0 type named in a web/RN signature, corrected asset-parameter macro semantics on Android/iOS/RN, and the full-token macro keys and adchannelchange fields on Roku.

Validation: production build, lint, typecheck, formatting, and the new guide's spellcheck passed. SDK-side gates: Dokka link check, TypeDoc type-link test, and the @suppress convention test.

[MaartenRimaux]

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

documentation#946 — OptiView Ads SDK 1.3.0 Verdict: REQUEST CHANGES

Bot sync of the generated SDK API references (TypeDoc web/RN, Dokka Android, DocC iOS, and a first Roku page) from 1.0.0 to 1.3.0 — 4741 files, all under ads/static/ads/v2/api-reference/. The generated sites are structurally sound (version stamps 1.3.0 everywhere, every DocC page has its data JSON, no broken web/RN links, every existing deep link from the .mdx guides and sidebar still resolves, Roku page byte-identical to a regeneration from SDK release/1.3.0, no leaked paths/hosts/secrets). One in-repo gap should be fixed on this branch (the Roku reference is unreachable); the remaining confirmed items are SDK-side documentation defects that this sync publishes and that need a KDoc/DocC/JSON fix plus regeneration.

Findings (each posted as its own inline comment; paths relative to ads/static/ads/v2/api-reference/ unless noted)

1. [SHOULD-FIX] New Roku API reference is unreachable from the site navigation — roku/index.html:27
2. [SHOULD-FIX] Android reference: 9 new dead links to @suppress-ed internal types — android/ads-sdk-core/com.dolby.optiview.ads.core/resolve-external-vendor-parameters.html:97
3. [SHOULD-FIX] Web/RN reference: new 1.3.0 types referenced in signatures have no page — web/interfaces/BreakManifest.html:66
4. [SHOULD-FIX] Android/iOS: SessionConfig.assetParameterMacros still says null/nil leaves the macro unresolved — android/ads-sdk-core/com.dolby.optiview.ads.core/-asset-parameter-macro-value/-companion/of.html:97
5. [SHOULD-FIX] Roku: updateAssetParameterMacros keys must be the full $NAME$ token — roku/index.html:79
6. [NIT] Android AdChannelChangeReason.EVENT_BOUNDARY has no description — android/ads-sdk-core/com.dolby.optiview.ads.core/-ad-channel-change-reason/index.html:188
7. [NIT] Roku adchannelchange description omits reason and manifestUrl — roku/index.html:158
8. [NIT] PR body template says "Web API reference" for a five-platform sync — .github/workflows/ads-sdk-release.yml:41

Reviewer agreement: 1 and 2 raised by 3/3; 7 and 8 by 2/3; 3, 4 (Gemini), 5 (Astra), 6 (Fable) by 1/3 — all verified against the PR head and the SDK release/1.3.0 sources.

Requirements: no Jira ticket (release automation PR). PR body ("publish the 1.3.0 API reference"): met for all five platforms. Implicit — new platform reachable from the site: missing (finding 1).

Uncertain: none.

Rejected reviewer claims: 3

• Dokka --root--.html dead links (Fable, NIT) → pre-existing: 45 such links on main and 45 at the PR head, none introduced here.
• Asset-parameter precedence described inconsistently across platforms — Android Asset.assetParameters "lowest-precedence", Android/iOS SessionConfig.assetParameters "merged on top of" the asset layer, web/Android updateAssetParameters "highest of the three layers", vs. the actual order session < update < manifest-session < asset (Gemini, SHOULD-FIX) → real, but pre-existing: identical text in the 1.0.0 reference on main and the implementation already had four layers at v1.0.0; not introduced by this PR. Worth an SDK-side docs ticket.
• RN updateAssetParameterMacros "null removes a name" vs AssetParameterMacroUpdates (Gemini) → pre-existing since 1.0.0; noted inside finding 4.

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

Findings outside the changed lines

• [SHOULD-FIX] New Roku API reference is unreachable from the site navigation

  This PR publishes /ads/v2/api-reference/roku/ for the first time, but nothing on the site links to it: sidebarsAds.ts (lines 125–148) still ends with the React Native entry and ads/api/index.mdx (lines 37–40) lists only Web, Android, iOS/tvOS and React Native. A Roku developer browsing API references cannot discover this page; it is reachable only by typing the URL. The 1.0.0 sync (#878) edited sidebarsAds.ts in the same PR, so this branch is the established place to wire it.

  Two related statements in the prose docs now contradict the published reference: ads/player-integration/optiview-ads-sdk/index.mdx line 14 says the SDK is available for Web, Android, iOS and React Native, and ads/workflows/index.mdx line 22 lists Roku as a platform where a client-side SDK is not an option.

  Fix (on this branch):

  // sidebarsAds.ts, after the React Native entry
  {
    type: 'link',
    label: 'Ads SDK Roku API',
    customProps: { icon: '🧩' },
    href: 'pathname:///ads/v2/api-reference/roku/',
  },

  <!-- ads/api/index.mdx, after the React Native bullet -->
  - [Roku API reference](pathname:///ads/v2/api-reference/roku/) for the `OptiViewAds` SceneGraph component.

  and update the two sentences above. If Roku is intentionally not announced yet, drop roku from API_DOCS_PLATFORMS in the SDK's scripts/ci-publish-api-docs.sh instead, so an unlinked page is not published.

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

• [SHOULD-FIX] Android reference: 9 new dead links to @suppress-ed internal types

  The signature on this page links ExternalVendorConfiguration, AssetParameterMacroTable and ResolvedExternalVendorParameters to ../-external-vendor-configuration/index.html etc. — none of those pages exist in the tree, so every type in the signature 404s.

  Root cause (SDK repo, release/1.3.0): the types carry @suppress in their KDoc (ExternalVendorConfiguration.kt lines 3–11, ChannelSwitch.kt lines 55–66), so Dokka omits their pages, but the @OptiViewInternalApi functions that use them (resolveExternalVendorParameters, resolveExternalVendorConfigurations, changedExternalVendorProviders, decideDeliveryMode, resolveDeliveryMode, AdRenderer.resolveExternalVendorConfiguration, OverlayAdRenderer.setResumeCueEndResolver) have no @suppress, so they are documented with dangling links.

  Evidence: a link check over the Android site finds 9 missing targets that were not missing at 1.0.0 (-asset-parameter-macro-table, -delivery-mode-choice, -delivery-mode-decision, -delivery-mode-source, -external-vendor-configuration, -external-vendor-configurations-result, -resolved-external-vendor-parameters, -resume-cue-end-source-renderer/{index,set-resume-cue-end-resolver}.html), referenced from 12 pages including the ads-sdk-core and ads-sdk-runtime package indexes. 5 such targets pre-exist on main.

  Fix: SDK-side — add @suppress to those functions (or configure Dokka to suppress everything annotated @OptiViewInternalApi), regenerate and re-publish. A relative-link check in ci-publish-api-docs.sh would catch this class of defect before the push.

  ads/static/ads/v2/api-reference/android/ads-sdk-core/com.dolby.optiview.ads.core/resolve-external-vendor-parameters.html:97

• [SHOULD-FIX] Web/RN reference: new 1.3.0 types referenced in signatures have no page

  events?: ChannelEvent[] (new in 1.3.0, channel events) renders ChannelEvent as plain text — there is no web/interfaces/ChannelEvent.html and no link, so a reader cannot find what a channel event contains.

  Root cause (SDK repo): TypeDoc runs on the curated packages/sdk/src/public-api.ts with excludeExternals: true (typedoc.json). Core types that @dolby-optiview/ads-sdk exports (via export * from '@dolby-optiview/ads-sdk-core') but that public-api.ts does not re-export are treated as external: no notExported warning, no page, no link.

  Evidence — unlinked type names in the generated HTML that did not occur at 1.0.0: web: ChannelEvent (BreakManifest.events), ExternalVendorConfiguration (OptiViewAds.getExternalVendorConfiguration()), ExternalVendorConfigurationChangeEvent (OptiViewAdsEventMap), Os, OsVersionRange, Platform (Targeting.os/osVersion/platform); react-native: ExternalVendorConfiguration (24 occurrences), LiveStartPushbackConfig (OptiViewAdsReactNativeConfig.liveStartPushback), ChannelEvent, ExternalVendorConfigurationChangeEvent. OptiViewAdsExternalVendors is exported by the web package and documented on RN/Android/iOS but absent from the web reference. Conversely the new RN page interfaces/ExternalPlaybackConfig.html documents a type that react-native/src/index.ts does not export.

  Fix: SDK-side — re-export the referenced 1.3.0 types from packages/sdk/src/public-api.ts and react-native/src/public-api.ts (and align react-native/src/index.ts with public-api.ts), regenerate and re-publish.

  ads/static/ads/v2/api-reference/web/interfaces/BreakManifest.html:66

• [SHOULD-FIX] Roku: updateAssetParameterMacros keys must be the full $NAME$ token

  The page documents { set: { NAME: value }, remove: ["NAME"] }. The Roku implementation keys macros by the complete token including both $ delimiters: RokuUpdateAssetParameterMacros copies update.set keys unchanged (roku/sdk/source/OptiViewAds/AssetParameters.bs lines 21–40) and substitution looks up values[token] where RokuScanMacroToken returns $NAME$ (AssetParameterMacros.bs lines 134, 161–170); the regression test uses { set: { "$CUSTOM$": "yes" }, remove: ["$OPTIVIEW_USER_AGENT$"] } (AssetParameterTests.bs line 104).

  Scenario: an app follows the page literally with m.ads.callFunc("updateAssetParameterMacros", { set: { SEGMENT: "sports" } }) — the call reports updated, yet $SEGMENT$ in the asset parameters stays unresolved and is sent literally; remove: ["SEGMENT"] never removes a registered $SEGMENT$ macro. The start-config row (assetParameterMacros, line 114) only says "values for $NAME$ macros" and does not resolve the ambiguity.

  Fix: SDK-side — change the description in roku/api/OptiViewAds.json (line 69) to e.g. Sets or removes macro values keyed by the full token: { set: { "$NAME$": value }, remove: ["$NAME$"] }. and regenerate (scripts/build-docs-roku.mjs; the page in this PR is byte-identical to the generator output, so only the JSON needs the edit).

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

• [NIT] Roku adchannelchange description omits reason and manifestUrl

  The event is described as carrying previousChannelId, channelId, previousDeliveryMode and deliveryMode. AdChannelChangeEvent also has reason and manifestUrl (roku/sdk/source/OptiViewAds/Events.bs lines 151–158; SessionPolling.bs line 111 sets manifestUrl), and reason is the field apps need to tell a channel switch from an event boundary.

  Fix: SDK-side — extend the adchannelchange entry in roku/api/OptiViewAds.json and regenerate.

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

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

  The auto-opened PR body reads "This PR contains the Web API reference for OptiView Ads SDK version 1.3.0", while the branch replaces the web, Android, iOS, React Native and Roku references. Not part of this diff — the text is hard-coded in the workflow (.github/workflows/ads-sdk-release.yml line 41); a follow-up on main:

              --body "This PR contains the generated API references (web, Android, iOS, React Native, Roku) for OptiView Ads SDK version ${ads_sdk_version}."

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

[stefdaemsdolby]

Replies to the automated review above, by finding:

Replies for #946 (one per review thread)

1. [SHOULD-FIX] New Roku API reference is unreachable (roku/index.html:27)

Fixed. ddc096a adds the sidebar link (API references → Ads SDK Roku API), the bullet in ads/api/index.mdx, the Player integration → OptiView Ads SDK → Roku guide and the Roku sentence in the SDK overview. 3e65aa0 removes Roku from the SSAI row in ads/workflows/index.mdx ("a client-side SDK is not an option"), since the SDK now ships a Roku component.

2. [SHOULD-FIX] Android reference: 9 new dead links to @suppress-ed internal types (resolve-external-vendor-parameters.html:97)

Fixed in 93fb7cd, regenerated from SDK branch docs/api-reference-1.3.0-review:

• These declarations now carry a standalone @suppress, so their pages and package-index rows are gone:
  • changedExternalVendorProviders, resolveExternalVendorConfigurations, resolveExternalVendorParameters, resolveLiveStartPushback.
  • The device-type decideDeliveryMode/resolveDeliveryMode overloads.
  • AdRenderer.resolveExternalVendorConfiguration and OverlayAdRenderer.resolveExternalVendorConfiguration.
  • OverlayAdRenderer.setResumeCueEndResolver, whose @suppress was inline and was printed as text.
• The 5 dead targets that already existed on main came from KDoc prose links to internal types (BreakScheduler, AdBreakSequencer, PauseAdController, AdVideoPlayer, streamId). These are now code spans.
• Two Dokka limitations cannot be fixed at the source: the @suppress-ed ResumeCueEndSourceRenderer supertype in the OverlayAdRenderer signature, and the --root--.html links Dokka emits for KDoc links to a class's own constructor property. Links to these pages are now rendered as plain text.
• New gates in the SDK:
  • :dokkaGenerate fails on any other link to a page that was not generated.
  • A script test keeps every @OptiViewInternalApi declaration on a standalone @suppress.

No relative link in the Android tree points to a missing page any more.

3. [SHOULD-FIX] Web/RN reference: new 1.3.0 types referenced in signatures have no page (web/interfaces/BreakManifest.html:66)

Fixed in 93fb7cd.

• Web: new pages for ChannelEvent, ExternalVendorConfiguration, ExternalVendorConfigurationChangeEvent, Os, OsVersionRange, Platform, OptiViewAdsExternalVendors (+ OptiViewAdsExternalVendorsConfig), ExternalVendorConfigurationEntry and the GAM GamSgaiConfiguration/GamSsaiConfiguration/GamSsbConfiguration.
• React Native: new pages for ChannelEvent, ExternalVendorConfiguration, ExternalVendorConfigurationChangeEvent and LiveStartPushbackConfig.
• RN entries: the RN package entries now export the same types as the reference, including ExternalPlaybackConfig. They ship as importable names in the next SDK release.
• New SDK gate: a TypeDoc test fails when a signature names an SDK type that has no page. It ignores a documented list of types that were already unlinked before 1.3.0.

4. [SHOULD-FIX] Android/iOS: SessionConfig.assetParameterMacros still says null/nil leaves the macro unresolved (…/-asset-parameter-macro-value/-companion/of.html:97)

Fixed in 93fb7cd. These docs now say a null/nil result omits the parameter that contains the macro (the same as Empty/.empty), and point to the explicit-value variant for keeping a token literally:

• Android: SessionConfig.assetParameterMacros, OptiViewAds.updateAssetParameterMacros, AdRenderer.setSessionAssetParameterMacros and OptiViewAdsExternalVendorsConfig.assetParameterMacros.
• iOS: SessionConfig.assetParameterMacros and its init parameter, OptiViewAds.updateAssetParameterMacros(_:) (which wrongly said "counts as unresolved") and OptiViewAdsExternalVendorsConfig.assetParameterMacros.

The RN OptiViewAdsConnector.updateAssetParameterMacros and OptiViewAdsExternalVendorsApi.updateAssetParameterMacros docs now say null marks a name empty and undefined removes it.

5. [SHOULD-FIX] Roku: updateAssetParameterMacros keys must be the full $NAME$ token (roku/index.html:79)

Fixed in 93fb7cd.

• updateAssetParameterMacros now reads { set: { "$NAME$": value }, remove: ["$NAME$"] }, keyed by the full token including both $ delimiters.
• The start-config assetParameterMacros row gives the same key format with an example.
• Both state that an empty string or invalid value omits the parameters that use the macro.

6. [NIT] Android AdChannelChangeReason.EVENT_BOUNDARY has no description

Fixed in 93fb7cd: "Playback crossed the start or end of a channel event; the event's eventId identifies it."

7. [NIT] Roku adchannelchange description omits reason and manifestUrl

Fixed in 93fb7cd. The entry now lists reason (channel-id-added, channel-id-changed, channel-id-removed, vendor-configuration-changed or timebase-changed) and manifestUrl.

8. [NIT] PR body template says "Web API reference" for a five-platform sync

Follow-up on main: #950.

[stefdaemsdolby]

Summary comment for #946

Review findings addressed:

• 3e65aa0: docs repo, workflows page. Roku is no longer listed as a platform without a client-side SDK.
• 93fb7cd: all five references regenerated at 1.3.0 from SDK branch docs/api-reference-1.3.0-review.
  • It fixes findings 2–7.
  • The SDK side also adds gates for each class of defect: Dokka dead links, @suppress placement, and unlinked TypeDoc types.
  • The iOS diff contains 8 reworded pages; the other JSON changes are only DocC key-order churn.
• Finding 1 was already covered by ddc096a. Finding 8 is handled in Describe all five platforms in the Ads SDK release PR body #950 (targets main).

[devin-ai-integration]

Opened #950 for the workflow-template follow-up. It targets main and only changes the generated release PR body to name all five platforms; it is separate from this release's reference updates.