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. For Google Pod Serving, have your Google Ad Manager networkCode and the channel's customAssetKey at hand.
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 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:

val sdk = OptiViewAds(
    config = OptiViewAdsConfig(player = THEOplayerAdapter(theoPlayerView.player)),
    renderer = OverlayAdRenderer(adContainer),
)

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.

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.