IMA DAI SDK for Roku

Class ima

Methods

disableLogging, getStreamManager, initSdk, requestStream

Global functions that control the IMA SDK.

`disableLogging()`

Disables the SDK logging. Logging will be on by default.

`getStreamManager()`

Returns a stream manager if it available. If the stream manager is not yet availbe, Invalid is returned. If there was an error creating the stream manager, an error object is returned.

Returns object: The stream manager or error object.

`initSdk(settings)`

Initializes the SDK.

Parameter	Type	Description
`settings`	`object`	Optional IMA settings object.

`requestStream(streamRequest)`

Starts an asynchronus stream request Control returns immediately to the player after calling this method.

Returns object: an error or invalid if no error

Parameter	Type	Description
`streamRequest`	`object`

Class ima.AdBreakInfo

Fields

adPosition, duration, podIndex, timeOffset, totalAds

Methods

createAdBreakInfo

Contains info about an ad break. Passed to event callbacks by the SDK.

Properties

Name	Type	Description
`adPosition`		The index of the ad in the ad break. The index is `1` for stand alone ads.
`duration`		The maximum duration of the break in seconds, or `-1` if unknown.
`podIndex`		For live streams, returns the break ID as the pod index, or `0` for a preroll. There are no postrolls in live streams. Defaults to `-2`. For video on demand (VOD), returns the index of the ad pod. For a preroll pod, returns `0`. For midrolls, returns `1`, `2`, ..., n. For a postroll pod, returns n+1...n+x. Defaults to `0` if this ad is not part of a pod, or this pod is not part of a playlist.
`timeOffset`		The position of the pod in the content in seconds. Pre-roll returns `0`, post-roll returns `-1` and mid-rolls return the scheduled time of the pod.
`totalAds`		The total number of ads contained within this ad break. The value is `1` for stand alone ads.

`createAdBreakInfo()`

Returns ima.AdBreakInfo:

Class ima.AdEvent

Fields

AD_PERIOD_ENDED, AD_PERIOD_STARTED, COMPLETE, ERROR, FIRST_QUARTILE, ICON_FALLBACK_IMAGE_CLOSED, ICON_FALLBACK_IMAGE_SHOWN, MIDPOINT, PROGRESS, SKIPPABLE_STATE_CHANGED, SKIPPED, START, THIRD_QUARTILE

Events fired by the ads manager.

Properties

Name	Type	Description
`AD_PERIOD_ENDED`		Fired every time the stream switches from advertising or slate to content. This will be fired even when an ad is played a second time or when seeking into an ad.
`AD_PERIOD_STARTED`		Fired every time the stream switches from content to advertising or slate. This will be fired even when an ad is played a second time or when seeking into an ad.
`COMPLETE`		Fired when the ad completes playing.
`ERROR`		Fired when an error occurs.
`FIRST_QUARTILE`		Fired when the ad playhead crosses the first quartile.
`ICON_FALLBACK_IMAGE_CLOSED`		Fired when the user closes the icon fallback image dialog.
`ICON_FALLBACK_IMAGE_SHOWN`		Fired when the icon fallback image is displayed.
`MIDPOINT`		Fired when the ad playhead crosses the midpoint.
`PROGRESS`		Fired when there is an update to the progress of an ad.
`SKIPPABLE_STATE_CHANGED`		Fired when an ad skippable state changes.
`SKIPPED`		Fired when an ad is skipped.
`START`		Fired when an ad starts playing.
`THIRD_QUARTILE`		Fired when the ad playhead crosses the third quartile.

Class ima.AdInfo

Fields

adBreakInfo, adDescription, adId, adSystem, adTitle, advertiserName, companions, creativeAdId, creativeId, currentTime, dealId, duration, skipOffset, universalAdIDRegistry, universalAdIDValue, wrappers

Methods

createAdInfo

Contains info about an ad. Passed to event callbacks by the SDK.

Properties

