Upgrading to the New Custom Playback

This guide will show you how to upgrade your HTML5 SDK implementation to support the new custom playback functionality. We recommend always passing in the custom video playback element to AdDisplayContainer, and that you pass the content video player as the custom playback element. This is to provide the best viewing experience of IMA video ads across all devices. The SDK will determine whether or not it will be used based on the platform playing ads. For example, the SDK will use your custom video player on pre-4.0 Android devices due to those platforms not being able to seamlessly switch between video elements during playback. This guide will show you how to upgrade from the old custom playback implementation to the latest implementation.

Prerequisites

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

A note about custom click tracking elements

The SDK's usage of the custom click tracking element also 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. Please 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.

Upgrading to the New Custom Playback

Option 1: Let the SDK handle content resume state on your behalf

This is the easier of our two options since it requires less logic and therefore less code to implement. There are three major steps you need to take for this implementation:

  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();
  ...
}

Disable your content ended listener when an ad is playing, and re-add it when content is 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. In short, 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

Along with the custom playback logic changes, 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.