Google IMA on Android

THEOplayer offers support for Google IMA as an ad integration system. Users of Google Ad Manager (formerly known as DoubleClick for Publishers) should use this ad integration.

To schedule and track ads through Google IMA, you need to include the Google IMA SDK and indicate through the API that you want to use Google IMA as the ad integration.

Using Google IMA in the Android SDK consists of 3 steps:

1. Add the integration-ads-ima dependency to your module's build.gradle.
2. Use the GoogleImaIntegrationFactory to create and add a GoogleImaIntegration.
3. Use a GoogleImaAdDescription to schedule ads.

Add the integration-ads-ima dependency

Add implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+' to your module build.gradle file, as demonstrated below:

android {
    // ...
    compileOptions {
        // Required by IMA SDK v3.37.0+
        coreLibraryDesugaringEnabled = true
    }
}

dependencies {
    // ...

    implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
    implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+'

    // Required by IMA SDK v3.37.0+
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'

    // ...
}

Use the GoogleImaIntegrationFactory

tip

If you're using automatic integrations, you can skip this step.

Create a GoogleImaIntegration through the GoogleImaIntegrationFactory, and add it to your player instance, as demonstrated below:

import com.theoplayer.android.api.ads.ima.GoogleImaIntegrationFactory

val theoplayerView = THEOplayerView(context)
val imaIntegration = GoogleImaIntegrationFactory.createGoogleImaIntegration(theoplayerView)
theoplayerView.player.addIntegration(imaIntegration)

Use a GoogleImaAdDescription

Use a GoogleImaAdDescription to schedule advertisements, as demonstrated below:

val typedSource = TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
    .build()

val imaAdDescription = GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
    .timeOffset("start")
    .build()

val sourceDescription = SourceDescription.Builder(typedSource)
    .ads(imaAdDescription)
    .build()

theoplayerView.player.source = sourceDescription

More information on scheduling ads is available at How to set up VAST and VMAP ads.

Next steps

The Google IMA integration exposes events through the Ads API. More information is available at How to subscribe to ad events.

The integration exposes a number of additional methods. These are available directly on the GoogleImaIntegration object, or indirectly through player.ads.ima (only for Kotlin). For example, schedule() can be used to schedule ads dynamically, and requestAds() can be used to request ads through the native Google IMA API.

Updating the Google IMA SDK

The IMA integration depends on Google's IMA SDK for Android from Maven. By adding the THEOplayer IMA integration to your Gradle dependencies, the Google IMA SDK is also automatically added to your app.

Our integration is tested with a specific version of the Google IMA SDK, and by default Gradle will automatically add the same version to your app. However, you can overwrite this with a later version (at your own risk) by manually adding a dependency on com.google.ads.interactivemedia.v3:interactivemedia to your build.gradle.

Starting with IMA SDK version 3.37.0, coreLibraryDesugaring must be enabled in your app. Without this, your app will not build. See the Android documentation for instructions on how to enable it.

Remarks

• The release notes for the IMA SDK can be found on the IMA Android SDK release history page.
• THEOplayer internally supports IMA SDK up until a certain version across different SDKs. We regularly update the internal code to stay up to date with the latest version of IMA SDK. Later versions of IMA SDK should work as expected, however there could be cases where a fix for a breaking change or a newly introduced API is required. Please reach out to us if you require support for a more recent IMA SDK since we intend to rectify this limitation.
• The limitations documented on the support and compatibility pages of the IMA SDK also apply to THEOplayer when the IMA integration is used. You can find the support matrix of the IMA Android SDK on their website.
• You can try out the snippets mentioned here on our samples app for Android SDK.