Skip to main content

Getting started with THEOads on Android

This guide will get you started to integrate THEOads in your THEOplayer Android SDK: configure the license, update dependencies and set the source description.

Prerequisites

  1. You need to have a THEOplayer license which is compatible with THEOads. This can be done through https://portal.theoplayer.com.
  2. You need a working THEOads signaling service.
  3. Add the THEOplayer Android SDK to your project by following our Getting started guide. Make sure to set up a THEOads-compatible license in your app.
  4. Add the THEOads integration as a dependency in your module-level build.gradle file:
    dependencies {
    implementation "com.theoplayer.theoplayer-sdk-android:core:8.+"
    implementation "com.theoplayer.theoplayer-sdk-android:integration-theoads:8.+"
    }

Integration

To make use of the THEOads integration, create and add the TheoAdsIntegration to your THEOplayerView:

import com.theoplayer.android.api.THEOplayerView
import com.theoplayer.android.api.ads.theoads.TheoAdsIntegration
import com.theoplayer.android.api.ads.theoads.TheoAdsIntegrationFactory.createTheoAdsIntegration

class MyActivity : Activity() {
private lateinit var theoPlayerView: THEOplayerView
private lateinit var theoAdsIntegration: TheoAdsIntegration

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

theoPlayerView = findViewById<THEOplayerView>(R.id.theoplayer)

theoAdsIntegration = createTheoAdsIntegration(theoPlayerView)
theoPlayerView.player.addIntegration(theoAdsIntegration)
}
}

Then, configure a source containing a TheoAdDescription:

import com.theoplayer.android.api.ads.theoads.TheoAdDescription
import com.theoplayer.android.api.source.SourceDescription
import com.theoplayer.android.api.source.SourceType
import com.theoplayer.android.api.source.TypedSource

theoPlayerView.player.source = SourceDescription.Builder(
TypedSource.Builder("PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI")
.type(SourceType.HLS)
.hlsDateRange(true)
.build()
).ads(
TheoAdDescription(
networkCode = "NETWORK-CODE",
customAssetKey = "CUSTOM-ASSET-KEY",
backdropDoubleBox = "PATH-TO-DOUBLE-BOX-BACKDROP-IMAGE", // Optional
backdropLShape = "PATH-TO-L-SHAPE-BACKDROP-IMAGE", // Optional
)
).build()
  • Notice that the src is different as usual. For THEOads, a signaling server needs to be set up which acts as a proxy to parse the given manifest and insert the ad interstitials. More information can be found here.
  • The hlsDateRange flag needs to be set to true as the ad markers are done using EXT-X-DATERANGE tags.
  • The ads object needs to be a TheoAdDescription. Furthermore, the networkCode and customAssetKey needs to be set according to your configured Google account.

Integrating with Open Video UI

When using the Open Video UI for Android, you need to create and add the TheoAdsIntegration before creating your DefaultUI or UIController. You can then create a THEOads-enabled source and set it as player.source:

import androidx.activity.compose.setContent
import com.theoplayer.android.ui.rememberPlayer

setContent {
val player = rememberPlayer()
LaunchedEffect(player) {
player.theoplayerView?.let { theoPlayerView ->
val theoAdsIntegration = createTheoAdsIntegration(theoPlayerView)
theoPlayerView.player.addIntegration(theoAdsIntegration)
}

player.source = SourceDescription.Builder(
TypedSource.Builder("PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI")
.type(SourceType.HLS)
.hlsDateRange(true)
.build()
).ads(
TheoAdDescription(
networkCode = "NETWORK-CODE",
customAssetKey = "CUSTOM-ASSET-KEY"
)
).build()
}

DefaultUI(
player = player
)
}

More information