Reach a Valuable Audience with Roku Ads Targeting!

Reach a Valuable Audience with Roku Ads Targeting!


12 January 2019

Marketing communication has become more robust and efficient through Roku channels. Advertising campaigns through Roku channels utilize diverse media channels over a particular time frame and target identified audiences. Roku uses the RAF (Roku Advertising Framework) library to integrate Advertising Campaigns in the channels.

What is RAF?

The Roku Advertising Framework (RAF) is a universal video ad solution directly integrated into the core Roku SDK as a library. The RAF library is intended for the developers to focus their effort on the core design of their applications and provide them with the ability to quickly and easily integrate video advertising features in an efficient way.

Advantages of using RAF

  • Allows to use preferred ad server (e.g. Freewheel, DFP)
  • Rebuilding the app is not needed
  • More standard way of client-side ad insertion across the apps
  • Better ad experience for the consumers (e.g., interactivity, frequency capping) possibly significantly increasing consumption of free content
  • For Advertisers, RAF addresses long-standing obstacles who want to buy media on the Roku platform
  • Additional possibilities to monetize publisher inventory

The RAF is intended to provide advanced advertising fulfillment and rendering capabilities to the applications. It’s quite easy to integrate the ads into the channel and get them rolling.

Let’s get them rolled out

Below are the basic steps to integrate ads in your channel/application.

Add below in the manifest file for any applications using the Roku Ad Framework library:


Client applications are not inclusive of any additional BrightScript modules as part of their own channel package. Instead, the “Library” keyword is used. The following line should be the first entry in your main.brs file:

Library "Roku_Ads.brs"

Obtain the library interface by calling the constructor without arguments:

adIface = Roku_Ads()

If you want to use Roku’s default ad server to fill ads, then no other configuration is required, else you need to configure the ad URL before making the ad request call:

dIface.setAdUrl(<custom ad server URL>)

API Reference

Initialization Methods:

Roku_Ads ()

This method returns the Roku ad parser/renderer object. This method acts as the main entry point for instantiating the ad interface. The returned object has global space. It is mainly responsible for managing ad server requests, parsing ad structure, schedules and render ads, and triggering tracking beacons.

Control Methods:

getAds (msg as string) as an object

This method gets the set of ads to be rendered. This method returns the full list of all ad pods parsed from the ad server response (when called with no parameters). When this method is called with the msg parameter, it can be used as an event listener in the client application’s main video playback loop to check whether the ads should be shown or not. Arguments:

  • msg – Optional. Generally, this is a message returned from a WaitMessage() call on the message port of the roVideoScreen or roVideoPlayer object during content playback.


  • Invalid or available ad pod(s)

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

This method gets the set of ads to be rendered. This method returns the full list of all ad pods parsed from the ad server response (when called with no parameters). When this method is called with the msg parameter, it can be used as an event listener in the client application’s main video playback loop to check whether the ads should be shown or not. Arguments:

  • Ads – Required. Array of ad pods to be rendered.
  • Ctx – Optional. Associative array with ad offset and ad counter to render ad pods.
  • View – Optional. Parameter which represents a renderable node that the ad UI can be parented to.


  • true if ad pod is rendered, false if the user exits before the render completion.

Configuration Methods:

setAdUrl (URL as String)

This method is used to set ad URL to use for a new getAds request.


  • url – URL to set as the current ad service request. Omit this parameter if Roku ad service is used as default service.


  • Invalid or available ad pod(s)

getAdUrl (URL as String)

This function is used to get the currently-configured ad URL, or the default Roku ad server URL if none has been configured.


  • Ad URL

setDebugOutput (enabled as Boolean)

The method above allows a client library to configure extended debug output. It is Disabled by default.


  • enabled – Boolean value to enable/disable extended debug logging.

setAdExit (enabled as Boolean)

The method allows default behavior to enable exiting ad render (e.g., via “Back” button) to return to content selection screen in the application. There might be some use cases which may require disabling this behavior if the user should not be allowed to skip ads.


  • enabled – Configures ad exit behavior during rendering.


Let’s play around Initialize the roDeviceInfo object to inherit the object methods

Check the user state
if m.deviceInfo.IsRIDADisabled() <> true
Get the Roku Advertising ID
m.deviceUUID = m.deviceInfo.GetRIDA()
end if

Instantiate the ad interface

m.adIface = Roku_Ads()
Set the Ad Server URL
url = "" +m.deviceUUID

Enable debug output


Ads present in the returned set of ad pods can immediately get rendered by calling

shouldPlayContent = adIface.showAds(adPods)

