Live Stream Pre-fetch

The IMA SDK can be used to monetize live streams as well as video-on-demand. For live streams, you need to make a new ad request for each ad break. Stagger these requests to ensure that all of your viewers aren't requesting ads at the same time and bogging down the ad server(s).

To help with this, the IMA SDK has the AdsRequest.liveStreamPrefetchSeconds property. This property specifies the maximum number of seconds the SDK should wait before reaching out to the ad server after you call AdsLoader.requestAds(). The actual request time will be randomized. For example, if you set AdsRequest.liveStreamPrefetchSeconds to 30, the SDK waits 0 to 30 seconds after you call AdsLoader.requestAds() to actually make the request to the server.

Live stream pre-fetch in practice

We recommend pre-fetching your next ad break as soon as an ad break completes. This ensures the maximum length of time is available for your pre-fetch window. Suppose you have 5 minutes between ad breaks. When an ad break completes, you can request your next ad break with a pre-fetch window of 290 seconds (5 minutes minus 10 seconds, to make sure the requests sent at the end of the pre-fetch window have enough time to resolve):

Objective-C


- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {

  ...

  switch (event.type) {

    ...

    case kIMAAdEvent_ALL_ADS_COMPLETED:

      IMAAdsRequest *request = [[IMAAdsRequest alloc]
             initWithAdTagUrl: self.adTagUrl
           adDisplayContainer: self.adDisplayContainer
         avPlayerVideoDisplay: self.avPlayerVideoDisplay
        pictureInPictureProxy: self.pictureInPictureProxy
                  userContext: nil];

      // set a delay between the end of the last ad
      // in the last request, and the first ad from
      // the new request
      Float64 adGap = 30;
      // make sure the request occurs at least five
      // seconds before starting the new set of ads
      request.liveStreamPrefetchSeconds = adGap - 5;
      [self.adsLoader requestAdsWithRequest:request];
      // start new ads after adGap seconds have elapsed
      dispatch_after(dispatch_time(DISPATCH_TIME_NOW, adGap * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
        [adsManager start];
      });

      break;

    ...

  }

  ...

}

Swift

func adsManager(_ adsManager: IMAAdsManager!, didReceive event: IMAAdEvent!) {
  switch event.type {

    ...

    case IMAAdEventType.ALL_ADS_COMPLETED:

      let request = IMAAdsRequest(
        adTagUrl: AdTagUrl,
        adDisplayContainer: adDisplayContainer,
        contentPlayhead: contentPlayhead,
        userContext: nil)

      // set a delay between the end of the last ad
      // in the last request, and the first ad from
      // the new request
      let adGap = 30
      // make sure the request occurs at least five
      // seconds before starting the new set of ads
      request.liveStreamPrefetchSeconds = adGap - 5
      adsLoader.requestAds(with: request)
      // start new ads after adGap seconds have elapsed
      DispatchQueue.main.asyncAfter(deadline: .now() + adGap) {
        adsManager.start()
      }

      break

    ...
  }
}