HTML5 Advanced Topics

Ad rules

IMA HTML5 SDK v3 supports fully automated ad playlists. This feature will insert ad breaks into the content as specified in Doubleclick for Publishers 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 creating the AdsManager, a contentPlayback object is passed in via the getAdsManager() call. This object must have a currentTime property that returns the current playhead position of the video. If you're using an HTML5 video element to display your content, you can just pass that element to the SDK. This object is used to track the progress of the content playback so ad breaks are automatically inserted at the times specified in DFP. You'll also need to let the SDK know that you want it to handle content state on your behalf. If you want to handle content state on your own, see our guide on upgrading to the new custom playback.
    var adsRenderingSettings = new google.ima.AdsRenderingSettings();
    adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
    adsManager = adsManagerLoadedEvent.getAdsManager(
        videoContent, adsRenderingSettings); // See API reference for contentPlayback.
    
  • To ensure post-rolls are played, you need to let the SDK know when your content is finished. This is a bit tricky, because in some cases the SDK will use your video player to play ads, so you need to make sure you're only letting the SDK know when your content is finished, and not when an ad is finished. You can do that using the code below:
    var videoContent = document.getElementById('contentElement');
    var contentEndedListener = function() {adsLoader.contentComplete();};
    
    videoContent.addEventListener('ended', contentEndedListener);
    
    function onContentPauseRequested() {
      contentElement.removeEventListener('ended', contentEndedListener);
      ...
    }
    
    function onContentResumeRequested() {
      contentElement.addEventListener('ended', contentEndedListener);
      ...
    }
    
  • The CONTENT_PAUSE_REQUESTED and CONTENT_RESUME_REQUESTED events are used to pause and resume the content when ad breaks are played.
  • If your video player supports drag-to-seek, and the current time property of the video player updates while the user is dragging, the SDK can't differentiate between content progressing normally and a user seeking through the content. You must use a custom contentPlayback object as your parameter to getAdsManager(). For an example of this use case, see The Trouble with Seeking.

Note: When the content has finished playing or the user has stopped playback, be sure to call AdsLoader.contentComplete in order to signal to the SDK that the content is done. The SDK will then play the post-roll ad break, if one has been scheduled. The ALL_ADS_COMPLETED event will be raised when ALL ad breaks have been played. In addition, note that content tracking begins when init() is called and you should always call init() before playing content.

Disabling automatic playback of ad breaks

In some circumstances you may want to prevent the SDK from playing ad breaks until you're ready for them. In this scenario, you can disable automatic playback of ad breaks in favor of letting the SDK know when you're ready for an ad break to play. With this configuration, once the SDK has loaded an ad break, it will fire an AD_BREAK_READY event. When your player is ready for the ad break to start, you can call adsManager.start():

function requestAds() {}
  ...
  adsLoader.getSettings().setAutoPlayAdBreaks(false);
  ...
}

function onAdsManagerLoaded() {
  ...
  // For non-auto ad breaks, listen for ad break ready
  adsManager.addEventListener(
      google.ima.AdEvent.Type.AD_BREAK_READY,
      adBreakReadyHandler);
  ...
}

function adBreakReadyHandler() {
  // Once we're ready to play ads. To skip this ad break, simply return
  // from this handler without calling adsManager.start().
  adsManager.start();
}

Try it out

You can see a working implementation below.

Using custom ad playback

We recommend all implementations pass in the custom video playback element to ensure support of IMA video ads across all devices. Previously if a custom video element was passed into IMA, it was always used to play video ads. This usage of custom playback has been deprecated; soon we're going to use custom playback only when necessary (e.g. on devices such as iPhones or pre-4.0 Android phones).

Note: If you aren't using custom playback or implemented it prior to the 3.1.62 release of the HTML5 SDK, see our guide on upgrading to the new custom playback.

Supported video formats and browsers

HTML5 is still a new and evolving standard. As a result, support for various features differs among browsers, and there is no single default video format supported by all major browsers. The three main video formats used in the majority of browsers are H.264, WebM and Ogg Theora. Below is a list of these video formats and the browser versions which currently support them:

  • Ogg Theora (video/ogg): Chrome 3+, Firefox 3.5+
  • H.264 (video/mp4): Chrome 3+, Safari 3.1+, iOS 3.2+, Android 2.1+, Internet Explorer 11
  • HLS via M3U8 (application/x-mpegURL): iOS 3.2+, Android 3.0+
  • WebM (video/webm): Chrome 6+, Firefox 4+, Internet Explorer 11

Supported platforms for overlays

In desktop browsers and tablet devices like the iPad, the video plays within a browser environment and overlay ads show while the video is playing. However, if a video plays in fullscreen mode on the iPad, overlays are only visible when the user exits fullscreen mode.

For the iPhone, iPod, and Android phone, the video plays in a native video player. Since nothing can be rendered over the native video player, overlays are only visible once the user exits the native video player. On the iPhone and iPod, click events on the overlay are captured by the video element. As a result, overlay clickthrough doesn't work by default.

VAST event compatibility

