# OptiView Ads SDK The OptiView Ads SDK is the recommended way to integrate OptiView Ads into your application. It is **player-agnostic**: you bring your own player, and the SDK takes care of the OptiView Ads specifics: * **Break Manifest logic:** the SDK polls the channel's [Break Manifest](https://docs-preview.optiview.dolby.com/pr-861/ads/concepts/break-manifest.md) and schedules the announced breaks against your player's timeline. You do not implement any polling or scheduling yourself. * **Ad playback:** the SDK renders the scheduled ads, including the different [break layouts](https://docs-preview.optiview.dolby.com/pr-861/ads/concepts/breaks.md#layouts), on top of your content player. * **Ad tracking and analytics:** the SDK reports the ad impressions and tracking events for the ads it plays. The SDK is available for [Web](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/web.md), [Android](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/android.md), [iOS](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/ios.md), and [React Native](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/react-native.md). ## How the SDK works with your player The SDK never talks to your player directly. All player interaction goes through a small **player adapter** interface, which exposes the playback state the SDK needs — most importantly the stream's timing information (such as the `EXT-X-PROGRAM-DATE-TIME` position on a live HLS stream) that breaks are scheduled against. The SDK ships ready-made adapters for popular players on each platform, and you can implement the adapter interface yourself for any other player. ## Configuration Configuration is split into two levels: * **SDK configuration** is provided once, when you create the SDK instance. It describes your player and how ads should be presented. * **Session configuration** is provided per channel, when you start a monetization session. It identifies the channel to monetize. ### SDK configuration | Property | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `player` | The adapter that wraps your content player. **Required.** | | `container` | The element or view in which the SDK renders ads, stacked above your content player. **Required.** | | `mode` | The ad insertion model: `sgai` (server-guided, the default) or `ssai` (server-side, for streams where the ads are stitched into the media stream). | | `gam` | Google Ad Manager configuration for [Google Pod Serving](https://docs-preview.optiview.dolby.com/pr-861/ads/integrations/google/pod-serving.md): contains your `networkCode`. | | `debug` | Enables verbose logging during development. | 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. ### Session configuration | Property | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `manifestUrl` | The channel's Break Manifest URL. **Required.** See [Retrieving the required values](#retrieving-the-required-values). | | `customAssetKey` | The Google Pod Serving custom asset key of the channel. Required to play Google Ad Manager breaks. See [Google Pod Serving](https://docs-preview.optiview.dolby.com/pr-861/ads/integrations/google/pod-serving.md). | | `assetParameters` | Session-level ad parameters, merged with the break's `assetParameters` and forwarded to Google as `adTagParameters`. Use these for player-side values such as device identifiers. See [Ad tag parameters](https://docs-preview.optiview.dolby.com/pr-861/ads/integrations/google/pod-serving.md#ad-tag-parameters). | ## Retrieving the required values * **Break Manifest URL (`manifestUrl`):** every channel exposes its Break Manifest on a public endpoint. The URL follows the pattern `https://us.markers.optiview.dolby.com/manifest/v1/{orgId}/channels/{channelId}` (replace `us.` with `eu.` for the EU region), using your organization ID and the channel's ID. See the [Break Manifest endpoint](https://docs-preview.optiview.dolby.com/pr-861/ads/concepts/break-manifest.md#endpoint) for details. * **Google `networkCode` and `customAssetKey`:** these come from your Google Ad Manager setup. See the [Google Ad Manager prerequisites](https://docs-preview.optiview.dolby.com/pr-861/ads/integrations/google.md) and [Google Pod Serving](https://docs-preview.optiview.dolby.com/pr-861/ads/integrations/google/pod-serving.md). ## Choose a platform ## [📄️Web](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/web.md) [On Web, the OptiView Ads SDK works with any HLS-capable player through a player adapter. Ready-made adapters are available for the OptiView Player (THEOplayer), HLS.js, Shaka Player, and the browser's native \`\` element, and you can implement a custom adapter for any other player.](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/web.md) ## [📄️Android](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/android.md) [On Android and Android TV, the OptiView Ads SDK is a native Kotlin library that works with the OptiView Player (THEOplayer) and Media3 / ExoPlayer through player adapters, and with any other player through a custom adapter.](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/android.md) ## [📄️iOS](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/ios.md) [On iOS and tvOS, the OptiView Ads SDK is a native Swift library that works with the OptiView Player (THEOplayer) and AVPlayer through player adapters, and with any other player through a custom adapter.](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/ios.md) ## [📄️React Native](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/react-native.md) [On React Native, the OptiView Ads SDK bridges the native Android and iOS SDKs behind a typed JavaScript API. All timing-sensitive break scheduling runs natively, so playback stays smooth regardless of the JavaScript thread's load.](https://docs-preview.optiview.dolby.com/pr-861/ads/player-integration/optiview-ads-sdk/react-native.md) ## Related resources | Resource | Description | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [Break Manifest](https://docs-preview.optiview.dolby.com/pr-861/ads/concepts/break-manifest.md) | The contract between the OptiView Ads backend and the player. | | [Channels](https://docs-preview.optiview.dolby.com/pr-861/ads/concepts/channels.md) | The channel whose Break Manifest the SDK polls. | | [Breaks](https://docs-preview.optiview.dolby.com/pr-861/ads/concepts/breaks.md) | The breaks the SDK schedules and plays. | | [Google Pod Serving](https://docs-preview.optiview.dolby.com/pr-861/ads/integrations/google/pod-serving.md) | Google Ad Manager configuration for pod-served breaks. |