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 reads the channel's Break Manifest — polling it on a live stream, fetching it once for a VOD asset — 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, 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, Android, iOS, and React Native.

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 that breaks are scheduled against: the EXT-X-PROGRAM-DATE-TIME position on a live HLS stream, or the playback position in a VOD asset. The SDK ships ready-made adapters for popular players on each platform, and you can implement the adapter interface yourself for any other player.

Ad workflows

The SDK plays whatever the breaks on your channel carry, for live and VOD channels alike, and picks the delivery mode — server-guided or server-side — that the channel sets for the device. Each asset in a break uses one of three ad sources, and one channel can mix them:

Ad source	Live	VOD	What the break carries	What your app needs on top of the platform integration
Static assets	Live	VOD	Direct URLs to video or image creatives, hosted on your CDN.	Nothing.
Your ad server (VAST)	Live	VOD	A VAST tag URL from your ad server.	On Web, Google's client-side IMA SDK (ima3.js) on the page. Nothing on Android, iOS, React Native.
Google Ad Manager	Live	VOD	An ad pod decisioned by Google Ad Manager.	On Web, Google's IMA DAI SDK (ima3_dai.js) on the page. Nothing on Android, iOS, React Native.

The platform guides cover the integration that every workflow shares: installing the SDK, wrapping your player, and starting a session. The Ad workflows section describes how to set up breaks for each ad source on live and VOD, which layouts it supports, and how to troubleshoot it.

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.

Neither level holds ad server URLs or accounts. What to play, and where to fetch it from, comes from the channel's Break Manifest — including the delivery mode and the settings for Google Ad Manager.

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	Optional. The ad insertion model: sgai (server-guided) or ssai (server-side, for streams where the ads are stitched into the media stream). By default the SDK uses the mode the channel's delivery rules set for the device, and sgai when there are none; set it only to override the channel.
gam	Optional. Google Ad Manager configuration. Google Ad Manager starts automatically when the Break Manifest carries a Google configuration. See Google Ad Manager.
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.
assetParameters	Session-level ad targeting parameters: appended to static asset and VAST tag URLs, or sent to Google as adTagParameters. See Ad targeting parameters.

Retrieving the required values

The Break Manifest URL is the only value your app needs:

• 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 for details.

You do not configure ad server values in the app. VAST tag URLs are set on the breaks, and for Google Ad Manager the network code and the Google asset keys are configured on the channel and delivered to the SDK through the Break Manifest.

Next steps

📄️Web

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.

📄️Android

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.

📄️iOS

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.

📄️React Native

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.

Related resources

Resource	Description
Break Manifest	The contract between the OptiView Ads backend and the player.
Channels	The channel whose Break Manifest the SDK polls.
Breaks	The breaks the SDK schedules and plays.
Ad targeting parameters	Passing targeting parameters to VAST tags and Google.