iOS Advanced Topics

A note about the SDK architecture

The iOS SDK uses a WebView to load a JavaScript back-end. This WebView is used to make ad requests, parse responses, ping tracking URLs, and render video ads.

SDK operation modes

Depending on the ad response that the SDK receives from the ad server, it can operate in one or more modes.

Single ad
An ad that can will played at any time when the "start" message is sent to the IMAAdsManager. No special initialization is necessary to play a single ad.
Ad pod
Several ads that will play back to back when "start" message is sent to the IMAAdsManager. No special initialization is necessary to play a single ad pod.
Ad rules
A playlist of ad breaks scheduled at certain times against particular content. The start message is ignored in ad rules mode. There can be several ad breaks scheduled within a single playlist (e.g., pre-roll, mid-roll, post-roll). For further implementation details, see the Ad Rules section below.

Ad rules

IMA iOS SDK v3 supports fully automated ad playlists. This feature will insert ad breaks into the content as specified in Doubleclick for Publishers when trafficking your ads. It also greatly simplifies the video player code necessary to support ad breaks, including pre-rolls, mid-rolls and post-rolls.

  • When trafficking the ads in DFP, it is possible to specify various ad rules like "always play ad break at the beginning of the content" or "play a one minute ad break every 30 minutes of content".
  • When ads are requested, the ad server can return an ad playlist. The SDK processes the playlist and automatically schedules the ad breaks that have been specified.
  • When initializing the AdsManager, an IMAContentPlayhead object is passed in via the initializeWithContentPlayhead:adsRenderingSettings: call. If you are using an AVPlayer to display your content, you can pass an instance of IMAAVPlayerContentPlayhead to the SDK. This object is used to track the progress of the content playback so ad breaks are automatically inserted at the times specified in DFP.

    With AVPlayer:

    IMAContentPlayhead *contentPlayhead =
        [[IMAAVPlayerContentPlayhead alloc]
            initWithAVPlayer:self.contentAVPlayer];
    [self.adsManager
        initializeWithContentPlayhead:contentPlayhead
            adsRenderingSettings:nil];
        

    Without AVPlayer:

    1. Implement the IMAContentPlayhead interface.
    2. Implement currentTime to return the current time of your video player.
    3. Change your initialization call to the IMAAdsManager to use initializeWithContentPlayhead:self.
  • The IMAAdsManagerDelegate is used to pause and resume the content as ad breaks are played.

Note: When the content has finished playing or the user has stopped playback, be sure to call to call contentComplete on the IMAAdsLoader in order to signal to the SDK that the content is done. The SDK will then play the post-roll ad break, if one has been scheduled. The ALL_ADS_COMPLETED event will be raised when ALL ad breaks have been played. In addition, note that content tracking begins when IMAAdsManager's initializeWithContentPlayhead:adsRenderingSettings method is called and you should always call initializeWithContentPlayhead:adsRenderingSettings before playing content.

Configuring click-through

The IMA iOS SDK allows the user to learn more about the currently playing ad by tapping a "Learn more" button displayed in the upper right corner of the video ad player. The IMA iOS SDK supports two ways to display the website associated with the ad once the user taps "Learn more":

  • Opening Mobile Safari (default)
  • Opening an in-app web browser in a UIViewController specified.

Be sure to enable the in-app web browser, use the properties provided by IMAAdsRenderingSettings. If you wish to be notified when the in-app or system browser opens and closes, implement the IMAWebOpenerDelegate.

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  IMAAdsRenderingSettings *settings = [[IMAAdsRenderingSettings alloc] init];
  settings.webOpenerPresentingController = self.inAppBrowserViewController;
  settings.webOpenerDelegate = self;
  [self.adsManager initializeWithContentPlayhead:nil adsRenderingSettings:settings];
}

- (void)willOpenExternalBrowser {
  // Called immediately before the external browser opens.
}

- (void)willOpenInAppBrowser {
  // Called immediately before the in-app browser opens.
}

- (void)didOpenInAppBrowser {
  // Called once the in-app browser has opened.
}

- (void)willCloseInAppBrowser {
  // Called immediately before the in-app browser closes.
}

- (void)didCloseInAppBrowser {
  // Called when the in-app browser has closed.
}

Specifying desired bitrate and video formats

