Enable VPAID 2 JavaScript creatives

The IMA HTML5 SDK supports VPAID 2 JavaScript creatives. When enabling support, there are two main differences to be aware of between the VPAID 2 spec and the way the IMA SDK supports VPAID 2. These differences don't impact player or SDK implementation code, but they are important for VPAID 2 JavaScript creative authors, as creatives may throw errors or not work as expected when rendered by the IMA HTML5 SDK.

Prerequisites

To follow along with this guide, start with an app that has the following:

  • HTML5 video player with the IMA HTML5 SDK integrated. If you don't have one, check out Set up the IMA SDK.
  • A VAST ad tag URL that points to a VPAID 2 JavaScript creative.

Helpful primers

  • If you're not familiar with VPAID 2, you can read more at IAB VPAID page.

Enable VPAID 2 support

To enable VPAID 2 JavaScript support, call the following method before initializing your AdDisplayContainer:

google.ima.settings.setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.ENABLED);
...
var adDisplayContainer = new google.ima.AdDisplayContainer(adContainerElement);
var adsLoader = new google.ima.AdsLoader(adDisplayContainer);
...

The available VPAID modes are as follows:

  • ENABLED - Allows VPAID ads with the default settings.
  • INSECURE - Allows VPAID ads in insecure mode. For more information, see IFrame security and Video player proxy element.
  • DISABLED - VPAID ads don't play. If a requested ad returns a VPAID creative, an error is thrown.

For more information on VPAID modes, see the API documentation for ImaSdkSettings.VpaidMode.

VPAID 2 support caveats

IFrame security

By default, the IMA SDK uses a secure iframe instead of a friendly iframe (same domain) or an in-page script to render VPAID 2 JavaScript creatives. This means that if a creative expects to access the DOM of the parent page, it could potentially cause an error. To render your ad in a friendly iframe instead, you can use ImaSdkSettings.setVpaidMode(...) like so:

adsLoader.getSettings().setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.INSECURE);

Video player proxy element

For security and proper mobile functionality, in ENABLED mode the IMA HTML5 SDK doesn't provide the actual video element to the ad; instead it provides a proxy element that mimics much of the functionality of the normal video element. For ad creatives that call only supported API methods, there should be no behavior changes in the rendering of the creatives. With VpaidMode.INSECURE mode, the SDK provides the video player element instead of the proxy.

Here are the methods, listeners and attributes available on the video proxy element:

Methods

  • addEventListener
  • canPlayType
  • load
  • play
  • pause
  • setattribute

Event types for addEventListener

  • abort
  • canplay
  • canplaythrough
  • click
  • durationchange
  • emptied
  • ended
  • error
  • loadeddata
  • loadedmetadata
  • loadstart
  • pause
  • play
  • playing
  • progress
  • ratechange
  • suspend
  • seeked
  • seeking
  • timeupdate
  • waiting

Attributes

  • currentTime
  • duration
  • ended
  • paused
  • playbackRate
  • src
  • type

FAQ

Are VPAID 2 JavaScript creatives supported in the iOS or Android SDKs?
The IMA HTML5 SDK is the only IMA SDK platform that supports VPAID 2 JavaScript creatives.
Does this enable VPAID creatives in the IMA HTML5 SDK?
Yes, the IMA HTML5 SDK supports VPAID 2 JavaScript creatives.