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 Google 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 THEO ad 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.
SDKs
Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
---|---|---|---|---|---|
Yes | Yes | Yes | Yes | Yes | No |
Web SDK
To use Google IMA in the Web SDK,
- You need to include the Google IMA SDK,
- You need to specify
integration: "google-ima"
in yourAdDescription
.
Include the IMA SDK
Google IMA has a dependency on the IMA SDK. Hence, this library needs to be included. The following snippet demonstrates how the IMA SDK can be included:
<script
type="text/javascript"
src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"
></script>
Alternatively, you can include the debug version of the IMA SDK for troubleshooting, which will provide extra logs from IMA on console:
<script
type="text/javascript"
src="https://imasdk.googleapis.com/js/sdkloader/ima3_debug.js"
></script>
Specify the integration
You need to set integration to "google-ima"
, as demonstrated by the snippet below which configures a pre-roll VAST ad.
player.source = {
sources: [
{
src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
}
],
ads: [
{
integration: "google-ima",
sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
timeOffset: "start"
}
]
};
Limitations
- There's a known issue within the IMA HTML5 SDK where it does not work well with multiple VPAID ads in a VMAP. More specifically when the
ImaSdkSetting
vpaidMode
is set toenabled
and theAdsRenderingSetting
enablePreloading
is set totrue
, it will not manage to play all ads (these are the default configurations when using the Google IMA integration in THEOplayer). The production IMA SDK doesn't throw any error in this scenario, the debug SDK, however, printsVpaid Error: VPAID ad called play on video element before start was called on VPAID manager
in the console in this case. This can be resolved by either usingvpaidMode
insecure
or by disabling preloading. Both can be achieved by specifying your preference in the AdsConfiguration.
Android SDK
The usage of Google IMA differs across the two Android-based SDKs.
- The Android SDK requires you to add
GoogleImaIntegration
. - The Legacy Android SDK (4.12.x) requires you to configure the
THEOplayerConfig
correctly.
Android SDK
Using Google IMA in the Android SDK consists of 3 steps:
- Add the
integration-ads-ima
dependency to your module'sbuild.gradle
. - Use the
GoogleImaIntegrationFactory
to create and add aGoogleImaIntegration
. - 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:
dependencies {
// ...
implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+'
// ...
}
Use the GoogleImaIntegrationFactory
Create a GoogleImaIntegration
through the GoogleImaIntegrationFactory
, and add it to your player instance, as demonstrated below:
// THEOplayerView theoPlayerView = ...;
GoogleImaIntegration imaIntegration = GoogleImaIntegrationFactory.createGoogleImaIntegration(theoPlayerView);
theoPlayerView.getPlayer().addIntegration(imaIntegration);
Use a GoogleImaAdDescription
Use a GoogleImaAdDescription
to schedule advertisements,
as demonstrated below:
TypedSource typedSource = new TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
.build();
GoogleImaAdDescription imaAdDescription = new GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
.timeOffset("start")
.build();
SourceDescription sourceDescription = new SourceDescription.Builder(typedSource)
.ads(imaAdDescription)
.build();
playerView.getPlayer().setSource(sourceDescription);
Other
The available ad events are different between the Android SDK and the Legacy Android SDK (4.12.x). More information is available at "How to subscribe to ad events".
The GoogleImaIntegration
instance exposes a number of methods. For example, schedule()
can be used to schedule ads dynamically, and requestAds()
can be used to request ads through the native Google IMA API.
When you add your THEOplayer IMA dependency to your module build.gradle
file (i.e. implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+'
), we will automatically add com.google.ads.interactivemedia.v3:interactivemedia
with the version specified here. You can overwrite this with a later version of the Google IMA SDK by adding this dependency to your module build.gradle
file, but at your own risk.
Legacy Android SDK (4.12.x)
To use Google IMA in the Legacy Android SDK (4.12.x),
- You need to include the Google IMA SDK,
- You need to set
useNativeIma
totrue
in yourTHEOplayerConfiguration
. - You need to use a
GoogleImaAdDescription
.
Include the IMA SDK
You must add the Google IMA Android SDK to your Android project, as explained here.
We would 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.
implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.25.1'
Set useNativeIma 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" />