# 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-894/ads/player-integration/optiview-ads-sdk.md#retrieving-the-required-values).
2. For [Google Pod Serving](https://docs-preview.optiview.dolby.com/pr-894/ads/integrations/google/pod-serving.md), 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](#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 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
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](https://docs-preview.optiview.dolby.com/pr-894/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.

## 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-894/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.