IMA DAI SDK for Roku

    1. ima
    2. ima.AdBreakInfo
    3. ima.AdEvent
    4. ima.AdInfo
    5. ima.Companion
    6. ima.CuePoint
    7. ima.Error
    8. ima.ErrorEvent
    9. ima.Player
    10. ima.StreamFormat
    11. ima.StreamInfo
    12. ima.StreamManager
    13. ima.StreamRequest
    14. ima.StreamType
    15. ima.WrapperInfo

Class ima

Methods

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

Back to top

Class ima.AdBreakInfo

Fields

Methods

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. Will be 1 for stand alone ads.

duration

The maximum duration of the break in seconds, or -1 if unknown.

podIndex

For live streams, always returns -1. 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. Will be 1 for stand alone ads.

createAdBreakInfo()


Returns ima.AdBreakInfo:

Back to top

Class ima.AdEvent

Fields

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.

Back to top

Class ima.AdInfo

Fields

Methods

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:

Back to top

Class ima.Companion

Fields

Methods

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:

Back to top

Class ima.CuePoint

Fields

Methods

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:

Back to top

Class ima.Error

Fields

Methods

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:

Back to top

Class ima.ErrorEvent

Fields

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.

Back to top

Class ima.Player

Methods

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.

Back to top

Class ima.StreamFormat

Fields

Defines the format of the stream.

Properties

Name Type Description
DASH

HLS

Back to top

Class ima.StreamInfo

Fields

Methods

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:

Back to top

Class ima.StreamManager

Methods

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. See: https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/roku/faq To get the content time for the current stream time pass in -1. Note: This function is only supported for Full-service DAI VOD streams, and returns the same value passed in for all other streams.

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. Note: This function is only supported for Full-service DAI VOD streams.

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. See: https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/roku/faq Note: This function is only supported for Full-service DAI VOD streams, and returns the same value passed in for all other streams.

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.

Back to top

Class ima.StreamRequest

Fields

Methods

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 all stream requests, and stream requests with an invalid code may fail. The code applies settings selected in the Ad Manager UI, such as programmatic limited ads enablement. 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

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

Back to top

Class ima.StreamType

Fields

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.

Back to top

Class ima.WrapperInfo

Fields

Methods

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:

Back to top