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.
Select the DAI solution you're interested in
Play livestreams registered with the Google Cloud Video Stitcher API
This guide demonstrates how to use the IMA DAI SDK for HTML5 to request and play a livestream for an event registered with the Google Cloud Video Stitcher API, and how to insert an ad break during playback.
This guide expands on the basic example from the Get started guide for IMA DAI.
For information on integrating with other platforms or on using the IMA client-side SDKs, see Interactive Media Ads SDKs.
Set up a Google Cloud project
Set up a Google Cloud project and configure service accounts to access the project.
Create a configuration for a livestream event using your own content livestream or a test live stream. This guide expects an HLS stream.
Enter the following variables for use in the IMA SDK:- Location
- The Google Cloud region
where your live config was created:
LOCATION
- Project number
- The Google Cloud project number using the Video Stitcher API:
PROJECT_NUMBER
- OAuth token
A service account's short lived OAuth token with the Video Stitcher user role:
OAUTH_TOKEN
Read more about creating short-lived credentials for service accounts. The OAuth token can be reused across multiple requests as long as it has not expired.
- Network code
The Ad Manager network code for requesting ads:
NETWORK_CODE
- Live config ID
- The live config ID you specified when creating your livestream event:
LIVE_CONFIG_ID
- Custom asset key
- The Ad Manager custom asset key generated during the process of creating a
configuration for a livestream event
with the Video Stitcher API:
CUSTOM_ASSET_KEY
Configure a development environment
The IMA sample apps only demonstrate HLS stream requests. You can still use DASH
streams when constructing the VideoStitcherLiveStreamRequest
class. When
setting up your DASH-compatible player, you need to set up a listener for your
video player's progress events that can provide the video's metadata to
StreamManager.processMetadata()
.
This function takes three parameters:
type
: A string which must be set to'ID3'
for HLS streams and'urn:google:dai:2018'
for DASH streams.data
: For DASH event messages, this is the message data string.timestamp
: A number that is the event message start time for DASH streams.
Send the metadata as soon and as often as your player events can provide. If metadata is missing or not correct, the IMA DAI SDK might not trigger ad events, leading to improperly reported ad events.
Download the IMA DAI examples for HTML5 and extract the HLS.js Simple sample into a new folder. This example is a web app that you can host locally for testing purposes.
To host the example locally, navigate to the new folder, and run the following python command to start a web server:
python3 -m http.server 8000
http.server
is only available in Python 3.x. You can use any other web server,
such as the Apache HTTP Server or Node JS.
Open a web browser and navigate to localhost:8000
to see a video player.
Your browser must support the HLS.js
library.
If everything is working properly, clicking the play button on the video player begins the short film "Tears of Steel" after a short ad. This content is delivered using a video on demand (VOD) stream.
Request a livestream
To replace the sample VOD stream with your livestream, use the
VideoStitcherLiveStreamRequest
class that automatically creates an ad session with Google Ad Manager. You can
use the Google Ad Manager UI to locate the generated DAI sessions for monitoring and debugging.
In the existing sample, there are functions for requesting a VOD stream or a
livestream. To make it work with the Google Cloud Video Stitcher API, you need
to add a new function to return a
VideoStitcherLiveStreamRequest
object.
Here's an example:
// StreamManager which will be used to request ad-enabled streams.
let streamManager;
...
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(
videoElement,
adUiElement
);
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);
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);
});
}
});
videoElement.addEventListener('pause', () => {
playButton.style.display = 'block';
});
playButton.addEventListener('click', initiatePlayback);
}
function initiatePlayback() {
requestVideoStitcherStream();
playButton.style.display = "none";
playButton.removeEventListener('click', initiatePlayback);
playButton.addEventListener('click', resumePlayback);
}
...
function requestVideoStitcherStream() {
const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest();
streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID';
streamRequest.region = 'LOCATION';
streamRequest.projectNumber = 'PROJECT_NUMBER';
streamRequest.oAuthToken = 'OAUTH_TOKEN';
streamRequest.networkCode = 'NETWORK_CODE';
streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY';
streamManager.requestStream(streamRequest);
}
For local testing, if the livestream files are located in a Cloud Storage
bucket, then you need to enable
CORS for origin
http://localhost:8000
.
Reload the page. Then, you can request and play custom livestreams.
(Optional) Add streaming session options
Customize your stream request by adding session options to override the default
Cloud Video Stitcher API configuration using
VideoStitcherLiveStreamRequest.videoStitcherSessionOptions
.
If you provide an unrecognized option, the Cloud
Video Stitcher API will respond with an HTTP 400 error. Consult the
troubleshooting guide
for assistance.
For example, you can override the manifest options with the following code snippet, which requests two stream manifests with renditions ordered from lowest bitrate to highest.
...
// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
"manifestOptions": {
"includeRenditions": [
{"bitrateBps": 3000, "codecs": "hvc1.1.4.L126.B0, mp4a.40.2"},
{"bitrateBps": 2000, "codecs": "avc1.64001f, mp4a.40.2"},
],
"bitrateOrder": "ascending"
}
};
streamManager.requestStream(streamRequest);
Insert an ad break
The Google Cloud Video Stitcher API inserts ads retrieved from the ad tag for each ad break. Ad breaks are denoted in the manifest using ad markers. Ad markers are inserted by the live stream encoder.
If you are using your own live stream, you need to insert the ad marker. For more information on the supported HLS and DASH ad markers, see the ad markers documentation.
If you created a live stream using the Google Cloud Livestream API, insert an ad break channel event.
The ad is played immediately after the ad break is inserted.
Clean up
Now that you have successfully hosted a live stream using the Google Cloud Video Stitcher API and requested it using the IMA DAI SDK for HTML5, it's important to clean up any serving resources.
Follow the livestream clean up guide to remove any unneeded resources and assets.
Finally, in the terminal window where you started the Python 3 web server, use
the command ctrl+C
to end the local server.