Google Interactive Media Ads HTML5 SDK
Google Interactive Media Ads HTML5 SDK
VAST-IMA-Player is a convenience layer around Google Interactive Media Ads HTML5 SDK (short: IMA) which tries to make using IMA less cumbersome for common monetization usecases.
This library can be used to build a simple outstream player or it can be used to implement more complex monetization scenarios. VAST-IMA-Player can monetize any content media player (with pre-, mid and postrolls), which follows the browser-built-in HTMLMediaElement API.
Browser Support
VAST-IMA-Player works in Chrome, Firefox, Edge, iOS Safari, Android and IE11. For IE11 you have to polyfill Promise when you want to use loadImaSdk(). In case you want the auto-resizing to work in older browsers you would have to polyfill ResizeObserver.
Why
IMA supports a wide range of IAB standards, like VAST, VMAP and VPAID and it can also be used for video monetization in conjunction with non-Google ad servers.
When you want to use IMA you either take an existing video-player with an IMA ad integration or you integrate IMA on your own. In the first case you can run into the issue that you don't need all the features that the full fledged video-player provides or that you want to adjust the IMA integration of the video-player, but it is not possible to do so. Integrating IMA on your own can be quite painful and laborious, especially when you want to synchronize the various Lifecycle states.
Features
This library focuses on managing the actual media monetization lifecycle and on aligning events without hiding too many details of the underlying IMA library:
- Only relies on HTMLMediaElement and can be used in combination with e.g. HLS.js or Shaka Player.
- Does not provide any additional video-player UI. The consumer should be able to decide whether to use the native controls or to design their own.
- Provides additional events to manage the video-monetization lifecycle:
MediaStart,MediaImpression,MediaStopandMediaCuePointsChange. - Proxies HTMLMediaElement events (
timeupdate,play,pause, ...) and properties (currentTime,volume, ...) through the VAST-IMA-Player API so that the consumer does not have to implement ad & content switching in their code. On iPhone the IMA defaults to use a single video tag to play back ad and content and VAST-IMA-Player ensures that the consumer receives the appropriate ad or content data. - Proxies the properties
volume,muted,currentTimeanddurationand provides proxy methods forplay()andpause(). - Prefixes all IMA events with
Adso that they are more aligned with the VPAID 2.0 standard. - It auto-resizes the IMA ad container (but also allows manual control).
- Synchronizes volume & muted state when switching between ad and content
Limitations
- In case you want to use a non-linear ad in front of a postroll VMAP ad break you should put an empty ad break at the end of the content to avoid that Google IMA preloads the postroll during non-linear ad, which lets the nonlinear ad disappear.
- Using
loadAdsto load a VMAP with a non-linear-ad followed by a linear ad will break rendering the linear ad. IMA does not properly reset the previous nonlinear ad whenautoPlayAdBreaksis set tofalseand a manualadsManager.start()is triggered.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta
name="viewport"
content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0">
<!-- loading IMA on your own -->
<script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
<!-- and the vast-ima-player -->
<script src="https://unpkg.com/@glomex/vast-ima-player@1/dist/vast-ima-player.umd.js"></script>
<title>My VAST-IMA-Player</title>
</head>
<body>
<div id="videoContainer" style="max-width:600px; position:relative;">
<video style="width:100%; height:100%;" id="mediaElement" controls playsinline poster="https://glomex.github.io/vast-ima-player/big-buck-bunny.png" preload="none">
<source type="video/mp4" src="https://glomex.github.io/vast-ima-player/big-buck-bunny.mp4">
</video>
<!-- the ad-container needs to be placed above the video container -->
<div id="adContainer" style="position:absolute; left:0; top:0;"></div>
</div>
<button id="playAd">Play Ad</button>
<script>
var adsRenderingSettings = new google.ima.AdsRenderingSettings();
var imaPlayer = new vastImaPlayer.Player(
google.ima,
document.getElementById('mediaElement'),
document.getElementById('adContainer'),
adsRenderingSettings
);
document.getElementById('playAd').addEventListener('click', function() {
var playAdsRequest = new google.ima.AdsRequest();
playAdsRequest.adTagUrl = 'https://glomex.github.io/vast-ima-player/linear-ad.xml';
imaPlayer.playAds(playAdsRequest);
});
</script>
</body>
</html>
