Wrapper for IMA SDK. IMA Wrapper is a convenience layer around Google Interactive Media Ads (IMA SDK for HTML5) which tries to make using IMA less cumbersome for common monetization use cases.
This SDK can be used to create a simple in-stream/out-stream video ad player, or to implement more complex monetization scenarios such as:
- Creating multiple instances of the IMA SDK to request multiple ad requests at the same time (in parallel)
- Integration with VPAID
NOTE: If you have already included the ima3.js script, the wrapper will check the IMA client side SDK version if it was included and will use it, if not, the wrapper will try to load ima3.js from //imasdk.googleapis.com/js/sdkloader/ima3.js.
Table of Contents
import IMAWrapper from 'ima-wrapper';
// Get your HTML element for ad container
const adContainer = document.getElementById('ad-container');
// Get your video element
const videoElement = document.getElementById('video-element');
// Define IMA wrapper, pass ad container and video element
const adsManager = new IMAWrapper(adContainer, videoElement, (error) => {
if(error) {
console.log(error);
return;
}
});
// Subscribe for events
// AdsManagerLoaded
adsManager.addEventListener('AdsManagerLoaded', function() {
// Get height and width of your video element
let width = videoElement.clientWidth;
let height = videoElement.clientHeight;
let viewMode = 'normal'; // fullscreen
// Init
try {
adsManager.init(width, height, viewMode);
} catch (adError) {
// Play your context without ads, if an error occurs
}
});
// AdError
adsManager.addEventListener('AdError', function(adError) {
if(adsManager) {
// Removes ad assets loaded at runtime that need to be properly removed at the time of ad completion
// and stops the ad and all tracking.
adsManager.abort();
}
// ...
});
// AdLoaded
adsManager.addEventListener('AdLoaded', function(adEvent) {
// Ad loaded, awaiting start
// Check if ad type is linear
if(adEvent.isLinear()) {
try {
// Start ad
adsManager.start();
} catch (adError) {
// Play video content without ads in case of error
}
} else {
// Ad is not linear
}
});
// AdStarted
adsManager.addEventListener('AdStarted', function() {
// Pause your video content
videoElement.pause();
});
// ...
// AdDurationChange
// AdSizeChange
// AdImpression
// AdVideoStart
// AdVideoFirstQuartile
// AdVideoMidpoint
// AdVideoThirdQuartile
// AdVideoComplete
// AdPaused
// AdPlaying
// AdStopped
// AdSkipped
// AdClickThru
// ...
// AllAdsCompleted
adsManager.addEventListener('AllAdsCompleted', function() {
// Play your video content
videoElement.play();
});
// VAST tag url
let vastUrl = 'your VAST tag url';
// Request Ads
adsManager.requestAds(vastUrl);
/*
// VAST XML
let vastXML = `<?xml version="1.0" encoding="UTF-8"?>
<VAST version="2.0">
<Error><![CDATA[http://example.com/empty-no-ad]]></Error>
</VAST>`;
adsManager.requestAds(vastXML);
*/A pre-bundled version of ima-wrapper is available: ima-wrapper.js [minified].
You can add the script directly to your page and access the library's components through the adserve.tv object.
<script src="ima-wrapper.js"></script>// Get your HTML elements for ad container and video element
const adContainer = document.getElementById('ad-container');
const videoElement = document.getElementById('video-element');
// Define IMA wrapper, pass ad container and video element
const adsManager = new adserve.tv.IMAWrapper(adContainer, videoElement, (error) => {
if(error) {
console.log(error);
return;
}
});ima-wrapper is available as an NPM package and can be easily installed with:
$ npm i ima-wrapper
$ git clone https://github.com/basil79/ima-wrapper.git
$ cd ima-wrapper
$ npm ci
To build the project for development:
$ npm run build:dev
To build the project for production:
$ npm run build:prod
This will generate the following file:
./dist/ima-wrapper.js- Minified browser production code
$ npm start
Then navigate to: http://localhost:8087 in your browser
ima-wrapper is supported all modern browsers.
See CONTRIBUTING