Reach a Valuable Audience with Roku Ads Targeting!


Amit Jethwani

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
  • The more standard way of client-side ad insertion across the apps
  • Consumers can have a Better ad experience (e.g., interactivity, frequency capping) means significantly increased 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 be followed to integrate the 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.


  • 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.


  • 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 was rendered, false if the user exited 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. This parameter should be omitted 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 be immediately 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 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 ParameterDescription
ROKU_ADS_USER_AGENTDevice model and firmware version
ROKU_ADS_TRACKING_IDRIDA (Roku ID for Advertising) value used for device identification
ROKU_ADS_TIMESTAMPCurrent timestamp value (number of milliseconds elapsed since 00:00:00 1/1/1970 GMT)
ROKU_ADS_LIMIT_TRACKINGSet to true or false, depending on whether user has limited ad tracking
ROKU_ADS_LIB_VERSIONUsed to obtain the RAF library version string
ROKU_ADS_KIDS_CONTENTMark 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_IPAn external IP address of the device
ROKU_ADS_DISPLAY_WIDTHWidth of device display
ROKU_ADS_DISPLAY_HEIGHTHeight of device display
ROKU_ADS_CONTENT_LENGTHImproves ad targeting by providing length of content (in number of seconds)
ROKU_ADS_CONTENT_IDIdentifies the content to allow for ad targeting
ROKU_ADS_CONTENT_GENREIdentifies the content categorization to allow for ad targeting
ROKU_ADS_CACHE_BUSTERMakes the URL unique to avoid retrieving cached ad server responses, or to ensure proper counting of unique event tracking beacons
ROKU_ADS_APP_VERSIONUsed to obtain the application version string
ROKU_ADS_APP_IDIdentifies 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 be passed 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. Both the attributes can either be enabled or disabled using an enable AdBufferMessaging method.


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

The buffering screen can also be customized by passing a Content meta-data object to below method


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


HDBackgroundImageUrlAligned to top-left corner
SDBackgroundImageUrlAligned to top-left corner
HDPosterUrlAligned to top-center
SDPosterUrlAligned to top-center
TitleCenter-aligned relative to and displayed below PosterUrl
DescriptionLeft-aligned relative to PosterUrl


Event Tracking

Roku has made it quite easy to track the events. Events are triggered automatically during ad rendering by the showAds method. The valid event types are:


Event NameTrigger Condition
ImpressionStart of ad render (e.g., first frame of a video ad displayed)
PodStartBeginning of ad pod render
PodCompleteCompleted rendering ad pod
FirstQuartile25% of video ad rendered
Midpoint50% of video ad rendered
ThirdQuartile75% of video ad rendered
Complete100% of video ad rendered
ErrorError during ad parsing or rendering (VAST 3.0)
CloseUser exited out of ad rendering before completion
SkipUser skipped ad (if skippable)
PauseUser paused ad
ResumeUser resumed ad
RewindUser rewound ad
MuteUser muted ad
UnmuteUser un-muted ad
AcceptInvitationUser launched another portion of an ad (for interactive ads)


Request a quote