Using Custom Ad Playback

This guide assumes you've implemented the HTML5 SDK prior to version 3.1.62 released on 8/14/2014. If you've used our quickstart to do an implementation after this version was released, you do not need this guide.

The default approach to integrate the IMA HTML5 SDK into your app is to have the SDK handle all of the ad-playing logic, while your app focuses on playing content video. The HTML5 SDK also provides an interface for playing ads in your video player, called custom ad playback. The rest of this guide describes its implementation.

Custom click tracking elements

The SDK's use of the custom click tracking element has changed. Previously, if a custom click tracking element was passed in to the SDK, it was always wired to handle clicks. Now the custom click tracking element will only be clickable in mobile environments; soon the SDK will only use the custom click tracking element in non-AdSense/AdExchange ads in pre-4.0 Android or iPhone environments.

As a result, do not render your custom click tracking element over your video player as it will break the ad viewing experience by preventing clickthroughs to the ad and skip buttons. See opt_clickTrackingElement under ima.AdDisplayContainer for more information, including how to determine when the SDK is using the custom click element for clickthroughs.

Implementing custom playback

There are two options for implementing custom playback. You can either allow the SDK to handle content resume state on your behalf, or you can handle content state yourself. The sections below describe both options.

Option 1: Let the SDK handle content state for resuming play

This is the easier of our two options since it requires less logic and less code. With this option, the SDK will remove your content from the video player, put the ad into the player, and play the ad. It will then remove the ad from the video player, put your content back in, and seek the content to where it was before the ad was played (which is important for mid-rolls).

The required steps are to:

  1. Tell the SDK that you'll want it to handle content state for you.
  2. Provide the SDK with a handle to your video player.
  3. Initialize your video player as the result of a user action.
  4. Disable your content-ended event listeners during ad playback.

Tell the SDK that you'll want it to handle content resume state for you.

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  var adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;

  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoContent, adsRenderingSettings);
}

Provide the SDK with a handle to your video player.

var videoContent = document.getElementById('contentElement');

function createAdDisplayContainer() {
  adDisplayContainer =
      new google.ima.AdDisplayContainer(
          document.getElementById('adContainer'),
          videoContent);
}

Initialize your video player as the result of a user action.

function requestAds() {
  ...
  adDisplayContainer.initialize();
  videoContent.load();
  ...
}

Remove your content ended event listener when an ad begins playing, and add it again when content begins playing.

Without this step, your player will trigger post-rolls at the end of your first ad and prevent any other ads from playing.

var contentEndedListener = function() {adsLoader.contentComplete();};
videoContent.addEventListener('ended', contentEndedListener);

function onContentPauseRequested() {
  videoContent.removeEventListener('ended', contentEndedListener);
  ...
}

function onContentResumeRequested() {
  videoContent.addEventListener('ended', contentEndedListener);
  ...
}

With this code in place, you have a simple solution to support ad playback on all devices.

Option 2: Handle content state on your own

If the SDK isn't sufficiently handling your content state for you, you can handle it on your own. You'll need to do the following:

  1. Store your content video source URI locally.
  2. Save your content state when an ad starts playing.
  3. Restore your content state when ads are finished.

The code in the snippet below expands upon the code in option one. To follow this implementation, you should first implement as outlined in option one.

var contentSrc = 'http://path/to/content/video';
var lastPauseTime = 0;

var contentEndedListener = function() {adsLoader.contentComplete();};
videoContent.addEventListener('ended', contentEndedListener);

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  var adsRenderingSettings = new google.ima.AdsRenderingSettings();

  // Tell the SDK NOT to save and restore content video state on our behalf.
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = false;

  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoContent, adsRenderingSettings);
  ...
}

function onContentPauseRequested() {
  videoContent.removeEventListener('ended', contentEndedListener);
  lastPauseTime = videoContent.currentTime;
  videoContent.pause();
}

function onContentResumeRequested() {
  videoContent.addEventListener('ended', contentEndedListener);
  videoContent.src = contentSrc;
  videoContent.addEventListener('loadedmetadata', loadedMetadataHandler);
  videoContent.load();
}

function loadedMetadataHandler() {
  if (videoContent.seekable.length) {
    // Video is in a seekable state
    if (videoContent.seekable.end(0) > lastPauseTime) {
      // We can seek to the last pause time
      videoContent.currentTime = lastPauseTime;
      videoContent.removeEventListener('loadedmetadata', loadedMetadataHandler);
      videoContent.play();
    }
  } else {
    // Video isn't seekable yet, try again in 100ms
    setTimeout(loadedMetadataHandler, 100);
  }
}

New API calls

We've added the following methods and properties to help you determine which rendering mode the SDK is using:

Send feedback about...

IMA SDK for HTML5
Need help? Visit our support page.