Name	Type	Description
`adBreakInfo`		Info related to the entire break this ad is in.
`adDescription`		The description of the ad.
`adId`		The id of the ad or an empty string if unknown.
`adSystem`		The ad system supplying the creative.
`adTitle`		The title of the ad.
`advertiserName`		The advertiser name as defined by the serving party.
`companions`		The companion ads specified in the VAST response.
`creativeAdId`		The ISCI (Industry Standard Commercial Identifier) code for an ad. This is the Ad-ID of the selected creative in the VAST response.
`creativeId`		The ID of the selected creative for the ad.
`currentTime`		The current time within an ad in seconds or -1 if unknown.
`dealId`		Returns the first deal ID present in the wrapper chain for the current ad, starting from the top.
`duration`		The duration of this single ad in seconds or -1 if unknown.
`skipOffset`		The time it takes for the ad to become skippable or -1 if unknown.
`universalAdIDRegistry`		A string used to identify the URL for the registry website where the selected creative's Universal Ad ID is cataloged.
`universalAdIDValue`		The Universal Ad ID of the selected creative for the ad.
`wrappers`		An array of ima.WrapperInfo with wrapper information for this ad. The order will be from outer wrapper to inner.

`createAdInfo()`

Returns ima.AdInfo:

Class ima.Companion

Fields

apiFramework, creativeType, height, trackingEvents, url, width

Methods

createCompanion

Contains information about companions of an ad.

Properties

Name	Type	Description
`apiFramework`		The API needed to execute this ad, or Invalid if unavailable.
`creativeType`		Represents the creativetype typically a mimetype.
`height`		The height of the companion in pixels. 0 if unavailable.
`trackingEvents`		A map of tracking events where the key is the event and the value is a list of urls to ping upon that event.
`url`		The URL for the static resource of this companion.
`width`		The width of the companion in pixels. 0 if unavailable.

`createCompanion()`

Returns ima.Companion:

Class ima.CuePoint

Fields

end, hasPlayed, start

Methods

createCuePoint

Contains info about a cue point.

Properties

Name	Type	Description
`end`		The end time for a cuepoint in seconds. This corresponds to an ad break.
`hasPlayed`		A boolean indicating the cuepoint has already played.
`start`		The start time for a cuepoint in seconds. This corresponds to an ad break.

`createCuePoint()`

Returns ima.CuePoint:

Class ima.Error

Fields

id, info, type

Methods

createError

Object passed to the error handler if there is an error.

Properties

Name	Type	Description
`id`		The id of the error. See the ErrorEvent constant for a list of error codes.
`info`		Additional information about the error.
`type`		Always set to error to indicate the type of this object.

`createError()`

Returns ima.Error:

Class ima.ErrorEvent

Fields

BAD_STREAM_REQUEST, COULD_NOT_LOAD_STREAM, ERROR, INVALID_RESPONSE, STREAM_API_KEY_NOT_VALID

All errors that the SDK might send back.

Properties

Name	Type	Description
`BAD_STREAM_REQUEST`		The stream request was not populated correctly.
`COULD_NOT_LOAD_STREAM`		Stream could not be loaded.
`ERROR`		An unknown error.
`INVALID_RESPONSE`		The server response was not valid.
`STREAM_API_KEY_NOT_VALID`		The API key provided was not accepted by the server.

Class ima.Player

Methods

adBreakEnded, adBreakStarted, allVideoComplete, createPlayer, loadUrl

`adBreakEnded(adBreakInfo)`

Optional. Called when an ad break had ended.

Parameter	Type	Description
`adBreakInfo`	`ima.AdBreakInfo`	Contains information about the ad break.

`adBreakStarted(adBreakInfo)`

Optional. Called when an ad break has started.

Parameter	Type	Description
`adBreakInfo`	`ima.AdBreakInfo`	Contains information about the ad break.

`allVideoComplete()`

Optional. Called when all video is complete.

`createPlayer()`

Creates an empty IMA Player object. You must implement the loadUrl function to play ads. Other functions are optional.

Returns ima.Player:

`loadUrl(streamInfo)`

Called when the player should begin playing a url. You must implement this method to load the stream.

Parameter	Type	Description
`streamInfo`	`ima.StreamInfo`	Contains information needed to play content.

