Integration Document for Roku Google IMA DAI

Setup

The IMA SDK depends on the Roku Advertising Framework. To load the framework, add the following to manifest:

bs_libs_required=roku_ads_lib,googleima3

Create Stream Asset for VOD

The imaStreamInfo key is required in the asset to play content with Google IMA Player. It requires the contentSourceId and videoId to determine the specific video stream and its source. Additionally, you can configure parameters such as apiKey, type.

Parameters

Parameter	Type	Description
contentSourceId	String	The content source ID for the stream request.
videoId	String	The video ID for the stream request.
apiKey	String	This key can be used to authenticate stream requests.
type	String	This key can be used to specify type of the content either vod or live
dfp_cust_params	String	This key is optional in the asset to provide adTagParameters to stream request

Example Usage

Example usage of VOD Asset:

{
  "name": "IMA-VOD",
.
.
.
.
  "custom": {
    "dfp_cust_params": "roku_ad_keys%3D30-0.0-PU02-roku%2C30-14.0-PU03- roku%26roku_ad_query_id%3D6662004937636311054",
  },
  "imaStreamInfo": {
    "contentSourceId": "2668819",
    "videoId": "00915BB8-6481-497B-BAF2-8277DED2A703-A",
    "apiKey": "",
    "type": "vod"
  }
}

Create Stream Asset for LIVE

The imaStreamInfo key is required in the asset to play content with Google IMA Player. It requires the assetKey to determine the specific video stream and its source. Additionally, you can configure parameters such as apiKey, type.

Parameters

Parameter	Type	Description
assetKey	String	Identifier of the live stream. This is used to determine which stream should be played.
apiKey	String	This key can be used to authenticate stream requests.
type	String	This key can be used to specify type of the content either vod or live
dfp_cust_params	String	This key is optional in the asset to provide adTagParameters to stream request

Example Usage

Example usage of Live Asset:

{
  "name": "IMA-Live",
.
.
.
.
  "custom": {
    "dfp_cust_params": "roku_ad_keys%3D30-0.0-PU02-roku%2C30-14.0-PU03- roku%26roku_ad_query_id%3D6662004937636311054",
  },
  "imaStreamInfo": {
    "contentSourceId": "2668819",
    "videoId": "00915BB8-6481-497B-BAF2-8277DED2A703-A",
    "apiKey": "",
    "type": "vod"
  }
}

Create GoogleIma Ads Player

The FLAdGoogleImaPlayer component can be created programmatically as well as can be added to a Scene Graph node component directly.

flPlayer = createObject("roSGNode", "FLAdGoogleImaPlayer")

AD TAG PARAMETERS

The Ad Player exposes api for LIVE content to replace ad tag parameters. This function Replaces ad tag parameters to be used for the upcoming ad requests for a live stream. Client team only need to send the parameters that have changed. This Api dynamically update the ad targeting parameters used for upcoming ad requests on a live stream. When replacing cust_params and dfp_cust_params, the entire encoded string value must be updated.

REPLACE_AD_TAG_PARAMETERS

This function can be invoked as follows:

flPlayer.callFunc(m.flPlayerFunctions.REPLACE_AD_TAG_PARAMETERS, <uri-encoded-string>)

Playback with Ad Player

Since FLAdGoogleImaPlayer is an extension of FLPlayer it provides the same playback features as the base player. You can set PlaybackAssetto the player and invoke player control functions to perform playback.

Observering Ad Playback Events

You can listen events from FLAdGoogleImaPlayer by observing fields on the ad player node. All the node fields can be observed for change as supported with SceneGraph. Please refer player component for the complete list of fields that provide ad events.

Sample demonstrating Ad state change observation

flPlayer.observeField(flPlayerFields.AD_BREAK_STARTED, "onAdBreakStarted")
flPlayer.observeField(flPlayerFields.AD_BREAK_FINISHED, "onAdBreakEnded")
flPlayer.observeField(flPlayerFields.AD_STARTED, "onAdStarted")
flPlayer.observeField(flPlayerFields.AD_FINISHED, "onAdEnded")

sub onAdBreakStarted(event as Object)
    adBreakStarted = event.getData()
    ? "adBreakStarted: ", adBreakStarted
end sub

sub onAdBreakEnded(event as Object)
    adBreakEnded = event.getData()
    ? "adBreakEnded: ", adBreakEnded
end sub

sub onAdStarted(event as Object)
    adStarted = event.getData()
    ? "adStarted: ", adStarted
end sub

sub onAdEnded(event as Object)
    adEnded = event.getData()
    ? "adEnded: ", adEnded
end sub

Ad Metadata

FLAdBreakInfo

Represents an ad break object. This object is available on observing ad break start and end.

Property	Type	Description
adBreakID	String	Ad Break Identifier
contentTimePosition	String	Current Time of the Ad
adBreakStartTimeOffset	Double	The position of the ad break, 0 is preroll, -1 is postroll and n is midroll
duration	Double	The duration of the ad break, in seconds
totalAds	Integer	Total number of adverts in the ad break

FLAdInfo

Represents an advert object. This object is available on observing ad break start and end.

Property	Type	Description
adID	String	The identifier of the advert
sequence	Integer	The sequence of the advert
adStartTimeOffset	Double	The position of the ad break, 0 is preroll, -1 is postroll and n is midroll
duration	Double	The duration of the advert in seconds
adBreakInfo	FLAdBreakInfo	The ad break which the advert belongs to
vastProperties	FLVastProperties	Represents a VAST properties object.

VASTProperties

Represents a VAST properties object.

Property	Type	Description
adSystem	String	The name of the system
adTitle	String	The title of the Ad.
description	String	The description of the Ad
adPosition	String	The position of the Ad, can be preroll, midroll or postroll
creativeId	String	The ID of the selected creative for the ad
creativeAdId	String	The Ad-ID of the selected creative in the VAST response in ISCI code
advertiser	String	The advertiser name as defined by the serving party
companions	String	The companion ads specified in the VAST response

RAF (Roku Advertising Framework)

Since Roku mandates all channel apps that include video advertising to use RAF, the fl-ad-googleima library uses RAF by default.

RAF APIs with FLAdGoogleImaPlayer

The ad player exposes the RAF APIs as follows.

SET_CONTENT_GENRE
SET_CONTENT_ID
SET_CONTENT_LENGTH
SET_NIELSEN_GENRE
SET_NIELSEN_APP_ID

These functions can be invoked as follows:

flPlayer.callFunc(m.flPlayerFunctions.SET_CONTENT_GENRE, "Adventure, Drama", false)
flPlayer.callFunc(m.flPlayerFunctions.SET_CONTENT_ID,"<content-id>")
flPlayer.callFunc(m.flPlayerFunctions.SET_CONTENT_LENGTH, 1200)
flPlayer.callFunc(m.flPlayerFunctions.SET_NIELSEN_GENRE, "<nielsen-genre>")
flPlayer.callFunc(m.flPlayerFunctions.SET_NIELSEN_APP_ID, "<nielsen-app-id>")