# 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](https://docs-preview.optiview.dolby.com/pr-981/ads/player-integration/optiview-ads-sdk.md#retrieving-the-required-values).
2. Check which [ad workflows](https://docs-preview.optiview.dolby.com/pr-981/ads/player-integration/optiview-ads-sdk.md#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](#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:

```kotlin
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](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/live/vast.md) and [Google Ad Manager](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/live/google-ad-manager.md) breaks) transitively; replace `<version>` with the SDK release you want to use:

```kotlin
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:

```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 = 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](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/break-manifest.md), 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)

Add the THEOplayer adapter alongside the runtime:

```kotlin
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`](https://docs-preview.optiview.dolby.com/pr-981/ads/v2/api-reference/android/ads-sdk-core/com.dolby.optiview.ads.core/-player-adapter/index) interface, which exposes playback position, timing information, and basic playback controls.