Class ima.StreamFormat

Fields

DASH, HLS

Defines the format of the stream.

Properties

Name	Type	Description
`DASH`
`HLS`

Class ima.StreamInfo

Fields

format, manifest, streamId, streamType, subtitles

Methods

createStreamInfo

Information passed from the sdk to the player about the stream.

Properties

Name	Type	Description
`format`		The format of the video: hls or dash. Defined in ima.StreamFormat.
`manifest`		URL for the stream.
`streamId`		A unique ID for the stream.
`streamType`		The type of video: live or on demand. Defined in ima.StreamType.
`subtitles`		Subtitles, if available. Invalid if not.

`createStreamInfo()`

Returns ima.StreamInfo:

Class ima.StreamManager

Methods

addEventListener, createStreamManager, enableInteractiveAds, getContentTime, getCuePoints, getPreviousCuePoint, getStreamTime, loadThirdPartyStream, onMessage, replaceAdTagParameters, start

Object for managing stream playback.

`addEventListener(event, callback)`

Adds a listener for the specified event. See the AdEvents constant for supported events.

Parameter	Type	Description
`event`	`string`
`callback`	`function`

`createStreamManager(streamRequest, streamInitResponse)`

Returns ima.StreamManager:

Parameter	Type	Description
`streamRequest`	`ima.StreamRequest`
`streamInitResponse`	`ima.StreamInitResponse`

`enableInteractiveAds()`

Unsupported. Instead pass data from the companion ad to RAF directly. This is now a no op.

`getContentTime(streamTime)`

Gets a time in milliseconds for a VOD stream, representing the time in the content without ads. For more details, see the FAQ. To get the content time for the current stream time pass in -1.

Returns Integer: The content time corresponding to the given stream time.

Parameter	Type	Description
`streamTime`	`Integer`	The time in the stream.

`getCuePoints()`

Returns all cue points corresponding to all ad breaks. This is only valid for video on demand content where all ad breaks are known ahead of time. All times represent the stream time in seconds. For Cloud Stitching API streams, the hasPlayed property of each ima.CuePoint is always false.

Returns Object: An array with all cue points.

`getPreviousCuePoint(time)`

Returns the cue point preceding this time. The cue point indicates an ad break. All times represent the stream time in seconds.

Returns ima.CuePoint: An object with start, end, and hasPlayed. Returns Invalid if no cue point is available.

Parameter	Type	Description
`time`	`Float`	The time to look up, `-1` indicates current time, and returns `Invalid` for all other streams.

`getStreamTime(contentTime)`

Gets time for the stream from a content time for VOD in milliseconds. For more details, see the FAQ.

Returns Integer: The stream time corresponding to the given content time.

Parameter	Type	Description
`contentTime`	`Integer`	The time of the content.

`loadThirdPartyStream(streamManifest, streamSubtitle)`

Loads the ad metadata and calls the loadUrl function with the provided streamManifestUrl and streamSubtitle data. This function only works when the stream request type is ima.StreamType.POD_VOD.

Parameter	Type	Description
`streamManifest`	`string`	The stream manifest URL with ads stitched.
`streamSubtitle`	`ifArray>\|Invalid`	The subtitles associate with the stream, or `Invalid` if none.

`onMessage(msg)`

Handles all messages coming from the Video object. Must be called for each message received on the roMessagePort.

Parameter	Type	Description
`msg`	`object`	The message from the roVideo port.

`replaceAdTagParameters(adTagParameters)`

Replaces all of the ad tag parameters to be used for the upcoming ad requests for a live stream. Note that this call is a no-op for VOD streams.

Parameter	Type	Description
`adTagParameters`	`string`	The new ad tag parameters.

`start()`

Starts playback of the stream.

Class ima.StreamRequest

Fields

adTagParameters, adUiNode, apiKey, assetKey, authToken, contentSourceId, customAssetKey, format, networkCode, player, ppid, streamActivityMonitorId, videoId, videoObject, videoStitcherSessionOptions

Methods

