Skip to main content
Version: v2

OptiView Ads SDK on 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.

Prerequisites​

  1. Retrieve the channel's Break Manifest URL. See Retrieving the required values.
  2. Check which ad workflows your breaks use. On Android, static assets, VAST, and Google Ad Manager all work with the installation below; nothing extra is needed.
  3. Install the SDK together with the adapter for your player (see Installation and the player sections below).

Installation​

The SDK is published to the THEOplayer Maven repository. Add it to the repositories in settings.gradle.kts, keeping Google and Maven Central for third-party dependencies:

dependencyResolutionManagement {
repositories {
maven { url = uri("https://maven.theoplayer.com/releases") }
google()
mavenCentral()
}
}

Then add the runtime to your app module. It brings in the core and SDK layers, Media3, and the Google IMA SDK (used to play VAST and Google Ad Manager breaks) transitively; replace <version> with the SDK release you want to use:

dependencies {
implementation("com.dolby.optiview:ads-sdk-runtime:<version>")
}

The app needs Java 17 and compileSdk 34 or later.

Integration​

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:

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 = contentAdapter),
renderer = OverlayAdRenderer(context, adContainer, contentAdapter),
manifestSource = HttpManifestSource(scope),
ticker = CoroutineSchedulerTicker(scope),
scope = scope,
)

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, 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.

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:

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:

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)​

Add the THEOplayer adapter alongside the runtime:

dependencies {
implementation("com.dolby.optiview:ads-sdk-adapter-theoplayer:<version>")
}

The THEOplayerAdapter wraps the Player of a THEOplayerView. Ads are rendered in an overlay view stacked above your content player view.

Limitations:

  • Requires the THEOplayer Android SDK 11 or later, which your app provides (the adapter does not bundle it), and a valid THEOplayer license.
  • Requires Android 6.0 (API level 23) or later.

Media3 / ExoPlayer​

The ExoPlayerAdapter ships with the runtime and wraps a Media3 ExoPlayer instance. Ads are rendered in an overlay view stacked above your content player view.

Limitations:

  • Requires Media3 / ExoPlayer 1.4 or later and Android 5.0 (API level 21) or later.

Custom players​

Any other player can be integrated by implementing the SDK's PlayerAdapter interface, which exposes playback position, timing information, and basic playback controls.