Upgrade from v3 to v4

  • The IMA DAI SDK v4 for tvOS is now an exact subset of the iOS SDK, simplifying development for iOS developers working on tvOS.

  • Upgrading to v4 requires changing the module name to GoogleInteractiveMediaAds, creating an IMAAdDisplayContainer, and passing it along with IMAVideoDisplay to the stream request.

  • Instead of IMAStreamManager, use IMAAdsLoader to request streams and implement IMAAdsLoaderDelegate for stream initialization.

  • Handle stream events through the unified IMAStreamManagerDelegate using a switch statement to manage specific events like ad breaks.

The IMA DAI SDK and the IMA client-side SDK have been merged in version 4, and have been reworked as an exact subset of the iOS SDK. This significantly reduces the learning curve for iOS developers. As a result, some of the code required for DAI users has changed to be more consistent with our other SDKs.

This guide walks through the process required to upgrade an existing v3 implementation to the new v4 SDK.

If in doubt, consult the iOS DAI samples—the tvOS v4 API is the same (except for companions and PIP, which are unavailable on tvOS).

Change the module name

To match the iOS SDK, we've changed the module name from InteractiveMediaAds to GoogleInteractiveMediaAds.

Changes
Old 

#import <InteractiveMediaAds/InteractiveMediaAds.h>
New 

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
Old 

@import InteractiveMediaAds;
New 

@import GoogleInteractiveMediaAds;

Create the new ad container

The IMAAdDisplayContainer is responsible for managing the ad container view and companion ad slots used for ad playback.

Changes
Old There is no prior equivalent.
New 

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

Pass the IMAVideoDisplay and IMAAdDisplayContainer into the IMAStreamRequest

Now that you have a video display and IMAAdDisplayContainer, you need to pass them to the stream request so that the IMA DAI SDK can manage them.

Changes
Old 

IMALiveStreamRequest *streamRequest =
    [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey];
IMAVODStreamRequest *streamRequest =
    [[IMAVODStreamRequest alloc] initWithContentSourceID:kContentSourceID
                                                 videoID:kVideoID];
New 

IMALiveStreamRequest *streamRequest =
    [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                adDisplayContainer:self.adDisplayContainer
                                      videoDisplay:self.videoDisplay];
IMAVODStreamRequest *streamRequest =
      [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
                                                   videoId:kVideoID
                                        adDisplayContainer:self.adDisplayContainer
                                              videoDisplay:self.videoDisplay];

Request with an IMAAdsLoader

Changes
Old 

self.streamManager =
    [[IMAStreamManager alloc] initWithVideoDisplay:self.videoDisplay];
self.streamManager.delegate = self;
[self.streamManager requestStream:streamRequest];
New 

self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
[self.adsLoader requestStreamWithRequest:streamRequest];

Implement IMAAdsLoaderDelegate for stream initialization

These functions have been renamed and modified to be consistent with the iOS SDK. The relationship between stream manager and stream has also changed. In the v3 SDK, a single stream manager could be used to manage multiple streams. In v4, each stream manager can only manage a single stream.

Changes
Old 

- (void)streamManager:(IMAStreamManager *)streamManager
    didInitializeStream:(NSString *)streamID {
  NSLog(@"Stream initialized with streamID: %@", streamID);
}

- (void)streamManager:(IMAStreamManager *)streamManager
      didReceiveError:(NSError *)error {
  NSLog(@"Error: %@", error);
  [self playBackupStream];
}
New 

- (void)adsLoader:(IMAAdsLoader *)loader
    adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream initialized with streamID: %@", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader
    failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  NSLog(@"Error: %@", adErrorData.adError);
  [self playBackupStream];
}

Implement IMAStreamManagerDelegate

For consistency with the iOS SDKs, the tvOS SDK now provides a single stream manager delegate, IMAStreamManagerDelegate, for handling stream events. You now need to use a switch statement within that delegate to manage specific events.

Changes
Old 

- (void)streamManager:(IMAStreamManager *)streamManager
      adBreakDidStart:(IMAAdBreakInfo *)adBreakInfo {
  NSLog(@"Ad break started");
  self.playerViewController.requiresLinearPlayback = YES;
}

- (void)streamManager:(IMAStreamManager *)streamManager
        adBreakDidEnd:(IMAAdBreakInfo *)adBreakInfo {
  NSLog(@"Ad break ended");
  self.playerViewController.requiresLinearPlayback = NO;
}
New 

- (void)streamManager:(IMAStreamManager *)streamManager
    didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"StreamManager event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      self.playerViewController.requiresLinearPlayback = YES;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      self.playerViewController.requiresLinearPlayback = NO;
      break;
    }
    // And so on for other events.
    default:
      break;
  }
}