Stay organized with collections
Save and categorize content based on your preferences.
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:
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:
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eThe IMA HTML5 SDK supports VPAID 2 JavaScript creatives, requiring a simple setup process outlined in the guide.\u003c/p\u003e\n"],["\u003cp\u003eKey differences exist between the VPAID 2 spec and the IMA SDK's implementation, primarily impacting creative authors.\u003c/p\u003e\n"],["\u003cp\u003eBy default, the SDK uses a secure iframe for rendering VPAID 2 creatives, but you can switch to a friendly iframe for DOM access.\u003c/p\u003e\n"],["\u003cp\u003eA video proxy element is used for security and mobile functionality, providing a subset of video element functionalities to the ad.\u003c/p\u003e\n"],["\u003cp\u003eVPAID 2 JavaScript creative support is currently exclusive to the IMA HTML5 SDK, not available in the iOS or Android SDKs.\u003c/p\u003e\n"]]],[],null,["# Enable VPAID 2 JavaScript creatives\n\nThe IMA HTML5 SDK supports VPAID 2 JavaScript creatives. Enabling support is easy, but there are two differences to be aware of between the [VPAID 2 spec](//iabtechlab.com/standards/video-player-ad-interface-definition-vpaid/) and the way the IMA SDK supports VPAID 2. These differences do not 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.\n\nPrerequisites\n-------------\n\n- HTML5 video player with the IMA HTML5 SDK integrated. If you don't have one, check out [Set up the IMA SDK](/interactive-media-ads/docs/sdks/html5/client-side).\n- A VAST ad tag URL that points to a VPAID 2 JavaScript creative.\n\nHelpful primers\n---------------\n\n- If you're not familiar with VPAID 2, you can read more at [IAB's VPAID page](//iabtechlab.com/standards/video-player-ad-interface-definition-vpaid/).\n\nEnabling VPAID 2 support\n------------------------\n\nTo enable VPAID 2 JavaScript support, call the following method before initializing your [AdDisplayContainer](/interactive-media-ads/docs/sdks/html5/client-side/reference/class/google.ima.AdDisplayContainer): \n\n```gdscript\n google.ima.settings.setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.ENABLED);\n ...\n var adDisplayContainer = new google.ima.AdDisplayContainer(adContainerElement);\n var adsLoader = new google.ima.AdsLoader(adDisplayContainer);\n ...\n```\n\nThe available VPAID modes are as follows:\n\n- `ENABLED` - Allows VPAID ads with the default settings.\n- `INSECURE` - Allows VPAID ads in insecure mode. For more information, see [IFrame security](#iframe-security) and [Video player proxy element](#proxyelement).\n- `DISABLED` - VPAID ads do not play. If a requested ad returns a VPAID creative, an error is thrown.\n\nFor more information on VPAID modes, see the API documentation for [ImaSdkSettings.VpaidMode](/interactive-media-ads/docs/sdks/html5/client-side/reference/namespace/google.ima.ImaSdkSettings#google.ima.ImaSdkSettings.VpaidMode).\n\nVPAID 2 support caveats\n-----------------------\n\n### IFrame security\n\nBy 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: \n\n```text\nadsLoader.getSettings().setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.INSECURE);\n```\n\n\u003cbr /\u003e\n\n### Video player proxy element\n\nFor 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.\n\nHere are the methods, listeners and attributes available on the video proxy element:\n\n#### Methods\n\n- `addEventListener`\n- `canPlayType`\n- `load`\n- `play`\n- `pause`\n- `setattribute`\n\n#### Event types for addEventListener\n\n- `abort`\n- `canplay`\n- `canplaythrough`\n- `click`\n- `durationchange`\n- `emptied`\n- `ended`\n- `error`\n- `loadeddata`\n- `loadedmetadata`\n- `loadstart`\n- `pause`\n- `play`\n- `playing`\n- `progress`\n- `ratechange`\n- `suspend`\n- `seeked`\n- `seeking`\n- `timeupdate`\n- `waiting`\n\n#### Attributes\n\n- `currentTime`\n- `duration`\n- `ended`\n- `paused`\n- `playbackRate`\n- `src`\n- `type`\n\nFAQ\n---\n\nAre VPAID 2 JavaScript creatives supported in the iOS or Android SDKs?\n: The IMA HTML5 SDK is the only IMA SDK platform that currently supports VPAID 2 JavaScript creatives.\n\nDoes this enable VPAID creatives in the IMA HTML5 SDK?\n: Yes, the IMA HTML5 SDK supports VPAID 2 JavaScript creatives."]]