This section lists the VAST events that are automatically reported to the server based on the information returned in the VAST response.

Fully supported

complete, creativeView, firstQuartile, impression, midpoint, pause, resume, rewind (fired when there is any significant seeking in the backward direction), start, thirdQuartile.

Partially supported

  • click

    The Click event is only sent for video ads. Clicks cannot be captured on the native fullscreen players on Android and iOS, or on desktop browsers. On Android, iPhone, and iPod, all videos play in a fullscreen player, but clicks can still be captured by an in-page click tracking element when the video is closed. However, if the video element uses native controls on the iPad, clicks cannot be captured.

  • fullscreen

    We support a simulated full screen mode, in which the video takes up the whole browser window. We consider a video to be in full screen mode when its offsetWidth and offsetHeight are at least the size of the document body. This mode is supported on all browsers. For an example of simulated full screen, download the sample.

    On the iPhone and pre-3.0 Android platforms, video will always play back in full screen mode.

  • mute, unmute

    iOS and Android only have native control of the volume. As such, we cannot determine the volume or mute state, nor are we notified of changes. Below is a list of the browser versions which do and do not support mute, unmute:

    • Supported: Firefox 3.5+, Chrome 8+, Safari 4+
    • Not supported: iOS, Android

Refer to the IAB guidelines for further details on VAST ad serving.

Cross-Origin-Resource-Sharing (CORS) for VAST

Modern browsers apply same-origin security restrictions to JavaScript network requests, meaning that a web application running from one origin cannot retrieve data served from a different origin. For VAST, this security restriction prevents JavaScript XMLHttpRequests made from JavaScript VAST rendering code from reading a VAST ad response served from a different origin.

This security restriction is meant to prevent issues where one origin is able to read data from another origin that a user may be logged into without that user's permission. The restriction poses problems for VAST served in a JavaScript environment because an ad server is often on a different domain than the ads player.

Cross-Origin Resource Sharing (CORS) headers is a W3C draft specification meant to allow sharing across different origins. To be servable in a JavaScript environment a VAST ad server's response must include the following HTTP CORS headers:

Access-Control-Allow-Origin: <origin header value>     
Access-Control-Allow-Credentials: true
This HTTP header allows an ads player on any origin to read the VAST response from the ad server origin. The value of Access-Control-Allow-Origin: should be the value of the Origin header sent with the ad request. The Access-Control-Allow-Credentials: header will ensure that cookies will be sent and received properly.

For more information, refer to the W3C Draft Specification on Cross-Origin Resource Sharing

Localizing for language and locale

The HTML5 SDK uses ImaSdkSettings.setLocale() for setting UI element text language and retrieving localized JavaScript files. Locale must be set before AdDisplayContainer and AdsLoader have been initialized and cannot be changed once those objects have been created.

google.ima.settings.setLocale('fr');
var adContainerElement = document.getElementById('adContainer');
var adDisplayContainer = new google.ima.AdDisplayContainer(adContainerElement);
var adsLoader = new google.ima.AdsLoader(adDisplayContainer);

Try it out

You can see a working implementation below.

Implementation notes

Mid-rolls on Android

As of Gingerbread (2.3), Android does not support switching the video source seamlessly during playback. If mid-rolls need to be shown, we suggest breaking your content up into chunks and showing ads before or after each chunk.

Native controls

Use of the video element's native controls is highly discouraged if the video element is to be the click tracking element as well. On many user agents, clicks on the native controls are interpreted as clicks on the video element and trigger a clickthrough. We suggest using custom video player controls when possible.

In addition, iOS does not communicate touch input to the HTML5 SDK due to the fact that these inputs are handled by native controls. As a result, overlays and click tracking elements will not work properly on the iPad if native controls are used.

Working with VPAID

The HTML5 SDK supports VPAID JS, with a few deviations from the spec. To enable VPAID JS, use the setVpaidMode() method of the AdsLoader.

VPAID JS spec deviations

IMA SDK support of VPAID JS makes two deviations from the VPAID JS spec:

  1. For security reasons, the VPAID ad is not loaded in a friendly IFRAME, but rather an untrusted IFRAME. This means that the ad cannot access the DOM of the parent website.
  2. For VPAID creators: The video element provided by the SDK is an object that proxies all calls to the actual video element. This allows for automatic playback of ads on mobile.

Reducing latency (best practices)

The key to reducing latency in your IMA-enabled web page is to do as much IMA-related set up as early as possible. You can do all of the following on your web page as early as you like before playing ads:

  • Create your AdDisplayContainer.
  • Create your AdsLoader.
  • Create your AdsRequest.
  • Request ads.
  • Obtain your AdsManager instance and register event handlers.

Doing all of the above will initialize the IMA SDK and request and parse your ads response all before the user even clicks play on your video. When you're ready to play the ads, call AdDisplayContainer.initialize() (always as the result of a user action!), then call AdsManager.init() and AdsManager.start(). For more information on making your entire page more responsive, see the tips on evaluating network performance in the Chrome documentation.

Send feedback about...

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