IMA SDKs make it easy to integrate multimedia ads into your websites and apps. IMA SDKs can request ads from any VAST-compliant ad server and manage ad playback in your apps. With IMA DAI SDKs, apps make a stream request for ad and content video—either VOD or live content. The SDK then returns a combined video stream, so that you don't have to manage switching between ad and content video within your app.
This guide demonstrates how to integrate the IMA SDK into a simple video player app. If you would like to view or follow along with a completed sample integration, download the simple example from GitHub.
Create the HTML
Create a file called dai.html
containing the following:
<html>
<head>
<script src="//cdn.jsdelivr.net/hls.js/latest/hls.min.js"></script>
<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
<script src="dai.js"></script>
<link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
<h2>IMA SDK DAI Demo (HLS.JS)</h2>
<video id="video"></video>
<div id="click"></div>
</body>
</html>
- Add library references for hls.js and the IMA DAI SDK,
respectively, using
<script>
tags. - In the body of the document, set up a
<video>
tag with a click<div>
below it, used for clickthrough. - Call
initPlayer()
in theonLoad
function to initialize your video player. (This is explained in more detail below.)
Create the CSS
Create a file called dai.css
containing the following:
#video,
#click {
width: 640px;
height: 360px;
position: absolute;
top: 35px;
left: 0;
}
#click {
cursor: pointer;
}
#banner {
width: 100%;
height: 35px;
background-color: black;
color: white;
position: absolute;
top: 0;
left: 0;
}
This establishes the styling information for the page, which is especially important for the click handler.
Create the JavaScript
Now create a new file called dai.js
. This is used by your HTML page
to perform all player logic on your page.
Initialize the StreamManager
In dai.js
, set up some variables to hold the information required
to request a stream from the DAI server.
var BACKUP_STREAM =
'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
'master.m3u8';
// Live stream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";
// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "19463";
var TEST_VIDEO_ID = "tears-of-steel";
var streamManager; // used to request ad-enabled streams.
var hls = new Hls(); // hls.js video player
var videoElement;
var clickElement;
Then, initialize StreamManager
and request a VOD stream.
function initPlayer() {
videoElement = document.getElementById('video');
clickElement = document.getElementById('click');
streamManager = new google.ima.dai.api.StreamManager(videoElement);
streamManager.setClickElement(clickElement);
streamManager.addEventListener(
[google.ima.dai.api.StreamEvent.Type.LOADED,
google.ima.dai.api.StreamEvent.Type.ERROR,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
onStreamEvent,
false);
// Timed metadata is only used for LIVE streams.
hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
if (streamManager && data) {
// For each ID3 tag in our metadata, we pass in the type - ID3, the
// tag data (a byte array), and the presentation timestamp (PTS).
data.samples.forEach(function(sample) {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, null);
// Uncomment the line below and comment out the one above to request a
// LIVE stream instead of a VOD stream.
//requestLiveStream(TEST_ASSET_KEY, null);
}
This function initializes a StreamManager
which is responsible
for requesting and managing DAI streams. The constructor takes a
video element and the resulting StreamManager
is passed a click
element: the <div>
you provide to the SDK to handle ad clicks.
Next, you need to implement event listeners for major video events.
Our simple example handles the LOADED
, ERROR
, AD_BREAK_STARTED
and AD_BREAK_ENDED
events by calling onStreamEvent()
. We construct
the onStreamEvent()
handler function below.
Finally, to support live streams, add a handler to listen to timed
metadata events and forward these events to the StreamManager
.
To work with DAI, your custom player must pass ID3 events for live streams to the IMA SDKs as shown in the sample code.
Request the stream
Add a requestVODStream()
function to handle VOD streams, and a similar
function for live streams:
function requestVODStream(cmsId, videoId, apiKey) {
var streamRequest = new google.ima.dai.api.VODStreamRequest();
streamRequest.contentSourceId = cmsId;
streamRequest.videoId = videoId;
streamRequest.apiKey = apiKey;
streamManager.requestStream(streamRequest);
}
function requestLiveStream(assetKey, apiKey) {
var streamRequest = new google.ima.dai.api.LiveStreamRequest();
streamRequest.assetKey = assetKey;
streamRequest.apiKey = apiKey;
streamManager.requestStream(streamRequest);
}
These functions create new StreamRequest
objects, either VOD or live.
The objects are interchangeable, so depending on your use case,
have your page call one of these two methods. Both methods take
an optional API key. If you're using an encrypted stream, you need to
create a DAI authentication key.
Handle stream events
Earlier you hooked up all of your event handlers to the onStreamEvent()
function. We now show how to implement that function:
function onStreamEvent(e) {
switch (e.type) {
case google.ima.dai.api.StreamEvent.Type.LOADED:
console.log('Stream loaded');
loadUrl(e.getStreamData().url);
break;
case google.ima.dai.api.StreamEvent.Type.ERROR:
console.log('Error loading stream, playing backup stream.' + e);
loadUrl(BACKUP_STREAM);
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
console.log('Ad Break Started');
videoElement.controls = false;
clickElement.style.display = 'block';
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
console.log('Ad Break Ended');
videoElement.controls = true;
clickElement.style.display = 'none';
break;
default:
break;
}
}
Our function handles stream loading and errors, as well as disabling
the player controls while an ad is playing--this is required by the
SDK. When the stream is loaded, the video player is instructed to
load and play the provided URL in the loadUrl()
function:
function loadUrl(url) {
console.log('Loading:' + url);
hls.loadSource(url);
hls.attachMedia(videoElement);
hls.on(Hls.Events.MANIFEST_PARSED, function() {
console.log('Video Play');
videoElement.play();
});
}
Congratulations, you now have a working IMA DAI implementation for HTML5.