# 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: ```ruby 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: ```ruby 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](https://github.com/THEOplayer/theoplayer-sdk-apple/README.md#installation). > **Info** > > This will not get the IMA SDK, but only the THEOplayer IMA integration. The IMA SDKs can be found at and . 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: ```swift 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: ```swift import THEOplayerSDK ``` ## Usage Initialize the integration and pass it to the `THEOplayer` instance: ```swift 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: ```swift 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: ```swift 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: ```swift 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: ```swift 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](https://docs-preview.optiview.dolby.com/pr-861/theoplayer/how-to-guides/ios/ads/set-up-vast-and-vmap.md). ## 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.](https://developer.apple.com/forums/thread/714467?answerId=734799022#734799022) 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](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/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](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/compatibility) on their website. * You can try out the snippets mentioned here on our [samples app for iOS SDK](https://github.com/THEOplayer/samples-ios-sdk).