Checking and acting on the return value allows the application to determine if the user has exited out of the ad and returned to the content selection screen before playing the main content. Additionally, if the ad server URL is configured to render additional midroll and/or postroll ads, the client application should periodically call getAds method. It should do so with the message from the content video playback loop to determine when to halt the content playback and render the ads as depicted below:

Calling getAds() in a while Loop

while shouldPlayContent
 videoMsg = wait(0, contentVideoScreen.GetMessagePort())
 adPods = adIface.getAds(videoMsg)
 if adPods <> invalid and adPods.Count() > 0
 contentVideoScreen.Close() ' stop playback of content
 shouldPlayContent = adIface.showAds(adPods) ' render current ad pod
 if shouldPlayContent
 ' *** Insert client app’s resume-playback code here
 end if
 end if
 ' *** Insert client app’s video event handler code here
end while

URL Parameter Macros for custom ad server URL

URL Parameter Description
ROKU_ADS_USER_AGENT Device model and firmware version
ROKU_ADS_TRACKING_ID RIDA (Roku ID for Advertising) value used for device identification
ROKU_ADS_TIMESTAMP Current timestamp value (number of milliseconds elapsed since 00:00:00 1/1/1970 GMT)
ROKU_ADS_LIMIT_TRACKING Set to true or false, depending on whether user has limited ad tracking
ROKU_ADS_LIB_VERSION Used to obtain the RAF library version string
ROKU_ADS_KIDS_CONTENT Mark ad requests as “directed towards children.” This macro is designed to help your channel comply with the Children’s Online Privacy Protection Act (COPPA)
ROKU_ADS_EXTERNAL_IP An external IP address of the device
ROKU_ADS_DISPLAY_WIDTH Width of device display
ROKU_ADS_DISPLAY_HEIGHT Height of device display
ROKU_ADS_CONTENT_LENGTH Improves ad targeting by providing length of content (in number of seconds)
ROKU_ADS_CONTENT_ID Identifies the content to allow for ad targeting
ROKU_ADS_CONTENT_GENRE Identifies the content categorization to allow for ad targeting
ROKU_ADS_CACHE_BUSTER Makes the URL unique to avoid retrieving cached ad server responses, or to ensure proper counting of unique event tracking beacons
ROKU_ADS_APP_VERSION Used to obtain the application version string
ROKU_ADS_APP_ID Identifies the client application making the ad request

Targeting using RIDA

The Roku ID is the ID that Roku offers to its publishers to enable targeted advertising on the Roku platform. The application can use the Get RIDA method to get the roku advertising ID. The fetched ID can only pass for audience targeting if “Limit Ad Tracking “is not set in the Roku Settings UI. You can check the user state by calling the IsRIDADisabled method.

Example URL<roku-device-id>

Note* Replace <roku-device-id> with the RIDA for audience targeting.

Custom Buffering Screens

Ads Buffering screen rendered during ads plays also supports multiple ways of customizing the buffering screen which appears before ad playback.

Default Ad Buffering Screen

The default ad buffering screen displays a text message and a progress bar. An enable AdBufferMessaging method can can either enable or disable attributes.

Custom Buffering Screen Using Content Meta-data (Fixed Positioning)

By passing a content meta-data object through the below method, the buffering screen can be customized setAdBufferScreenContent ()

This method does not support custom positioning. The supported content meta-data attributes are:

Attribute Positioning
HDBackgroundImageUrl Aligned to the top-left corner
SDBackgroundImageUrl Aligned to the top-left corner
HDPosterUrl Aligned to top-center
SDPosterUrl Aligned to top-center
Title Center-aligned relative to and displayed below PosterUrl
Description Left-aligned relative to PosterUrl

Event Tracking

Roku has made it quite easy to track the events. During ad rendering by the ShowAds method, it automatically triggers events. The valid event types are:

Event Name Trigger Condition
Impression Start of ad render (e.g., first frame of a video ad displayed)
PodStart Beginning of ad pod render
PodComplete Completed rendering ad pod
FirstQuartile 25% of video ad rendered
Midpoint 50% of video ad rendered
ThirdQuartile 75% of video ad rendered
Complete 100% of video ad rendered
Error Error during ad parsing or rendering (VAST 3.0)
Close User exited out of ad rendering before completion
Skip User skipped ad (if skippable)
Pause User paused ad
Resume User resumed ad
Rewind User rewound ad
Mute User muted ad
Unmute User un-muted ad
AcceptInvitation User launched another portion of an ad (for interactive ads)

Please find a few Roku applications, that we developed in recent times:

Blog Categories
Request a quote