Get started with the IMA DAI SDK

Select the DAI solution you're interested in

Full service DAI

This guide demonstrates how to play a DAI stream, using the IMA CAF DAI SDK. If you would like to view or follow along with a completed sample integration, download the example.

Before using this guide, be sure to familiarize yourself with the Chromecast Application Framework's Web Receiver protocol. This guide assumes a basic level of familiarity with CAF receiver concepts, such as message interceptors and mediaInformation objects, as well as familiarity with using the Cast Command and Control tool to emulate a CAF sender.

To use IMA DAI, you must have an Ad Manager 360 account. If you have an Ad Manager account, contact your account manager for more details. For information about signing up for Ad Manager, visit the Ad Manager Help Center.

For information on integrating with other platforms, or on using the IMA client-side SDKs, see Interactive Media Ads SDKs.

CAF DAI overview

Implementing DAI using the IMA CAF DAI SDK involves two main components as demonstrated in this guide:

StreamRequest: An object that defines a stream request to Google's advertising servers. Stream requests come in two main varieties:
- LiveStreamRequest: specifies an Asset Key, and an optional API key, as well as other optional parameters.
- VODStreamRequest: Specifies a Content Source ID, a Video ID, and an optional API key, as well as other optional parameters.
StreamManager: An object that handles communication between the video stream and the IMA DAI SDK, such as firing tracking pings and forwarding stream events to the publisher.

Prerequisites

A Cast Developer Console account with a registered test device.
A hosted web receiver app that is registered with your Cast Developer Console and which can be modified to host the code provided by this guide.
A sending app that is configured to use your web receiver app. This example uses the Cast Command and Control tool as the sender.

Configure the sender's MediaInfo objects

First, configure your sender app's MediaInfo object to include the following fields:

`contentId`		A unique identifier for this media item
`contentUrl`		The fallback stream URL to load if the DAI StreamRequest fails for any reason
`streamType`		For live streams this value should be set to `LIVE`. For VOD streams, this value should be set to `BUFFERED`
`customData`	`assetKey`	Live streams only. Identifies the livestream to be loaded
	`contentSourceId`	VOD streams only. Identifies the media feed that contains the requested stream.
	`videoId`	VOD streams only. Identifies the requested stream within the specified media feed.
	`ApiKey`	An optional API key that can be required to retrieve the stream URL from the IMA DAI SDK
	`senderCanSkip`	A boolean value to let the receiver know whether the sending device has the ability to display a skip button, enabling support for skippable ads

To configure these values in the cast command and control tool, click the Load Media tab, and set the custom load request type to LOAD. Then replace the JSON data in the text area with one of the following JSON objects:

LIVE

{
  "media": {
    "contentId": "bbb",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8",
    "streamType": "LIVE",
    "customData": {
      "assetKey": "sN_IYUG8STe1ZzhIIE_ksA",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

VOD

{
  "media": {
    "contentId": "tos",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/tos.m3u8",
    "streamType": "BUFFERED",
    "customData": {
      "contentSourceId": "2548831",
      "videoId": "tears-of-steel",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

This custom load request object can be sent to the receiver to test the following steps.

Create a basic CAF receiver

Following the CAF SDK Basic Receiver Guide, create a basic web receiver.

Your receiver's code should look like this:

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    cast.framework.CastReceiverContext.getInstance().start();
  </script>
</body>
</html>

Import the IMA DAI SDK and get the Player Manager

Add a script tag to import the IMA DAI SDK for CAF to your web receiver, just after the script loading CAF. The CAF DAI SDK is evergreen, so there is no need to set a specific version. Then in the script tag that follows, store the receiver context and player manager as constants before starting the receiver.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();

    castContext.start();
  </script>
</body>
</html>

Initialize the IMA Stream Manager

Initialize the CAF DAI SDK's Stream Manager.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    castContext.start();
  </script>
</body>
</html>

Create the load message interceptor

The CAF DAI SDK uses the CAF load message interceptor to make stream requests and replace the content URL with the final DAI stream. The message interceptor calls streamManager.requestStream() which handles setting ad breaks, requesting the stream, and replacing the existing contentURL.

There can only be one load message interceptor, so if your app requires the use of the interceptor, you need to incorporate any custom functions into the same callback.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    const getStreamRequest = (request) => null;

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, (request) => {
          return streamManager.requestStream(request, getStreamRequest(request))
              .then((request) => {
                this.broadcast('Stream request successful.');
                return Promise.resolve(request);
              })
              .catch((error) => {
                this.broadcast('Stream request failed.');
                return Promise.resolve(request);
              });
        });

    castContext.start();
  </script>
</body>
</html>

Build the stream request

To complete your CAF DAI integration, you need to build your stream request using the data that was included in the mediaInfo object from the sender.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    const getStreamRequest = (request) => {
      const imaRequestData = request.media.customData;
      let streamRequest = null;
      if (imaRequestData.assetKey) {
        // Live stream
        streamRequest = new google.ima.cast.dai.api.LiveStreamRequest();
        streamRequest.assetKey = imaRequestData.assetKey;
      } else if (imaRequestData.contentSourceId) {
        // VOD stream
        streamRequest = new google.ima.cast.dai.api.VODStreamRequest();
        streamRequest.contentSourceId = imaRequestData.contentSourceId;
        streamRequest.videoId = imaRequestData.videoId;
      }
      if (streamRequest && imaRequestData.ApiKey) {
        streamRequest.ApiKey = imaRequestData.ApiKey;
      }
      if (streamRequest && imaRequestData.senderCanSkip) {
        streamRequest.senderCanSkip = imaRequestData.senderCanSkip;
      }
      return streamRequest;
    };

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, (request) => {
          return streamManager.requestStream(request, getStreamRequest(request))
              .then((request) => {
                return Promise.resolve(request);
              })
              .catch((error) => {
                this.broadcast('Stream request failed.');
                return Promise.resolve(request);
              });
        });

    castContext.start();
  </script>
</body>
</html>

You're now able to request and playback DAI streams with Google's CAF DAI SDK. To learn about more advanced SDK features, see the other guides or download our sample receiver applications.