Reach a Valuable Audience with Roku Ads Targeting!

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:

bs_libs_required=roku_ads_lib

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.

Returns:

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

Returns:

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

Arguments:

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

Returns:

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

Returns:

• Ad URL

setDebugOutput (enabled as Boolean)

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

Returns:

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

Returns:

• enabled – Configures ad exit behavior during rendering.

Playground

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 = "http://ctv.monarchads.com/serve/?tag=4411&dnt=0&appname=towerofhanoi&aid=" +m.deviceUUID
m.adIface.setAdUrl(url)

Enable debug output

m.adIface.enableAdMeasurements(true)
m.adIface.setDebugOutput(true)
m.adIface.setAdExit(false)

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

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

http://my.ad.server.net/?my_first_param=MyFirstValue&other_param=SomeOtherValue&_fw_did=rida:<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:

• https://channelstore.roku.com/details/245206/balls-and-boxes-free
• https://channelstore.roku.com/details/228252/mineshaft
• https://channelstore.roku.com/details/228306/bubble-trouble
• https://channelstore.roku.com/details/208144/tower-of-hanoi-free