Get started with the IMA DAI SDK

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 Google Cloud Video Stitcher API

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

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 registering a livestream event with the Video Stitcher API: ASSET_KEY

Download the basic example

Download and run the IMA Roku 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 Cloud Video Stitcher livestream, use the sdk.createVideoStitcherLiveStreamRequest() function. Once your DAI session is live, 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 to determine whether to construct a VOD StreamRequest or a live StreamRequest. To make it work with the Google Cloud Video Stitcher API, add a new path to construct a Cloud Video Stitcher live StreamRequest using the values generated previously.

Example

basic_example/components/MainScene.xml

<?xml version="1.0" encoding="utf-8" ?>
<component name="MainScene" extends="Scene" initialFocus = "myVideo">
<script type="text/brightscript">
<![CDATA[
  function init()
    m.video = m.top.findNode("myVideo")
    m.video.notificationinterval = 1
    m.testLiveStream = {
      title: "Livestream",
      assetKey: "c-rArva4ShKVIAkNfy6HUQ",
      apiKey: "",
      type: "live"
    }
    m.testVodStream = {
      title: "VOD stream"
      contentSourceId: "2548831",
      videoId: "tears-of-steel",
      apiKey: "",
      type: "vod"
    }
    m.testVideoStitcherLiveStream = {
      title: "Video Stitcher Livestream",
      customAssetKey: "ASSET_KEY",
      networkCode: "NETWORK_CODE",
      liveConfigId: "LIVE_CONFIG_ID",
      region: "LOCATION",
      projectNumber: "PROJECT_NUMBER",
      oAuthToken: "OAUTH_TOKEN",
      apiKey: "",
      type: "stitcherLive"
    }
    loadImaSdk()
  end function

  function loadImaSdk() as void
    m.sdkTask = createObject("roSGNode", "imasdk")
    m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
    m.sdkTask.observeField("errors", "onSdkLoadedError")

    ' Set this to the stream data you would like to play.
    selectedStream = m.testVideoStitcherLiveStream
    m.videoTitle = selectedStream.title
    m.sdkTask.streamData = selectedStream

    m.sdkTask.observeField("urlData", "urlLoadRequested")
    m.sdkTask.video = m.video
    ' Setting control to run starts the task thread.
    m.sdkTask.control = "RUN"
  end function

basic_example/components/Sdk.xml

  Sub loadStream()
    sdk = m.sdk
    sdk.initSdk()
    setupVideoPlayer()

    request = {}
    streamData = m.top.streamData
    if streamData.type = "live"
      request = sdk.CreateLiveStreamRequest(streamData.assetKey, streamData.apiKey)
    else if streamData.type = "vod"
      request = sdk.CreateVodStreamRequest(streamData.contentSourceId, streamData.videoId, streamData.apiKey)
    else if streamData.type = "stitcherLive"
      request = sdk.CreateVideoStitcherLiveStreamRequest(
        streamData.customAssetKey,
        streamData.networkCode,
        streamData.liveConfigId,
        streamData.region,
        streamData.projectNumber,
        streamData.oAuthToken
      )
    else
      request = sdk.CreateStreamRequest()
    end if

    request.player = m.player
    request.adUiNode = m.top.video

    requestResult = sdk.requestStream(request)
    If requestResult <> Invalid
      print "Error requesting stream ";requestResult
    Else
      m.streamManager = Invalid
      While m.streamManager = Invalid
        sleep(50)
        m.streamManager = sdk.getStreamManager()
      End While
      If m.streamManager = Invalid or m.streamManager["type"] <> Invalid or m.streamManager["type"] = "error"
        errors = CreateObject("roArray", 1, True)
        print "error ";m.streamManager["info"]
        errors.push(m.streamManager["info"])
        m.top.errors = errors
      Else
        m.top.streamManagerReady = True
        addCallbacks()
        m.streamManager.start()
      End If
    End If
  End Sub

After you've added these changes, reload the app to request and play your custom livestream.

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

Follow the Unregister livestream events guide to end your livestream event.