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.
Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
---|---|---|---|---|---|
Yes | Yes | Yes | Yes | Yes | No |
To use Google IMA in the Web SDK,
integration: "google-ima"
in your AdDescription
.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>
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
!)
ImaSdkSetting
vpaidMode
is set to enabled
and the AdsRenderingSetting
enablePreloading
is set to true
, 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, prints Vpaid 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 using vpaidMode
insecure
or by disabling preloading. Both can be achieved by specifying your preference in the AdsConfiguration.The usage of Google IMA differs across the two Android-based SDKs.
GoogleImaIntegration
.THEOplayerConfig
correctly.Using Google IMA in the Unified Android SDK consists of 4 steps:
build.gradle
files.unified-ads-ima
dependency to your module's build.gradle
.GoogleImaIntegrationFactory
to create and add a GoogleImaIntegration
.GoogleImaAdDescription
to schedule ads.A prerequisite of using Google IMA is to add the Kotlin dependencies.
Add org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.0
to your project build.gradle
file's buildscript
, as demonstrated below:
buildscript {
repositories {
google()
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:7.1.1'
classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.0'
}
}
Add apply plugin: 'kotlin-android'
to your module build.gradle
file, as demonstrated below:
// ...
apply plugin: 'kotlin-android'
android {
compileSdkVersion 30
// ...
}
dependencies {
// ...
}
unified-ads-ima
dependencyAdd implementation 'com.theoplayer.theoplayer-sdk-android:unified-ads-ima:+'
to your module build.gradle
file, as demonstrated below:
// ...
apply plugin: 'kotlin-android'
android {
compileSdkVersion 30
// ...
}
dependencies {
// ...
implementation 'com.theoplayer.theoplayer-sdk-android:unified:+'
implementation 'com.theoplayer.theoplayer-sdk-android:unified-ads-ima:+'
// ...
}
GoogleImaIntegrationFactory
Create a GoogleImaIntegration
through the GoogleImaIntegrationFactory
, and add it to your player instance, as demonstrated below:
// THEOplayerView playerView = ...;
GoogleImaIntegration adIntegration = GoogleImaIntegrationFactory.createGoogleImaIntegration(playerView);
playerView.getPlayer().addIntegration(adIntegration);
GoogleImaAdDescription
Use a GoogleImaAdDescription
to schedule advertisements,
as demonstrated below:
TypedSource typedSource = TypedSource.Builder
.typedSource("https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd")
.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();
playerView.getPlayer().setSource(sourceDescription);
The available ad events are different between the Unified and the WebView-based Android SDK. 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:unified-ads-ima:+'
),
we will automatically add v3.25.1 of the native Google IMA Android SDK.
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.
To use Google IMA in the WebView-based Android SDK,
useNativeIma
to true
in your THEOplayerConfiguration
.GoogleImaAdDescription
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.
implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.22.2'
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" />
You have to use a GoogleImaAdDescription
instead 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);
To use Google IMA in the iOS SDK,
useNativeIma: true
in your THEOplayerConfiguration
.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.
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.
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())
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;
THEOplayer currently supports the iOS and tvOS IMA SDK up until a certain version:
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.
integration
!)