Google IMA

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

Scheduling and tracking ads through the Googla IMA ad integration is similar to the default ad integration, so you're advised to read through "How to set-up VAST and VMAP. The main difference with the default integration is that you need to indicate through the API that you want to use Google IMA as the ad integration, and that you need to include the Google IMA SDK.

Table of Contents

• SDKs
• Web SDK
• Android (TV) SDK
• iOS (tvOS) SDK
• Remarks

SDKs

Web SDK

To use Google IMA in the Web SDK,

1. You need to include the Google IMA SDK
2. You need to specify integration: "google-ima" in your AdDescription.

Include the IMA SDK

Google IMA has a dependency on the IMA SDK. Hence, this library needs to be included. The following snippets demonstrates how this SDK can be included.

<script
  type="text/javascript"
  src="//imasdk.googleapis.com/js/sdkloader/ima3.js"
></script>

Specify the integration

You have to set integration to "google-ima", as demonstrated by the snippet below which configures a pre-roll VAST ad.

player.source = {
  "sources": [
    {
      "src": "//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
    }
  ],
  "ads": [
    {
      "integration": "google-ima",
      "sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml",
      "timeOffset": "start"
    }
  ]
}

(Tip: try out some of the other snippets mentioned at "How to set-up VAST and VMAP, but don't forget to include the IMA SDK and to specify the integration!)

Android SDK

To use Google IMA in the Android SDK,

1. You need to include the Google IMA SDK
2. You need to set googleIMA: true in your THEOplayerConfiguration.
3. You need to use a GoogleImaAdDescription

Include the IMA SDK

You must add the Google IMA Android SDK to your Android project, as explained at https://github.com/googleads/googleads-ima-android/releases.

We'd recommend adding the following gradle dependency to your gradle file, as demonstrated below, near the place where THEOplayer .aar file is included in the same file.

compile 'com.google.ads.interactivemedia.v3:interactivemedia:3.22.2'

Set googleIMA to true

Google IMA has to be enabled by setting the useNativeIma to true, as demonstrated by the snippet below.

THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
    .ads(
            new AdsConfiguration.Builder().googleImaConfiguration(
                    new GoogleImaConfiguration.Builder().useNativeIma(true).build()
            ).build()
    )
    .build();

Alternatively, if you specify your THEOplayerView through XML, you must configure it there, as demonstrated below.

<com.theoplayer.android.api.THEOplayerView
    android:id="@+id/theoPlayerView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:adGoogleImaNative="true"
    app:layout_behavior="@string/appbar_scrolling_view_behavior" />

Use a GoogleImaAdDescription

You have to use a GoogleImaAdDescriptioninstead of a THEOAdDescription. The snippet below demonstrates how you could schedule a pre-roll VAST ad.

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

AdDescription ad = GoogleImaAdDescription.Builder.googleImaAdDescription("//cdn.theoplayer.com/demos/ads/vast/vast.xml")
    .timeOffset("start").build();

SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription(typedSource)
    .ads(ad)
    .build();
theoplayerView.getPlayer().setSource(sourceDescription);

iOS SDK

To use Google IMA in the iOS SDK,

1. You need to include the Google IMA SDK
2. You need to set useNativeIma: true in your THEOplayerConfiguration.
3. You need to use a GoogleImaAdDescription

An example for the iOS SDK is available at https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-IMA. An example for the tvOS SDK is available at https://github.com/THEOplayer/samples-tvos-sdk/tree/master/Google-IMA.

Note that some limitations may apply.

Include the IMA SDK

Similar to how you add the THEOplayer "framework" (i.e. SDK) in your Xcode, you must also add the Google IMA "framework" (i.e. SDK) in your Xcode.

You can find the Google IMA iOS SDK at https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/download, which you will manually download and install.

Alternatively, you can use Cocoapods, as demonstrated at https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-IMA.

Set useNativeIma to true

Google IMA has to be enabled in the THEOplayerConfiguration, as demonstrated by the snippet below.

let playerConfig = THEOplayerConfiguration(chromeless: false, defaultCSS: false, ads: AdsConfiguration(showCountdown: true , preload: .MIDROLL_AND_POSTROLL, googleImaConfiguration: GoogleIMAConfiguration(useNativeIma: true)))

If you're using the tvOS SDK, then it's sufficient to create an empty AdsConfiguration object to enable Google IMA, as demonstrated by the snippet below.

let playerConfig = THEOplayerConfiguration(chromeless: false, ads: AdsConfiguration())

Use a GoogleImaAdDescription

You have to use a GoogleImaAdDescription instead of a THEOAdDescription. The snippet below demonstrates how you could schedule a pre-roll VAST ad.

let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")
let stream = SourceDescription(source: typedSource, ads: [GoogleImaAdDescription(src: "//cdn.theoplayer.com/demos/ads/vast/vast.xml", timeOffset: "start")])
player.source = stream;

Limitations

THEOplayer currently supports the iOS and tvOS IMA SDK up until a certain version:

• on iOS, the THEOplayer iOS SDK is compatible up to version 3.11.4 when targeting iOS 10 and above. Using version 3.11.3 allows you to target lower iOS versions. Versions 3.12.0 and above are not supported.
• on tvOS, the THEOplayer tvOS SDK is compatible up to version 4.2.3 when targeting iOS 10 and above. Using version 4.2.1 allows you to target lower iOS versions. Versions 4.3.1 and above are not supported.

Please reach out to us if you require support for a recent (unsupported) IMA SDK. We intent to rectify this limitation.

The iOS IMA SDK release history is available at https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/history. The tvOS IMA SDK release history is available at https://developers.google.com/interactive-media-ads/docs/sdks/tvos/client-side/history.

Remarks

• Tip: try out some of the other snippets mentioned at "How to set-up VAST and VMAP, but don't forget to include the IMA SDK and to specify the integration!)