Get Started

Note: Dynamic ad insertion requires that you have an Ad Manager 360 account and an account manager. Please contact your account manager if you are interested in signing up.

This guide shows you how to integrate the IMA SDK for tvOS into a new tvOS Xcode project.

Prerequisites

Before you begin, you'll need the following:

If you'd rather follow along with a finished IMA SDK integration, download BasicExample.zip.

Adding the SDK to the Xcode project

Unzip the IMA SDK downloaded from above and add the framework inside to your Xcode project. For information on adding the tvOS framework to your project, see Apple's documentation on adding an existing framework to a project.

Your first stream request

Importing the SDK

Once you've added the SDK to your project, import it in ViewController.m.

#import "ViewController.h"

@import InteractiveMediaAds;

@interface ViewController ()
...

Creating your video player

Before you can play a stream, you'll need an IMA-compatible video player. This example uses an AVPlayer inside of an AVPlayerViewController, and the AVPlayer is used to create an IMAAVPlayerVideoDisplay.

@import AVKit;
@import InteractiveMediaAds;

@interface ViewController ()

/// Holds the AVPlayer for stream playback.
@property(nonatomic, strong) AVPlayerViewController *playerViewController;

/// Used to provide the IMA SDK with a reference to the AVPlayer.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *videoDisplay;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = [[AVPlayer alloc] init];

  self.videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self presentViewController:self.playerViewController animated:false completion:nil];
}

Requesting a stream

Now that you have a video player, you can build your stream request and request a stream--and that's it! You now have a fully functional video stream.

// Live stream asset key.
static NSString *const kTestAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
// VOD content source and video IDs.
static NSString *const kContentSourceID = @"19463";
static NSString *const kVideoID = @"googleio-highlights";

static NSString *const kBackupContentPath =
    @"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/"
    @"master.m3u8";

@interface ViewController ()

/// Holds the AVPlayer for stream playback.
@property(nonatomic, strong) AVPlayerViewController *playerViewController;

/// Used to provide the IMA SDK with a reference to the AVPlayer.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *videoDisplay;

/// Main point of interaction with the SDK - used to request the stream,
/// and calls delegate methods once the stream has been initialized.
@property(nonatomic, strong) IMAStreamManager *streamManager;

@end

...

- (void)viewDidLoad {
  ...
  // Create a stream request. Use one of "Live stream request" or "VOD request".
  // Live stream request.
  IMALiveStreamRequest *streamRequest = [[IMALiveStreamRequest alloc] initWithAssetKey:kTestAssetKey];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  /*IMAVODStreamRequest *streamRequest =
      [[IMAVODStreamRequest alloc] initWithContentSourceID:kContentSourceID videoID:kVideoID];*/

  self.streamManager = [[IMAStreamManager alloc] initWithVideoDisplay:self.videoDisplay];

  [self.streamManager requestStream:streamRequest];
}

- (void)playBackupStream {
  NSURL *contentURL = [NSURL URLWithString:kBackupContentPath];
  self.playerViewController.player = [[AVPlayer alloc] initWithURL:contentURL];
  [self.playerViewController.player play];
}
...
}

Handling stream manager events

At this point your video is playing with dynamically inserted ads (DAI), and there's nothing more you need to do. However, there are some additional optional steps you can take. If you'd like, you can now listen for and handle stream manager events as follows.

@interface ViewController () <IMAStreamManagerDelegate>

- (void)viewDidLoad {
  ...
  self.streamManager = [[IMAStreamManager alloc] initWithVideoDisplay:self.videoDisplay];
  self.streamManager.delegate = self;
}

#pragma mark - Stream manager delegates

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

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

- (void)streamManager:(IMAStreamManager *)streamManager
      adBreakDidStart:(IMAAdBreakInfo *)adBreakInfo {
  NSLog(@"Stream manager event (ad break start)");
  self.playerViewController.requiresLinearPlayback = YES;
}

- (void)streamManager:(IMAStreamManager *)streamManager
        adBreakDidEnd:(IMAAdBreakInfo *)adBreakInfo {
  NSLog(@"Stream manager event (ad break complete)");
  self.playerViewController.requiresLinearPlayback = NO;
}

That's all there is to it! You're now requesting, playing, and monitoring events on a DAI stream.

Send feedback about...

IMA DAI SDK for tvOS
Need help? Visit our support page.