Ad rules

SDK operation modes

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

Single ad
An ad that can be 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 play back to back when the 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 tvOS SDK supports fully automated ad playlists. This feature inserts ad breaks into the content as specified in Google Ad Manager 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 ads in Ad Manager, 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 pass an instance of IMAAVPlayerContentPlayhead to the SDK when you create your adDisplayContainer. This object is used to track the progress of the content playback so ad breaks are automatically inserted at the times specified in Ad Manager.

    With AVPlayer:

    IMAContentPlayhead *contentPlayhead =
        [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentAVPlayer];
    IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:adTagUrl
                                                  adDisplayContainer:adDisplayContainer
                                                     contentPlayhead:contentPlayhead
                                                         userContext:nil];

    Without AVPlayer:

    1. Implement the IMAContentPlayhead interface.
    2. Implement currentTime to return the current time of your video player.
    3. Change the IMAAdsManager initialization call 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 contentComplete on the IMAAdsLoader in order to signal to the SDK that the content has finished playing. The SDK then plays the post-roll ad break, if one has been scheduled. The ALL_ADS_COMPLETED event is 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.