Google IMA on iOS

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.

To use Google IMA with the THEOplayer iOS SDK, the THEOplayer GoogleIMA Integration should be integrated. The integration is a lightweight module written in Swift, for serving advertisements from the Google IMA SDK.

info

The THEOplayer GoogleIMA integration supports both iOS and tvOS platforms.

Installation

The THEOplayer GoogleIMA integration is published on the following package managers:

Cocoapods

Simply add the following to your project's Podfile:

pod 'THEOplayer-Integration-GoogleIMA'

The above entry automatically manages the fetching of the IMA SDK dependency.

If you would want to set a specific version for the IMA SDK, replace the Podfile entry with:

pod 'THEOplayer-Integration-GoogleIMA/Base'
pod 'GoogleAds-IMA-iOS-SDK', '3.31.0' # specify the desired version
# or
pod 'GoogleAds-IMA-tvOS-SDK', '4.16.0' # specify the desired version

Swift Package Manager

Please check the installation instruction found here.

info

This will not get the IMA SDK, but only the THEOplayer IMA integration. The IMA SDKs can be found at https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios and https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos. You should add these to your Xcode project's Package Dependencies for SPM to fetch.

Minimum supported IMA SDK versions

The THEOplayer GoogleIMA integration requires a minimum IMA SDK version of 3.31.0 for iOS and 4.16.0 for tvOS. Using an older version will result in compilation errors due to new APIs used by the integration.

Import

Import the framework in the source files where it will be used:

import THEOplayerGoogleIMAIntegration

You will also need the THEOplayer core SDK since the THEOplayer GoogleIMA integration extends its functionality.

To import the THEOplayer core SDK framework add:

import THEOplayerSDK

Usage

Initialize the integration and pass it to the THEOplayer instance:

let configBuilder = THEOplayerConfigurationBuilder()
configBuilder.license = "your_theoplayer_license"
let theoplayer = THEOplayer(configuration: configBuilder.build()
let imaIntegration = GoogleIMAIntegrationFactory.createIntegration(on: theoplayer)
theoplayer.addIntegration(imaIntegration)

Optionally, the createIntegration accepts a configuration argument of type IMASetting:

import GoogleInteractiveMediaAds // required to access definitions such as `IMASettings`
..
..
..
let settings = IMASettings()
settings.language = "en"
let imaIntegration = GoogleIMAIntegrationFactory.createIntegration(on: theoplayer, with: settings)

Define a GoogleImaAdDescription in your source object to specify the advertisement:

let adSrc = "https://cdn.theoplayer.com/demos/ads/vast/dfp-preroll-skip-5s.xml"
let adDescription = GoogleImaAdDescription(src: adSrc)
// or
let adDescriptionWithOffset = GoogleImaAdDescription(src: adSrc, timeOffset: "10")

The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter.

Finally, we pass the ad description to the player either by setting it in the source:

let source = "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"
let mimeType = "application/x-mpegurl"
let typedSource = TypedSource(src: source, type: mimeType)
let sourceDescription = SourceDescription(source: typedSource, ads: [adDescription])
theoplayer.source = sourceDescription

Or by calling the ad schedule API:

theoplayer.ads.schedule(adDescription: adDescription)

A VAST ad without a timeOffset argument in the description will be scheduled to play at the player's currentTime. If the source is not loaded yet, it will be scheduled as a preroll.

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

Limitations

1. Prerolls must be loaded after the player view is fully rendered and ready. This means attempting to load the ad in the viewDidLoad lifecycle will result in a failed request.
2. There is a known bug by Apple that throws runtime warnings concerning the main thread. If you run into this warning while using the IMA SDK, please check this thread for more information.
3. When using SwiftUI, make sure to wrap the THEOplayer in a UIViewControllerRepresentable rather than a UIViewRepresentable, as the Google IMA SDK requires a UIViewController as a precondition before making ad requests. Otherwise, the ads will not play.

Remarks

• The release notes for the IMA SDK can be found on the IMA iOS 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 iOS SDK on their website.
• You can try out the snippets mentioned here on our samples app for iOS SDK.