createLiveStreamRequest, createPodLiveStreamRequest, createPodVodStreamRequest, createStreamRequest, createVideoStitcherLiveStreamRequest, createVideoStitcherVodStreamRequest, createVideoStitcherVodStreamRequestWithVodConfig, createVodStreamRequest

Used for specifying properties of the stream request.

Properties

Name	Type	Description
`adTagParameters`		Optional. You can override a limited set of ad tag parameters on your stream request. Supply targeting parameters to your stream provides more information. You can also use the dai-ot and dai-ov parameters for stream variant preference. See Override stream variant parameters for more information.
`adUiNode`		A scene graph node where ad UI displays. IMA places elements like Why This Ad and Skip buttons on this element during ads. The element must overlay the entire video element.
`apiKey`		Optional. These keys can be used to authenticate stream requests. DAI authentication keys must be set up in the DFP UI.
`assetKey`		Required for live streams. This is used to determine which stream should be played. The live stream request asset key is an identifier which can be found in the DFP UI.
`authToken`		The stream request authorization token. Used in place of the API key for stricter content authorization. The publisher can control individual content streams authorizations based on this token.
`contentSourceId`		Required for on-demand streams. The cmsid comes from the DFP Video Content Source in the DFP UI.
`customAssetKey`		The custom asset key is used to determine which stream should be played. Custom asset keys are required for pod serving stream requests.
`format`		The format of the stream. Defaults to `ima.StreamFormat.HLS`.
`networkCode`		The network code for the publisher making the stream request. Network codes are required for Pod serving stream requests made with createPodLiveStreamRequest or createPodVodStreamRequest. These codes are also required for Cloud stitching stream requests made with createVideoStitcherLiveStreamRequest, createVideoStitcherVodStreamRequest, or createVideoStitcherVodStreamRequestWithVodConfig. These codes are optional and recommended for Full service stream requests made with createLiveStreamRequest or createVodStreamRequest. Adding the network code applies settings selected in the Ad Manager UI, such as programmatic limited ads enablement. For Pod serving and Cloud stitching, adding the network code locates and plays the stream. To find the network code, see this article.
`player`		An implementation of the player interface.
`ppid`		Deprecated. Use adTagParameters. Optional. A DFP Audience publisher provided identifier.
`streamActivityMonitorId`		The ID to be used to debug the stream with the stream activity monitor. This is used to provide a convenient way to allow publishers to find a stream log in the stream activity monitor tool.
`videoId`		Required for on-demand streams. Identifier for the video content source.
`videoObject`		The video object (such as the Video roSGNode) responsible for video playback on the client app. This object will be polled for various data to be used in properly timing Live HLS ID3 events.
`videoStitcherSessionOptions`		The session options are used to set video sticher specific parameters for VideoStitcher streamRequests.

`createLiveStreamRequest(assetKey, apiKey, networkCode)`

Initializes required properties of a Live StreamRequest. Using this API causes any other StreamType-specific properties to be ignored. If any required parameters are empty strings, error logging occurs and the API returns a generic StreamRequest, with no properties ignored.

Returns ima.StreamRequest: ima.StreamRequest object with required Live properties.

Parameter	Type	Description
`assetKey`	`string`
`apiKey`	`string`	Parameter assigned to the returned `ima.StreamRequest`'s `ima.StreamRequest.apiKey` property. If no API key exists, pass an empty string.
`networkCode`	`string`	Network code for the publisher making the stream request. Including the network code is optional, but recommended.

`createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)`

Initializes required properties of a Pod Live ima.StreamRequest. Using this API causes any other ima.StreamType-specific properties to be ignored. If any required parameters are empty strings, error logging occurs and the API returns a generic StreamRequest, with no properties ignored.

Returns StreamRequest: ima.StreamRequest object with required PodLive properties.

Parameter	Type	Description
`customAssetKey`	`string`
`networkCode`	`string`
`apiKey`	`string`	Optional parameter assigned to the returned `ima.StreamRequest`'s `ima.StreamRequest.apiKey` property; defaults to empty string.

`createPodVodStreamRequest(networkCode)`

