Get started

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.

Note: The IMA DAI SDK for CAF supports both HLS and DASH streams, with no implementation differences.

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.

Note: 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, which are demonstrated in this guide:

• StreamRequest: An object that defines a stream request to Google's advertising servers. StreamRequests 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

Before you begin, you need the following:

• 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. For the purposes of this example, we will use the Cast Command and Control tool as our sender.

1. 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 live stream 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": "2528370",
      "videoId": "tears-of-steel",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

This custom load request object can be sent to the receiver to test each step below

2. Create a basic CAF receiver

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

Your receiver's code should look like the following:

<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>

3. 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 below 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>

4. 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>

5. 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 will call streamManager.requestStream(), which will handle setting ad breaks, requesting the stream and replacing the existing contentURL.

Note: there can only be one load message interceptor, so if your application requires use of the interceptor, you will need to incorporate your custom functionality 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>

6. Build the stream request

To complete your CAF DAI integration, you'll 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>

… and voila! Now you are 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.