Use the IMA DAI SDK on Android

Play livestreams registered with Google Cloud Video Stitcher API

This guide demonstrates how to use the IMA DAI SDK for Android 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.

If you would like to view or follow along with a completed sample integration, download the Cloud video stitcher example.

Set up a Google Cloud project

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

Download the basic example

Download and run the IMA Android DAI Basic Example. Click the play button on the video player to start the short film "Tears of Steel", which contains ad breaks every 30 seconds.

Request a livestream

To replace the sample stream with your livestream, you need to use the ImaSdkFactory.createVideoStitcherLiveStreamRequest() to create 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 purposes.

In the existing sample, there are conditional statements for requesting a VOD stream or a livestream. To make it work with Google Cloud Video Stitcher API, you need to add a new path to return a StreamRequest created using ImaSdkFactory.createVideoStitcherLiveStreamRequest().

Here's an example:

videoplayerapp/SampleAdsWrapper.java

private sdkFactory ImaSdkFactory;
...
private enum ContentType {
  LIVE_HLS,
  LIVE_DASH,
// Add a Live HLS Google Cloud type.
  LIVE_HLS_GOOGLE_CLOUD,
  VOD_HLS,
  VOD_DASH,
}

// Set CONTENT_TYPE to the associated enum for the
// stream type you would like to test.
private static final ContentType CONTENT_TYPE =
    ContentType.LIVE_HLS_GOOGLE_CLOUD;
...

@Nullable
  private StreamRequest buildStreamRequest() {
    StreamRequest request;
    switch (CONTENT_TYPE) {
      ...
      case LIVE_HLS_GOOGLE_CLOUD:
        // Live HLS stream generated by the Google Cloud Video Stitcher API.
        request = sdkFactory.createVideoStitcherLiveStreamRequest(
          "NETWORK_CODE",
          "CUSTOM_ASSET_KEY",
          "LIVE_CONFIG_ID",
          "LOCATION",
          "PROJECT_NUMBER",
          "OAUTH_TOKEN"
        );
        request.setFormat(StreamFormat.HLS);
        return request;
    }
    // Content type not selected.
    return null;
  }
...

Reload the app to request and play your custom livestream.

(Optional) Add streaming session options

Customize your stream request by adding session options to override the default Cloud Video Stitcher API configuration using StreamRequest.setVideoStitcherSessionOptions(). 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.

public void requestAndPlayAds() {
  adsLoader.addAdErrorListener(this);
  adsLoader.addAdsLoadedListener(this);
  StreamRequest streamRequest = buildStreamRequest();

  // The following session options are examples. Use session options
  // that are compatible with your video stream.
  Map<String, Object> sessionOptions = Map.of(
    "manifestOptions", Map.of(
      "includeRenditions", List.of(
        Map.of(
          "bitrateBps", 3000, "codecs",
          "hvc1.1.4.L126.B0, mp4a.40.2"),
        Map.of(
          "bitrateBps", 2000,
          "codecs", "avc1.64001f, mp4a.40.2")
      ),
      "bitrateOrder", "ascending"
    )
  );

  /* sessionOptions JSON structure.
   * {
   *  "manifestOptions": {
   *    "includeRenditions": [
   *      {"bitrateBps": 3000, "codecs": "hvc1.1.4.L126.B0, mp4a.40.2"},
   *      {"bitrateBps": 2000, "codecs": "avc1.64001f, mp4a.40.2"},
   *    ],
   *    "bitrateOrder": "ascending"
   *  }
   * };
   */

  streamRequest.setVideoStitcherSessionOptions(sessionOptions);
  adsLoader.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.

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 Android, it's important to clean up any serving resources.

Follow the livestream clean up guide to remove any unneeded resources and assets.

Previous
Prepare for your client application to work with Google Ad Manager
Next
Chromecast