Initializes the required properties of a ima.StreamRequest to register a VOD stream when using DAI Pod serving with a third party video stitcher. This function sets the request type to ima.StreamType.POD_VOD and validates all required properties for missing data. Failed validations will log an error in the debug console.

Returns StreamRequest: an ima.StreamRequest object. If all required properties are specified, the request type is set to ima.StreamType.POD_VOD.

Parameter	Type	Description
`networkCode`	`string`	the Google Ad Manager network code

`createStreamRequest()`

Returns ima.StreamRequest: An empty ima.StreamRequest object.

`createVideoStitcherLiveStreamRequest(customAssetKey, networkCode, liveConfigId, region, projectNumber, oAuthToken)`

Initializes required properties of a Video Stitcher Live StreamRequest. Using this API causes any other StreamType-specific properties to be ignored. If any required parameters are empty strings, error logging occurs and the API returns a generic StreamRequest, with no properties ignored.

Returns ima.StreamRequest: ima.StreamRequest object with required VideoStitcherLive properties.

Parameter	Type	Description
`customAssetKey`	`string`
`networkCode`	`string`
`liveConfigId`	`string`
`region`	`string`
`projectNumber`	`string`
`oAuthToken`	`string`

`createVideoStitcherVodStreamRequest(adTagUrl, networkCode, contentSourceUrl, region, projectNumber, oAuthToken)`

Initializes required properties of a Video Stitcher VOD StreamRequest. Using this API causes any other StreamType-specific properties to be ignored. If any required parameters are empty strings, error logging occurs and the API returns a generic StreamRequest, with no properties ignored.

Returns ima.StreamRequest: ima.StreamRequest object with required VideoStitcherVod properties.

Parameter	Type	Description
`adTagUrl`	`string`
`networkCode`	`string`
`contentSourceUrl`	`string`
`region`	`string`
`projectNumber`	`string`
`oAuthToken`	`string`

`createVideoStitcherVodStreamRequestWithVodConfig(vodConfigId, networkCode, region, projectNumber, oAuthToken)`

Initializes required properties of a Video Stitcher VOD StreamRequest using vodConfigId created from cloud video stitcher. Using this API causes any other StreamType-specific properties to be ignored. If any required parameters are empty strings, error logging occurs and the API returns a generic StreamRequest, with no properties ignored.

Returns ima.StreamRequest: ima.StreamRequest object with required VideoStitcherVod properties.

Parameter	Type	Description
`vodConfigId`	`string`
`networkCode`	`string`
`region`	`string`
`projectNumber`	`string`
`oAuthToken`	`string`

`createVodStreamRequest(contentSourceId, videoId, apiKey, networkCode)`

Initializes required properties of a VOD ima.StreamRequest. Using this API causes any other ima.StreamType-specific properties to be ignored. If any required parameters are empty strings, error logging occurs and the API returns a generic StreamRequest, with no properties ignored.

Returns ima.StreamRequest: ima.StreamRequest object with required VOD properties.

Parameter	Type	Description
`contentSourceId`	`string`
`videoId`	`string`
`apiKey`	`string`	Parameter assigned to the returned `ima.StreamRequest`'s `ima.StreamRequest.apiKey` property. If no API key exists, pass an empty string.
`networkCode`	`string`	Network code for the publisher making the stream request. Including the network code is optional, but recommended.

Class ima.StreamType

Fields

LIVE, VOD

Defines the type of stream that the player is asked to play. Prerolls and VOD should play from the beginning of the stream.

Properties

Name	Type	Description
`LIVE`		The video is live.
`VOD`		The video is on demand.

Class ima.WrapperInfo

Fields

adId, adSystem, creativeAdId, creativeId, dealId

Methods

createWrapperInfo

Contains information about a wrapper.

Properties

Name	Type	Description
`adId`		The id of the ad or an empty string if unknown.
`adSystem`		The declared name of the ad system or and empty string if unknown.
`creativeAdId`		The ad id on the creative or an empty string if unknown.
`creativeId`		The id of the creative or an empty string if unknown.
`dealId`		The deal id or an empty string if unknown.

`createWrapperInfo()`

Returns ima.WrapperInfo: