API reference

Construction

Roku_Ads() as Object

This is the main entry point for instantiating the ad interface. This object manages ad server requests, parses ad structure, schedules and renders ads, and triggers tracking beacons.

The Roku ad parser/renderer object returned has global scope because it is meant to represent interaction with external resources (the ad server and any tracking services) that have persistence and state independent of the ad rendering within a client application.

Control

fireTrackingEvents(adStructure as Object, ctx as Object) as Boolean

Description

Triggers event tracking, including parameter substitution for Nielsen DAR, when library client code handles the ad rendering. This method can be used in scenarios where the RAF ad renderer is not used (for example, custom ad rendering or server-stitched ads).

Parameters

Return Value

A flag indicating whether all beacons of the requested type were successfully fired.

getAds(msg as string) as Object

Description

Gets the set of ads to be rendered now. This method may be called with no parameters or with a msg parameter.

• When called with no parameters, this function returns the full list of all ad pods parsed from the ad server response.
• When called with the msg parameter, this function can be used as an event listener in the client application’s main video playback loop to check whether midroll or postroll ads should be shown or not.

Parameters

Return Value

Available ad pod(s) scheduled for rendering or invalid, if none are available

showAds(ads as Object, ctx as Object, view as Object) as Boolean

Description

Renders any ads scheduled for display.

When this method is called with an array of ad pods (for example, using the value returned from the initial call to the getAds() method), this is interpreted to mean that any preroll ad pod present should be rendered.

Client applications should always check the return value. If it is false, an application should exit content playback and return to the content selection screen. Typically, this occurs when the user presses the “Back” button during ad playback.

Parameters

Return Value

A flag indicating whether the ad pod was rendered to completion. This will be false if the user exited before render completion.

Configuration

setAdUrl(url as String)

Description

Sets the ad URL to be used for a new getAds() request.

You can only receive payment for ads shown in your application when the Roku Ad Framework is properly configured with a valid URL assigned by your ad service or by Roku.

Please contact adsupport@roku.com to discuss monetization options and obtain an ad URL if you wish to use Roku to fill ad inventory in your application.

Parameters

getAdUrl() as String

Description

Gets the currently-configured ad server URL.

Return Value

The current ad server URL.

setAdPrefs(useRokuAdsAsFallback as Boolean, maxRequests as Integer)

Description

Configures general ad request preferences.

The default is for Roku to backfill ads if this method is not called or useRokuAdsAsFallback is not set to false

Parameters

setAdConstraints(maxHeight as Integer, maxWidth as Integer, maxBitrate as Integer, supportedMimeTypes as Object)

Description

Configures media constraints to filter renderable video ads.

By default, the MIME types are configured for “video/mp4”, “video/mp4-h264”, “video/x-mp4”, “application/x-mpegurl”, and “application/json”.

Any additional known types can be mapped to their stream format by setting this parameter before calling getAds().

Parameters

setAdBreaks(contentLength as Integer, adBreakTimes as Integer)

Description

Configures content playback parameters, which can be used for scheduling relative-positioned ad breaks in VMAP ad service responses.

• If your application uses VMAP ad URLs and they are configured to use “nn%” timeOffset values, then you must specify the contentLength prior to calling getAds().
• If VMAP is configured to use “#mm” timeOffset values, you must first specify a set of ad break times.
• Calling with empty parameters will reset these to invalid values.

The content length can also be set independently via setContentLength() if ad break times are not required.

Parameters

setAdExit(enabled as Boolean)

Note: setAdExit() is deprecated and disabled - check showAds() return value instead

#### Description

The default behavior is to enable exiting during ad rendering (for example, via the “Back” button) to return to content selection screen in the application.

Some use cases may require disabling this behavior if the user should not be allowed to skip ads when there is no applicable content selection mechanism.

#### Parameters

| Argument | Type | Description | | -------- | ------ | ------------------------------------------------------------ | | enabled | Boolean | Enables ad exit behavior during rendering. |

importAds(adPodArray as Object)

Description

Resets the internal ad pod cache to allow client code to import a set of ads from unsupported ad service response formats or when aggregating ads from multiple ad services.

The application is responsible for ensuring that the ad pods in the array contain all the required data members.

Parameters

enableJITPods(enabled as Boolean)

Available since version 2.4

Description

For applications that use a VMAP or SmartXML ad response to structure multiple ad pods, including midrolls, the JIT (or “Just In Time”) feature can be used to avoid pre-fetching all ad metadata before the content playback begins.

When enabled, ad call redirects for midrolls are deferred until a certain time before the ad pod is rendered. This mechanism relies on the host app’s continuous use of the BrightScript getAds() API method with the content video position event to determine when to resolve the deferred ads.

JIT is used as a global setting; if the app has mixed content streams, where some content should not use JIT (such as server-stitched ads), then the host app is responsible for disabling this functionality before any ad calls are made for such streams.

Parameters

enableInPodStitching(isIPS as Boolean)

Available since version 2.14

Description

"In-pod stitching" (IPS) mode brings some of the benefits from CSAS API to apps using the classic CSAI API showAds(). When IPS mode is enabled and showAds() is called for an ad break with multiple ads, it would stitch together the video clips for playback, prebuffering the next ad in the background while the current ad is finishing. The viewer experience is better because of the fast transitions between ads. Conversely, when IPS is disabled, each video plays individually and a few seconds are spent in a buffering screen between the ads.

Parameters

setLimitAdTracking(enabled as Boolean)

Available since version 3.1

For apps that collect explicit in-app consent for ad targeting (for example, to adhere to GDPR), this function specifies the value of the ROKU_ADS_LIMIT_TRACKING URL parameter macro to be passed into beacons and ad requests.

This function cannot override the ROKU_ADS_LIMIT_TRACKING value if the customer has cleared the Personalize ads check box in the Settings > Privacy menu.

Parameters

setTrackingCallback(callback as Function, obj as Object)

Description

Allows library client to set a callback function to be called when ad tracking events are fired or checked.

Callback functions must have the following signature:

Sub CallbackFunc(obj = Invalid as Dynamic, eventType = Invalid as Dynamic, ctx = Invalid as Dynamic)

• The obj parameter is an opaque object always passed through to the callback.

• The eventType, if set, is a string specifying a tracking event that is fired. Event names correspond to Tracking.

• The ctx is an optional associative array that encapsulates metadata associated with VAST-specified macros or ad render progress. Each member of the ctx array should separately be considered optional (for example, client code should check for valid values before operating on these data members). Generally, if ctx.eventType is not set, then ctx.time should be set and indicate ad render progress:

  {
      errType: String,
      errCode: String,
      errMsg : String,
      time : Int | Float (playback position, in s),
      url : String (rendered asset URI),
      ad : Associative Array representing ad structure for current ad,
      adIndex: Int (logical index of current ad within ad pod)
  }

Parameters

setDebugOutput(enabled as Boolean)

Description

Enables a library client to configure extended debug output, which is disabled by default.

Parameters

getLibVersion() as String

Description

Gets the RAF library version.

Return Value

The library version in the following format: “<major>.<minor>”

General audience measurement

enableAdMeasurements(enabled)

Available since version 2.1

Description

Applications using audience measurement features must explicitly enable the framework to operate on the custom impression tag parameters. This function is used in conjunction with the setContentGenre(), setContentId(), and setContentLength() APIs to provide measurement data to third-party ad measurement platforms such as NielsenDAR, ComScore CCR, and ComScore VCE.

Contact adsupport@roku.com for more information on how to use audience measurement features.

Parameters

setContentGenre(genres as String, kidsContent as Boolean)

Description

Enables potential ad targeting by specifying a set of genre tags to associate with the content or the ad request.

To clear genre tags, pass an empty string in the genres parameter or omit it.

The semantics and implementation of targeting based on genre values are dependent on the configured ad server, but for a list of currently-supported tags supported by the Roku ad server, see Roku Genre Tags.

Parameters

setContentId(id as String)

Description

Enables potential ad targeting on a video content item by specifying its identifier.

Passing an empty string or omitting the id parameter will clear the content ID.

Parameters

setContentLength(length as Integer)

Description

Configures the content length to extend ad targeting properties for Nielsen DAR.

This method may also be used to determine VMAP relative ad break times.

Omitting the length parameter will clear any content length that was previously set.

Parameters

Nielsen DAR

The Nielsen DAR APIs have been deprecated. Use the general audience measurement APIs instead.

setNielsenGenre(genre as String)

Description

Enables ad campaign measurement using Nielsen DAR tags by specifying a primary genre for the content being played, according to the Nielsen genres defined in Nielsen DAR Genre Tags.

Examples:

“CS” for a “Seinfeld” episode. “N” for a “60 Minutes” episode.

Parameters

setNielsenAppId(id as String)

Enables ad campaign measurement using Nielsen DAR tags.

The value of this application ID is uniquely assigned to your application by Nielsen and must be configured before rendering any ads containing Nielsen beacons.

Parameters

Nielsen DCR

getNielsenContentData() as String

Description

Provides an encrypted Nielsen RIDA parameter string for apps using the Nielsen SDK for DCR measurements.

Return Value

Encrypted Nielsen RIDA parameter string.

Client stitched ads

constructStitchedStream(contentMetaData as Object, ads as Object) as Object

Description

Merges a video feed and a set of one or more ad pods into a single playlist for playback via the renderStitchedStream() function.

Parameters

Return Value

A single video stream containing the specified video feed and ads.

renderStitchedStream(csasStream as Object, view as Object) as Boolean

Description

Renders a video stream that uses client-side ad stitching.

Tracking events are triggered automatically during ad rendering by this method.For client applications that perform their own ad rendering, the valid event types that must be handled are represented in the tracking array of the Ad Structure.

For client-side stitched streams, the app will also get tracking events during content playback in addition to those received during ad rendering.

Parameters

Return Value

A flag indicating whether the stream played to completion. This is false if the user exited playback before the stream completed.

Server stitched ads

stitchedAdsInIt(adPodArray as roArray)

Description

Imports ad metadata to be used for server-stitched ad rendering and resets the internal state before handling events.

The application is responsible for ensuring that the ad pods in the array contain all the required data members. In particular, for server-stitched ads, all time-dependent tracking beacons (Impression and quartile beacons) must have a valid time data member set, with a value relative to the entire stitched stream. For example, if a 30-second ad starts at 10:00 within the stitched stream, its Impression beacons should have track.time = 600.0 and its Midpoint beacons should have track.time = 615.0, and so on.

This method is used in conjunction with stitchedAdHandledEvent() to implement ad rendering within server-stitched video streams.

Parameters

stitchedAdHandledEvent(msg as Object, player as Object) as roAssociativeArray

Description

Determines whether a stitched ad is being rendered, lets the ad renderer attempt to handle the event, and returns metadata about the ad and the event handled state.

This method is only intended for use in rendering server-stitched ads.

The advertising framework must first be initialized using the stitchedAdsInit() method before calling this method.

Parameters

{
  ' Returns message port for player
  GetMessagePort : Function() as Object,

  ' Pauses a stitched video stream
  Pause : Function() as Boolean,

  ' Resumes a paused stitched stream
  Resume : Function() as Boolean,

  ' Seeks to absolute position (in ms) within stream
  Seek : Function(offsetMs as Integer) as Boolean,

  ' Plays stitched video stream
  Play : Function() as Boolean,

  ' Stops stitched video stream
  Stop : Function() as Boolean
}

{
  sgNode : video, ' the video node which will render the stitched stream
  port : port ' the message port on which (at least) the "position" and "state" fields of
  the above video node are observed
}

Return Value

• If a stitched ad is being rendered, this method returns an roAssociativeArray that represents the current ad context and state. The return value is of the form:

    {
        adIndex : Integer, 'Index of current ad within pod
        adPodIndex : Integer, 'Index of current pod
        evtHandled : Boolean, 'True if event was handled by ad renderer
        adExited : Boolean, 'True if user exited ad rendering
        adCompleted : Boolean, 'True if ad has completed rendering
    }
  

• If no stitched ad is being rendered, this method returns Invalid.

• If the return value indicates that there is a stitched ad being rendered and that the event was handled by the renderer, the client application must take no action on that event. If the ad was exited, the client app should stop playback and return to the content selection screen.

Buffer screen customization

setAdBufferScreenContent(contentMetaData as Object)

Description

Enables the client application to set metadata for the content populating the default ad buffer screen. contentMetaData conforms to the format defined in Content Meta-Data and can contain any or all of the following:

{
  HDBackgroundImageUrl : String (URL for HD background image),
  SDBackgroundImageUrl : String (URL for SD background image),
  HDPosterUrl : String (URL for HD video poster),
  SDPosterUrl : String (URL for SD video poster),
  Title : String (Content title),
  Description : String (Content description)
}

Parameters

enableAdBufferMessaging(enableMsg as Boolean, enableProgressBar as Boolean)

Description

Enables the client application to display messaging text and a progress bar on the default ad buffer screen.

Parameters

setAdBufferScreenLayer(zOrder as Integer, contentMetaData as Object)

Description

Enables the client application to set individual layer metadata for the custom ad buffer UI. contentMetaData conforms to the format defined in Content Meta-Data.

The values that can be passed in the zOrder and contentMetaData parameters are specified by roImageCanvas.

Parameters

clearAdBufferScreenLayers()

Description

Enables the client application to clear all metadata in all layers previously set for the custom buffer screen.

setAdBufferRenderCallback(callback as Function, obj as Object, timeout as Integer)

Description

Enables the client application to set a callback function and timeout value for ad buffering events, to provide opportunity for analytics methods or animation of elements on custom buffer screen.

Parameters

{
    'array of content metadata set via setAdBufferScreenLayer, or Invalid
     canvasLayers : roArray of roAssociativeArrays,

    'progress percentage [0-100]. Optional, only for "Progress" event type
     progress : Integer

    'ad metadata for currently buffering ad
    ad : roAssociativeArray,

    'index of current ad within pod
    adIndex : Integer
}