Google IMA Roku SDK APIs

    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.StreamInfo
    11. ima.StreamManager
    12. ima.StreamRequest
    13. ima.StreamType
    14. 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()

Initializes the SDK.

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

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.

Back to top

Class ima.AdEvent

Fields

Events fired by the ads manager.

Properties

Name Type Description
AD_PERIOD_ENDED

Fired when an ad period ends.

AD_PERIOD_STARTED

Fired when an ad period starts. This includes the entire ad break including slate as well. This event will be fired even for ads that are being replayed or when seeking to the middle of an ad break.

COMPLETE

Fired when the ad completes playing.

ERROR

Fired when an error occurs.

FIRST_QUARTILE

Fired when the ad playhead crosses the first quartile.

MIDPOINT

Fired when the ad playhead crosses the midpoint.

PROGRESS

Fired when there is an update to the progress of an ad.

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

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.

currentTime

The current time within an ad in seconds or -1 if unknown.

duration

The duration of this single ad in seconds 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.

Back to top

Class ima.Companion

Fields

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.

Back to top

Class ima.CuePoint

Fields

Contains info about a cue point.

Properties

Name Type Description
end

An integer indicating the end time for a cuepoint in seconds. This corresponds to an ad break.

hasPlayed

A boolean indicating the cuepoint has already played.

start

An integer indicating the start time for a cuepoint in seconds. This corresponds to an ad break.

Back to top

Class ima.Error

Fields

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.

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

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

adBreakEnded(adBreakInfo)

Optional. Called when an ad break had ended.

Parameter Type Description
adBreakInfo imasdk.AdBreakInfo

Contains information about the ad break.

adBreakStarted(adBreakInfo)

Optional. Called when an ad break has started.

Parameter Type Description
adBreakInfo imasdk.AdBreakInfo

Contains information about the ad break.

allVideoComplete()

Optional. Called when all video is complete.

loadUrl(streamInfo)

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

Parameter Type Description
streamInfo imasdk.StreamInfo

Contains information needed to play content.

Back to top

Class ima.StreamInfo

Fields

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

Properties

Name Type Description
format

The format of the video: hls or dash.

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.

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

enableInteractiveAds(videoPlayer)

Allows interactive ads to display on VOD video.

These ads are json data from ad creators that have worked with Roku directly to support their formats. Roku Ad Framework uses roVideoPlayer to display interactive elements.

For scene graph a specific type of object must be used. It should be an roAssociativeArray with two fields.

{
  sgNode: roSGNode REM Your video node.
  port: roPort REM A port listening to events from the video node
}

Note: roVideoScreen will not work for interactive ads.

Parameter Type Description
videoPlayer Object

The player showing the content.

getContentTime(streamTime)

Gets a time in milliseconds for a VOD stream, representing the time in the content without ads. See: https://developers.google.com/interactive-media-ads/docs/sdks/roku/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.

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 Integer

The time to look up, -1 indicates current time.

getStreamTime(contentTime)

Gets time for the stream from a content time for VOD in milliseconds. See: https://developers.google.com/interactive-media-ads/docs/sdks/roku/faq

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

Parameter Type Description
contentTime Integer

The time of the content.

onMessage(msg)

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

Parameter Type Description
msg object

The message from the roVideo port.

start()

Starts playback of the stream.

Back to top

Class ima.StreamRequest

Fields

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.

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.

format

The format of the stream, should be hls or dash. Defaults to hls.

player

An implementation of the player interface.

ppid

Deprecated. Please 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.

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

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.

Back to top

Send feedback about...

IMA DAI SDK for Roku
Need help? Visit our support page.