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​