diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index fc3df1a361fa..cfac2bc9d1ad 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -81,6 +81,25 @@ await sdk.startSession({ Follow the platform guide for [Web](/ads/player-integration/optiview-ads-sdk/web), [Android](/ads/player-integration/optiview-ads-sdk/android), [iOS](/ads/player-integration/optiview-ads-sdk/ios), or [React Native](/ads/player-integration/optiview-ads-sdk/react-native). If you use the OptiView Player, the legacy [OptiView Player integration](/ads/player-integration/optiview-player/) is also available. +### Player interception (opt-in) + +The example above keeps the default reactive playback. +To let the SDK hold first play for a preroll and route player controls during ads, +add `interceptPlayer: true` before loading or playing content: + +```typescript +const sdk = new OptiViewAds({ + player: new THEOplayerAdapter(player, container), + container, + interceptPlayer: true, +}); +``` + +Keep using the same player methods and events. +THEOplayer Web requires 11.15+ with `ads.registerClientSideIntegration`. +Older versions warn and keep reactive playback. +See each platform guide for its opt-in setup and limitations. + This integration plays every [ad workflow](/ads/workflows/): static assets from your CDN, VAST tags from your ad server, and Google Ad Manager — on live and VOD channels. Static assets need nothing more; for VAST or Google Ad Manager on Web, the workflow page lists the Google IMA script to add to your page. ## 4. Schedule a break diff --git a/ads/player-integration/optiview-ads-sdk/android.mdx b/ads/player-integration/optiview-ads-sdk/android.mdx index 2841c1fc73e2..5d0e0ac4b840 100644 --- a/ads/player-integration/optiview-ads-sdk/android.mdx +++ b/ads/player-integration/optiview-ads-sdk/android.mdx @@ -42,20 +42,89 @@ The app needs Java 17 and `compileSdk` 34 or later. Create the SDK with an adapter around your player, then start a session with the channel's Break Manifest URL. The example below uses the OptiView Player (THEOplayer) adapter; the other adapters work the same way: ```kotlin +import com.dolby.optiview.ads.adapter.theoplayer.THEOplayerAdapter +import com.dolby.optiview.ads.runtime.OverlayAdRenderer +import com.dolby.optiview.ads.sdk.CoroutineSchedulerTicker +import com.dolby.optiview.ads.sdk.HttpManifestSource +import com.dolby.optiview.ads.sdk.OptiViewAds +import com.dolby.optiview.ads.sdk.OptiViewAdsConfig +import com.dolby.optiview.ads.sdk.SessionConfig +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.SupervisorJob +import kotlinx.coroutines.launch + +val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main) +val contentAdapter = THEOplayerAdapter(theoPlayerView.player) val sdk = OptiViewAds( - config = OptiViewAdsConfig(player = THEOplayerAdapter(theoPlayerView.player)), - renderer = OverlayAdRenderer(adContainer), + config = OptiViewAdsConfig(player = contentAdapter), + renderer = OverlayAdRenderer(context, adContainer, contentAdapter), + manifestSource = HttpManifestSource(scope), + ticker = CoroutineSchedulerTicker(scope), + scope = scope, ) -sdk.startSession( - SessionConfig( - manifestUrl = "https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID", +scope.launch { + sdk.startSession( + SessionConfig( + manifestUrl = "https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID", + ) ) -) +} ``` From this point the SDK polls the [Break Manifest](../../concepts/break-manifest.mdx), schedules the breaks against your player's timeline, plays the ads, and reports the impressions. To verify the integration, schedule a break through the API or dashboard and confirm that it plays out. +## Player interception (opt-in) + +Interception is off by default. The existing integration example stays reactive. +For Media3, give your UI the adapter's `interceptedPlayer`, not the raw ExoPlayer. +Use that same player for app commands and listeners. Its Media3 `Player` API stays the same. + +```kotlin +val contentPlayer = ExoPlayer.Builder(context).build() +val contentAdapter = ExoPlayerAdapter(contentPlayer) +val appPlayer = contentAdapter.interceptedPlayer +playerView.player = appPlayer +val config = OptiViewAdsConfig(player = contentAdapter, interceptPlayer = true) +``` + +Pass `config` to `OptiViewAds`. Keep the integration example's renderer, manifest source and ticker. +Create the SDK and start the session before calling `appPlayer.play()`. +The SDK can hold first play for a preroll and route play, pause, seek, mute and volume during ads. + +For THEOplayer, use its adapter's player in app code: + +```kotlin +val contentAdapter = THEOplayerAdapter(theoPlayerView.player) +val appPlayer = contentAdapter.interceptedPlayer +val config = OptiViewAdsConfig(player = contentAdapter, interceptPlayer = true) +``` + +The raw `THEOplayerView.player` is not intercepted. +Only calls and listeners through `appPlayer` use interception. + +In Java, use `contentAdapter.getInterceptedPlayer()` for the UI and app. +Starting from your existing `OptiViewAdsConfig config`, preserve its options and use +the full `copy` overload to enable interception before constructing the SDK: + +```java +OptiViewAdsConfig interceptedConfig = config.copy( + config.getPlayer(), config.getAdPreload(), config.getDoubleBoxAudio(), + config.getAdInsertion(), config.getTransition(), config.getChaining(), + config.getTuneIn(), config.getBreakWarnings(), config.getPdtGraceSeconds(), + config.getPtsSource(), config.getContinueContentDuringBreak(), + config.getManifestUrlDiscovery(), config.getLiveStartPushback(), + config.getDiagnostics(), config.getDebug(), config.getGam(), + config.getDeliveryMode(), config.getAdBreakCutSafetyMarginSec(), + config.getInterceptManifestResponse(), config.getInterceptManifestRequest(), + config.getExternalPlayback(), true +); +``` + +The last argument is `interceptPlayer`. The older Java constructor leaves it off. +The older `copy` overload preserves the existing interception setting. + ## Supported players ### OptiView Player (THEOplayer) diff --git a/ads/player-integration/optiview-ads-sdk/index.mdx b/ads/player-integration/optiview-ads-sdk/index.mdx index 0c6b0e6923ca..78d3c3d14da9 100644 --- a/ads/player-integration/optiview-ads-sdk/index.mdx +++ b/ads/player-integration/optiview-ads-sdk/index.mdx @@ -52,6 +52,29 @@ Neither level holds ad server URLs or accounts. What to play, and where to fetch The SDK also exposes optional presentation settings — such as ad preloading, break chaining, and tune-in behavior — with sensible defaults. The platform pages describe the platform-specific options. +### Player interception (opt-in) + +Player interception is off by default. Existing integrations keep reactive playback. +For Web, add the option to your existing SDK configuration before loading or playing content: + +```typescript +const sdk = new OptiViewAds({ ...sdkConfig, interceptPlayer: true }); +``` + +Here, `sdkConfig` is your existing configuration, including its player adapter. +The SDK can hold first play for a preroll and route play, pause, seek, mute and volume during ads. +Your app keeps its player methods and events. + +Use the opt-in setup in the [Web](./web.mdx#player-interception-opt-in), +[Android](./android.mdx#player-interception-opt-in), +[iOS and tvOS](./ios.mdx#player-interception-opt-in), or +[React Native](./react-native.mdx#player-interception-opt-in) guide. +Android needs the adapter's `interceptedPlayer`; raw `THEOplayerView.player` is not intercepted. +AVPlayer needs `InterceptedAVPlayer`. +React-native-video needs the `/video` wrapper with native controls disabled. +Built-in, notification and Now Playing controls bypass interception. +THEOplayer Web needs 11.15+; older versions warn and keep reactive playback. + ### Session configuration | Property | Description | diff --git a/ads/player-integration/optiview-ads-sdk/ios.mdx b/ads/player-integration/optiview-ads-sdk/ios.mdx index f595ad377a24..0e15eb714665 100644 --- a/ads/player-integration/optiview-ads-sdk/ios.mdx +++ b/ads/player-integration/optiview-ads-sdk/ios.mdx @@ -56,9 +56,15 @@ targets: [ Create the SDK with an adapter around your player, then start a session with the channel's Break Manifest URL. The example below uses the OptiView Player (THEOplayer) adapter; the other adapters work the same way: ```swift +import OptiViewAdsRuntime +import OptiViewAdsAdapterTHEOplayer + +let contentAdapter = THEOplayerAdapter(player: theoplayer) let sdk = OptiViewAds( - config: OptiViewAdsConfig(player: THEOplayerAdapter(player: theoplayer)), - renderer: OverlayAdRenderer(container: adContainer) + config: OptiViewAdsConfig(player: contentAdapter), + renderer: OverlayAdRenderer(overlayContainer: adContainer, contentPlayer: contentAdapter), + manifestSource: URLSessionManifestSource(), + ticker: DispatchSchedulerTicker() ) try await sdk.startSession( @@ -70,6 +76,36 @@ try await sdk.startSession( From this point the SDK polls the [Break Manifest](../../concepts/break-manifest.mdx), schedules the breaks against your player's timeline, plays the ads, and reports the impressions. To verify the integration, schedule a break through the API or dashboard and confirm that it plays out. +## Player interception (opt-in) + +Interception is off by default. The existing integration example stays reactive. +For AVPlayer, create an `InterceptedAVPlayer` and give the same instance to your +player layer or view controller and the adapter: + +```swift +import OptiViewAdsRuntime + +let contentPlayer = InterceptedAVPlayer() +playerLayer.player = contentPlayer +let contentAdapter = AVPlayerAdapter(player: contentPlayer) +let config = OptiViewAdsConfig(player: contentAdapter, interceptPlayer: true) +``` + +Pass `config` to `OptiViewAds`. Keep the integration example's renderer, manifest source and ticker. +Create the SDK and start the session before loading or playing content. +Keep using AVPlayer methods, properties and observations on `contentPlayer`. +The SDK can hold first play for a preroll and route play, pause, seek, mute and volume during ads. +A plain `AVPlayer` does not install interception. + +For THEOplayer, keep the same player instance and use: + +```swift +let contentAdapter = THEOplayerAdapter(player: theoplayer) +let config = OptiViewAdsConfig(player: contentAdapter, interceptPlayer: true) +``` + +These setups apply to iOS and tvOS. + ## Supported players ### OptiView Player (THEOplayer) diff --git a/ads/player-integration/optiview-ads-sdk/react-native.mdx b/ads/player-integration/optiview-ads-sdk/react-native.mdx index e269d8bd7c97..4bf00b434c0d 100644 --- a/ads/player-integration/optiview-ads-sdk/react-native.mdx +++ b/ads/player-integration/optiview-ads-sdk/react-native.mdx @@ -70,6 +70,66 @@ From this point the SDK polls the [Break Manifest](../../concepts/break-manifest All configuration options, session settings, and ad events are documented in the [React Native API reference](pathname:///ads/v2/api-reference/react-native/), starting from the [`createOptiViewAds`](pathname:///ads/v2/api-reference/react-native/variables/createOptiViewAds.html) function. +## Player interception (opt-in) + +Interception is off by default. Existing setup stays reactive. +For react-native-theoplayer, enable it when creating the connector, before setting +the source or playing: + +```tsx +const ads = createOptiViewAds(player, { interceptPlayer: true }); +await ads.startSession({ manifestUrl: MANIFEST_URL }); +player.source = { sources: [{ src: CONTENT_URL, type: 'application/x-mpegurl' }] }; +player.play(); +``` + +Keep using the same THEOplayer methods and events. +With `useTHEOplayerAdsBinding`, put `interceptPlayer: true` in `adsConfig`. + +For react-native-video v6, use the SDK's `/video` wrapper. +Enable interception on both the connector and the wrapper, and pass the connector +as `ads`. Keep using react-native-video props, callbacks and ref methods: + +```tsx +import { useEffect, useState } from 'react'; +import { createOptiViewAds, useReactVideoHandle, type OptiViewAdsConnector } from '@dolby-optiview/ads-sdk-react-native'; +import { Video } from '@dolby-optiview/ads-sdk-react-native/video'; + +function ContentVideo() { + const { player, onVideoEvent } = useReactVideoHandle(); + const [ads, setAds] = useState(null); + + useEffect(() => { + if (!player) return; + const connector = createOptiViewAds(player, { interceptPlayer: true }); + setAds(connector); + void connector.startSession({ manifestUrl: MANIFEST_URL }); + return () => { + setAds(null); + void connector.destroy(); + }; + }, [player]); + + return ( +