Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions ads/getting-started/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
81 changes: 75 additions & 6 deletions ads/player-integration/optiview-ads-sdk/android.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
23 changes: 23 additions & 0 deletions ads/player-integration/optiview-ads-sdk/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
40 changes: 38 additions & 2 deletions ads/player-integration/optiview-ads-sdk/ios.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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)
Expand Down
60 changes: 60 additions & 0 deletions ads/player-integration/optiview-ads-sdk/react-native.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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<OptiViewAdsConnector | null>(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 (
<Video
source={{ uri: CONTENT_URL }}
onLoad={onVideoEvent}
ads={ads}
interceptPlayer
controls={false}
showNotificationControls={false}
disableFocus
/>
);
}
```

The SDK can hold first play for a preroll and route play, pause, seek, mute and volume during ads.
Use app controls through the wrapper. Built-in controls, notification controls and
Now Playing or other system media controls bypass interception.
Disable `controls` and `showNotificationControls`.
On iOS, native fullscreen can still show built-in controls.

## Supported players

### OptiView Player (react-native-theoplayer)
Expand Down
28 changes: 28 additions & 0 deletions ads/player-integration/optiview-ads-sdk/web.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,34 @@ This integration is the same for every ad workflow. If your breaks use VAST or G

All configuration options, session settings, and ad events are documented in the [Web API reference](pathname:///ads/v2/api-reference/web/), starting from the [`OptiViewAds`](pathname:///ads/v2/api-reference/web/classes/OptiViewAds.html) class.

## Player interception (opt-in)

Interception is off by default. Leave the existing examples unchanged for reactive playback.
Add `interceptPlayer: true` to the SDK configuration before setting the source or playing:

```typescript
import { OptiViewAds, HlsJsAdapter } from '@dolby-optiview/ads-sdk';

const sdk = new OptiViewAds({
player: new HlsJsAdapter(hls, video),
container,
interceptPlayer: true,
});
await sdk.startSession({ manifestUrl: MANIFEST_URL });
hls.loadSource(CONTENT_URL);
await video.play();
```

Use the same option with `new ShakaAdapter(shakaPlayer, video)`,
`new NativeVideoAdapter(video)` or `new THEOplayerAdapter(theoplayer, playerDiv)`.
Keep the rest of your adapter and ad-player configuration.
Keep using the same player object, methods and events. For hls.js, Shaka and native video,
use the content video's transport and audio API.
The SDK can hold first play for a preroll and route play, pause, seek, mute and volume during ads.

THEOplayer Web interception requires 11.15+ with `ads.registerClientSideIntegration`.
Older versions warn and keep reactive playback.

## Supported players

### OptiView Player (THEOplayer)
Expand Down
Loading