VAST response from the server can contain multiple media files with different bitrates and in different formats. The SDK will choose the appropriate bitrate based on the current network conditions:

  • max 300 kbit/s for cellular connection
  • unlimited for WiFi

Note: iOS does not provide any detailed information on the current network speed, so the iOS SDK tries to be conservative when on cellular connection.

If you want to specify preferred video formats and bitrate, use an IMAAdsRenderingSettings instance to pass this information at the time of Ads Manager initialization.

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  IMAAdsRenderingSettings *settings = [[IMAAdsRenderingSettings alloc] init];
  settings.bitrate = 1024;  // kbits
  settings.mimeTypes = @[ @"video/mp4", @"application/x-mpegURL"];
  [self.adsManager initializeWithContentPlayhead:nil adsRenderingSettings:settings];
}

Specifying language

The IMA SDK allows you to specify the language to be used to localize ads and the player UI controls. To do so, set the language parameter of IMASettings to the appropriate language code and include those settings when initializing the AdsLoader.

- (void)createAdsLoader {
  IMASettings *settings = [[IMASettings alloc] init];
  settings.language = "en";
  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:settings];
}

Ad server compatibility

The SDK currently supports VAST 2.0 ad responses. For all ads requests made by the SDK, CORS headers are necessary to be present on the ad server ad response. Cross-Origin Resource Sharing (CORS) headers is a W3C draft specification that allows sharing across different origins. VAST ad server's response must include the following HTTP CORS headers:

Access-Control-Allow-Origin: <origin header value>     
Access-Control-Allow-Credentials: true

This HTTP header allows an ads player on any origin to read the VAST response from the ad server origin. The value of Access-Control-Allow-Origin: should be the value of the Origin header sent with the ad request. The Access-Control-Allow-Credentials: header will ensure that cookies will be sent and received properly.

For a simple guide to add CORS, please see Enable cross-origin resource sharing.

Reducing Latency - Best Practices

The key to reducing latency in your IMA-enabled app is to do as much IMA-related set up as early as possible. You can do all of the following in your app as early as you like before playing ads:

  • Define your content playhead tracker.
  • If required, create your IMAAdsLoader. If you already have an instance of IMAAdsLoader, re-use that instance. Re-using an existing IMAAdsLoader reduces latency and ensures features like frequency capping work properly.
  • Create your IMAAdDisplayContainer.
  • Create your IMAAdsRequest.
  • Request ads.
  • Obtain your IMAAdsManager instance.
  • Create your IMAAdsRenderingSettings.
Doing all of the above will initialize the IMA SDK and request and parse your ads response all before your user even clicks play on your video. When you're ready to play the ads, initialize the IMAAdsManager via IMAAdsManager:initializeWithAdsRenderingSettings. For more information on making your entire page more responsive, see the tips on evaluating network performance in the Chrome documentation.

Supported languages

Language Code Language
af Afrikaans
am Amharic
ar Arabic
eu Basque
bn Bengali
bg Bulgarian
ca Catalan
zh_cn Chinese, Mainland China, simplified characters
zh_hk Chinese, Hong Kong, traditional characters
zh_tw Chinese, Taiwan, traditional characters
hr Croatian
cs Czech
da Danish
nl Dutch
en English
en_gb English, Great Britain
et Estonian
fil Filipino
fi Finnish
fr French
fr_ca French, Canada
gl Galician
de German
el Greek, Modern
gu Gujurati
he Hebrew
hi Hindi
hu Hungarian
is Icelandic
id Indonesian
it Italian
ja Japanese
kn Kannada
ko Korean
lv Latvian
lt Lithuanian
ms Malay
ml Malayalam
mr Marathi
no Norwegian
nb Norwegian, Bokmal
fa Persian
pl Polish
pt_br Portuguese, Brazil
pt_pt Portuguese, Portugal
ro Romanian
ru Russian
sr Serbian
sk Slovak
sl Slovenian
es Spanish
es_419 Spanish, Latin America and the Caribbean
sw Swahili
sv Swedish
ta Tamil
te Telugu
th Thai
tr Turkish
uk Ukrainian
ur Urdu
vi Vietnamese
zu Zulu

Send feedback about...

IMA SDK for iOS
Need help? Visit our support page.