Friday, May 30, 2014

Changes to the IMA SDK for iOS

The IMA SDK for iOS version beta7 will introduce some changes in the way you tell the SDK about your display area and companion slots, which lays the groundwork for more versatility in displaying ads. While these new, more versatile features aren’t quite ready yet, we recommend building with beta7 so you'll be prepared to take advantage of upcoming greater versatility and extending support to future iOS platforms.

Introducing the IMAAdDisplayContainer

In the beta6 version of the SDK, the IMAAdsManager contains an adView which you add to your UI to display ads (IMAAdsManager.adView). In the beta7 version of the SDK, you will provide the SDK with a UIView in which it will display ads when they are ready. This is done via the new IMAAdDisplayContainer. This new object will also contain information about your companion ad slots (but more on that later):

  self.adDisplayContainer = [[IMAAdDisplayContainer alloc]
      initWithAdContainer:self.videoView
           companionSlots:nil];

In the example, we use the videoView as the UIView for the ad container. The SDK simply adds views to the provided UIView to display ads, so you won’t lose the required components for the content player already in the videoView. This IMAAdDisplayContainer will be passed to the IMAAdRequest, in place of the current companionSlots parameter:

  IMAAdsRequest *request =
      [[IMAAdsRequest alloc] initWithAdTagUrl:self.adTagUrlTextField.text
                           adDisplayContainer:self.adDisplayContainer
                                  userContext:nil];

Changes to the IMACompanionAdSlot

In the beta6 version of the SDK, you provide the IMAAdsRequest with an NSArray of IMACompanionSlot objects, each of which is initialized with a width and height. When ads are loaded, you add these to your UI:

  // Create your companion slots.
  NSMutableDictionary *companions = [NSMutableDictionary dictionary];
  companions[@"300x50"] =
      [[IMACompanionAdSlot alloc] initWithWidth:300 height:50];
  self.companionSlots = companions;

  ...

  // Give the companion slots to the IMAAdsRequest.
  IMAAdsRequest *request =
      [[IMAAdsRequest alloc] initWithAdTagUrl:self.adTagUrlTextField.text
                               companionSlots:[self.companionSlots allValues]
                                  userContext:nil];

  ...

  // Once ads have been loaded, display the companion ads.
  [self.smallCompanionSlot addSubview:
      ((IMACompanionAdSlot *)self.companionSlots[@"300x50"]).view];
In the beta7 version of the SDK, you will initialize the IMAAdDisplayContainer with an array of companion ad slots. You will then initialize the IMAAdsRequest with the IMAAdDisplayContainer. When ads are loaded, the SDK will fill in the companions for you: 
  // Create your companion slots.
  NSMutableDictionary *companions = [NSMutableDictionary dictionary];
  companions[@"300x50"] =
      [[IMACompanionAdSlot alloc] initWithView:self.smallCompanionSlot 
                                         width:300 
                                        height:50];
  self.companionSlots = companions;

  // Give the companion slots to the IMAAdDisplayContainer.
  self.adDisplayContainer = [[IMAAdDisplayContainer alloc]
      initWithAdContainer:self.videoView
           companionSlots:[self.companionSlots allValues]];

  // Request ads with the IMAAdDisplayContainer.
  IMAAdsRequest *request =
      [[IMAAdsRequest alloc] initWithAdTagUrl:self.adTagUrlTextField.text
                           adDisplayContainer:self.adDisplayContainer
                                  userContext:nil];

These changes will allow for continued support of YouTube-hosted ads (including TrueView), as well as allow you to provide a custom player for ads further down the road, similar to the HTML5 custom playback option. A custom ad player is not intended to be used by everyone - in fact most of you will not need it - but it will offer support for some additional features in the future.

As always, if you have any questions feel free to contact us via the support forum.

 - , IMA SDK Team