Roku SDK Documentation : Integrating the Roku Advertising Framework

Getting Started

The RAF library is intended to allow 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 with minimal impact to the rest of their application. This section provides an overview of the fundamental steps required to integrate with such applications. Other developers may wish to have more control over certain features within their applications, such as rendering the ads with a custom UI, or integrating the event tracking with a 3rd-party analytics API. The API Reference provides more detailed information on the video ad API, and the Use Cases section offers examples designed to cover a variety of different scenarios. The video ad features are provided as a common library deployed and managed as a hidden channel. 

The following line must be placed in the manifest file for any applications using the Roku Ad Framework library:

bs_libs_required=roku_ads_lib

Client applications do not include 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"

The library interface is obtained by calling the constructor with no arguments:

adIface = Roku_Ads()

If the client application is using Roku’s default ad server to fill ads, no other configuration is required. Otherwise, configure the ad URL before making the ad request call:

adIface.setAdUrl(myAdUrl)

Aside from the Configuration interface, there are two main methods used to control ad parsing and rendering. The first, getAds(), makes the initial request to the ad server, parses the server response, and returns the structure of ads to be rendered prior to, or during playback, of the selected content:

adPods = adIface.getAds()

Any preroll 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 here allows the application to determine if the user exited out of the ad (for example, by pressing the “Back” button on the remote) and return to the content selection screen before playing the main content.

If the application is only showing preroll ads, the above five lines are sufficient. If the ad server URL was configured for additional midroll and/or postroll ads, the client application should periodically call getAds() with the message from the content video playback loop to determine when to halt the content playback and render the ads:

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

Please note that the system overlay behavior has been modified in Roku OS 8. Every time RAF is rendered, the Video node will not be in focus. For the Roku system overlay to slide out when the * button is clicked, the Video node should be set to be in focus. Otherwise, the channel retains control over the * button and will need to handle button presses on their own. To set the Video node in focus again, use the following code snippet:

Use Cases

The video ad library is intended to support a variety of use cases, depending on the requirements of the application. The sample code presented here is provided for illustrative purposes of each of these cases and is not intended to represent required or optimal usage in client applications. For clarity and concision, error and object validity checking are omitted in these examples.

In all cases, the library must first be included and its interface constructed as described in Getting Started. Additionally, unless the client application is using Roku’s default ad URL (which currently provides only a single ad), the ad URL must be configured before requesting an ad pod:

Library "Roku_Ads.brs"

adIface = Roku_Ads() 
adIface.setAdUrl(myAdUrl) 
adPods = adIface.getAds()

At this point, the ad server response has been fully parsed and is available in the adPods Ad Structure.

Client Side Ad Insertion

If the client application has no need for custom UI or user interaction during ad rendering, it is recommended to use the default rendering method showAds(). This method handles rendering and control of interactive and video ads, as well as displaying basic messaging UI (e.g., “Your program will continue after these messages”) and feedback UI (“Ad 1 of 3”). Calling showAds() with an array of ad pods (such as the structure returned from the initial call to getAds()) will render the first pod scheduled as a preroll. Calling it with a single ad pod will render that pod, regardless of its renderSequence attribute.

Single Preroll Ad Pod

Just call showAds() with the adPods value that the application obtained above:

shouldPlayContent = adIface.showAds(adPods)

Note that the return value should still be checked to see if the user exited the ad, and therefore should also exit out of content playback back to a selection screen.

Sequential Rendering

Typically, if the ad service URL is configured to return a slate of ad pods to be presented throughout the presentation of the content, it is sufficient to use getAds() as an event listener in the content video event loop, as described in Getting Started, to determine when the scheduled ad breaks should occur:

shouldPlayContent = adIface.showAds(adPods)
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

This usage of getAds() also automatically implements the default policy that determines whether to re-render ads that have already been viewed. This policy permits the user to rewind content up to 5 minutes before a scheduled ad break before displaying that ad pod again.

Custom Scheduling

Alternatively, there may be instances where the application must have greater control over when ad breaks occur. As an example, if the ad service is configured to return a VAST 2.0 response without temporal ad breaks, the application could re-interpret this unstructured response and schedule rendering of those ads as necessary:

adBreakSchedule = [adBreakTime1, adBreakTime2, adBreakTime3] 
scheduledPods = [] 
adBreakIndex = 0 
for each ad in adPods[0].ad
  ' schedule one ad per ad break
  scheduledPods.Push({viewed : false,
                      renderSequence : "midroll",
                      duration : ad.duration,
                      renderTime : adBreakSchedule[adBreakIndex],
                      ads : [ad]
                      })
  adBreakIndex = adBreakIndex + 1 
end for

Default sequential rendering could then be used by first importing this new scheduledPods ad structure, as described in Custom Ad Parsing and Rendering.

Or, if the library’s ad rendering features are desired without the default ad scheduling mechanism, the application may completely control which ads are scheduled for rendering:

shouldPlayContent = true 
adBreakIndex = 0 
while shouldPlayContent
  videoMsg = wait(0, contentVideoScreen.GetMessagePort())
  if videoMsg.isPlaybackPosition()
    curPos = videoMsg.GetIndex()
    nextPod = scheduledPods[adBreakIndex]
    if curPos > nextPod.renderTime and not nextPod.viewed
      contentVideoScreen.Close() ' stop playback of content
      shouldPlayContent = adIface.showAds(nextPod) ' render next ad pod
      adBreakIndex = adBreakIndex + 1
      if shouldPlayContent
        ' *** Insert client app’s resume-playback code here
      end if
    end if
  end if
  ' *** Insert client app’s video event handler code here 
end while

This type of custom ad scheduling may also be necessary if the client application relies on multiple ad services to fill its ad slots. For this case, separate calls are made to setAdUrl(), followed by getAds(), to get the ads from each service. Then scheduling and rendering can be done using one of the methods described above.

Example

For an example, see: FullRAFSceneGraphSample.zip

Enabling Nielsen Digital Ad Ratings

As third parties such as Nielsen measure all video advertising in the digital ecosystem, Roku mandates that all channels enable Nielsen DAR in their Roku apps. Even if the publisher does not have a direct relationship with Nielsen, it is important to enable that in the app so as to avoid an app update when/if there is a decision made to enable Nielsen.

Nielsen DAR must first be enabled using:

enableNielsenDAR(true)

This need only be done once and can be called at any point before any ads are rendered.

Next, a Nielsen application ID must be set for accurate campaign measurement. If you are not working with Nielsen directly, you can use Roku's default App Id: P2871BBFF-1A28-44AA-AF68-C7DE4B148C32

setNielsenAppId("P2871BBFF-1A28-44AA-AF68-C7DE4B148C32")

Each content item will then need to be tagged appropriately. The required attributes are:

• title (NielsenProgramId) - this value should the title of a movie or series and should not uniquely identify episodic content
• length of the content (in seconds)
• Nielsen genre (see Nielsen DAR Genre Tags)

setNielsenProgramId("TED Talks")
setContentLength(1200)
setNielsenGenre("GV")

The content-specific metadata should be set when new content is selected before any ads are rendered, so that the values can be added to the custom Nielsen impression tags for the ads. If any of these metadata are unknown for a particular piece of content (for example, live streams may not have a specific content length), applications should call the appropriate function with an empty parameter to clear the value.

Frequency Capping and Targeting using RIDA

The Roku ID for Advertising is a device identifier available to Roku publishers for development and marketing purposes. It is designed to generally follow the guidelines established for the IDFA (Identifier for Advertising) used on other platforms. The RIDA limits disclosure of users’ identifying information and allows the ability to opt-out of remarketing or reset the ID at any time. It is the ID that Roku offers to its publishers to enable frequency capping and targeted advertising on the Roku platform.

The app can use the GetRIDA() API to get the RIDA for the device. RIDA should only be passed for audience targeting if "Limit Ad Tracking" is not set in the Roku Settings UI. If the RIDA is not set, it should still be used for frequency capping and when the ad server may need to know the user state. The app can check that by calling the IsRIDADisabled() API.

Function getRIDA() as String
    RIDA = ""
    dev_info = createObject("roDeviceInfo")
    if not dev_info.IsRIDADisabled()
       RIDA = dev_info.GetRida()
   end if

    return RIDA
End Function

RIDA Specific Parameters

Many leading ad servers such as FreeWheel and DFP have Roku specific parameters in their ad request that the app can pass the RIDA in.

For Freewheel, the parameters are:

_fw_did=rida:<roku-device-id>
_fw_vcid2=<roku-device-id>

url = http://my.ad.server.net/?my_first_param=MyFirstValue&other_param=SomeOtherValue&_fw_did=rida:<roku-device-id>

For DFP, the parameter is called rdid. Additional details available here: https://support.google.com/dfp_premium/answer/6238701?hl=en

url = http://pubads.g.doubleclick.net/gampad/request-type?my_first_param=MyFirstValue&other_param=SomeOtherValue&rdid=<roku-device-id>

Custom Buffering Screens

RAF also supports multiple ways of customizing the buffering screen which appear before ad playback.

Default Ad Buffering Screen

The default ad buffering screen displays a message and a progress bar. Both attributes can either be enabled or disabled using enableAdBufferMessaging().

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

The buffering screen can also be customized by passing a Content meta-data object to setAdBufferScreenContent(). This function does not support custom positioning. Instead, use SetAdBufferScreenLayer() as described in the next section.

The supported content meta-data attributes are:

bufferScreenContent = {}
bufferScreenContent.HDBackgroundImageUrl = "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f8/Aspect-ratio-16x9.svg/1280px-Aspect-ratio-16x9.svg.png"
bufferScreenContent.HDPosterUrl = "http://static.commentcamarche.net/ccm.net/faq/images/0-BX4VeV6H-resolution-comparison-s-.png"
bufferScreenContent.Title = "Title for custom buffering screen"
bufferScreenContent.Description = "Description for custom buffering screen"

adIface.SetAdBufferScreenContent(bufferScreenContent)

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

For a complete custom buffering screen, setAdBufferScreenLayer() allows the same content meta-data attributes as setAdBufferScreenContent(), but enables you to customize the positioning and other roImageCanvas attributes.

layers = [
	{Url: BackgroundImageUrl}
    {Url: PosterUrl, TargetRect : {x : 405, y : 370, w : 467, h : 262}}
    {
    	Text : "This is a custom build screen"
        TextAttrs : { Color : "#FF0000", HAlign : "Center", Font : "Large"}
        TargetRect : {y : 50, h : 30}
    }
]
adIface.setAdBufferScreenLayer(2, layers)

For an example on different custom buffering screen implementations, see CustomBufferScreenSceneGraphSample.zip.

Custom Ad Parsing and Rendering

Custom Ad Parsing

Some applications may use an ad service that returns an unsupported response format, but can still take advantage of the library’s ad rendering features. In this case, the application is reponsible for requesting and parsing the ad response and structuring the ads into an array of pods according to the required Ad Structure. Scheduling and rendering can then proceed as described in Client Side Ad Insertion by first calling the importAds() method with the ad structure constructed externally by the client:

adIface.importAds(myAdPodArray)

Custom Ad Rendering

Client applications may elect to control the ad rendering within the application, either to provide custom UI while loading ads, or because the ads are rendered by a method unsupported by the video ad library (e.g., by server-side video stitching). It is sufficient to make a single call to getAds() to get the entire Ad Structure. The client application is then responsible for using the streams data to render the ads, and also must trigger the Tracking events when the requisite conditions are met.

The fireTrackingEvents() method is used to trigger event tracking, including client macro replacement and processing of Nielsen DAR beacons. The adStructure parameter passed in to this method can be either an adPod or a single ad from Ad Structure, depending on whether the event is relevant for the entire pod (such as PodStart or PodComplete) or for a single ad (all other event types). The ctx parameter should contain either a type string from the Tracking events or a time numerical value for firing time-dependent events such as quartile beacons. If both are specified, the type value takes precedence. Custom tracking event types can be added and fired as well, but client code should attempt to use conventional event types such as “Impression” where appropriate, as certain operations like Nielsen DAR parameter substitution rely on the “Impression” event type.

Client code should fire all supported tracking events specified by Tracking during ad rendering when the appropriate conditions are met. Some events need not be fired such as Error, which is specific to VAST parsing only. Events corresponding to operations unsupported during ad rendering also need not be fired, such as Rewind, Mute, or AcceptInvitation (which is specific to ads with interactive elements).

As an example, if ad contains the Ad Structure for a video ad that the client application has just begun rendering, the Impression beacons for that ad could be fired with a single call:

adIface.fireTrackingEvents(ad, {type: "Impression"})

While the ad playback progresses, assuming the variable adProgressTime holds a value representing the number of seconds since the ad began rendering, the quartile beacons can be sent via:

adIface.fireTrackingEvents(ad, {time: adProgressTime})

If the ad were paused by the user, then the client app would fire the Pause beacons:

adIface.fireTrackingEvents(ad, {type: "Pause"})

Requirements for Server Side Ad Insertion

1. Frequency Capping and Targeting Requirements

For apps that serve ads via SSAI, the outbound ad call to the ad server is not made from the client. The app will have to assume the onus of passing the RIDA from the client to the server side component of the SSAI vendor or the ad server.

2. Nielsen Digital Ad Ratings Requirements

For server side ad inserted applications, call fireTrackingEvents() in RAF and ensure that the Nielsen beacons are passed to RAF via that API. It is valid to pass all impression beacons to RAF via this API. For non-Nielsen beacons, RAF will be just a pass-through. 

3. Uniform Ad Experience Requirements

To enhance user engagement and consistency of ads served on the Roku platform, RAF supports rendering of both video and interactive ads (from certain vendors such as Brightline and Innovid) in server-stitched streams. This allows Roku to display standard UI components and behavior (ad counter, ad timer, trickplay support, etc.) for server-stitched streams.

Implementation Details

There are two API methods required for these use cases. First, the application is responsible for requesting and parsing the ad response, and structuring the ads into an array of pods, according to the required Ad Structure. This ad metadata may, in some cases, come from a third party SDK provided by your stitching platform.

• For server stitched ads, the 'time' member of the 'tracking' data (in Ad Structure) for each ad is required.  The value of this data member should correspond to the absolute time in the entire stream, not just relative to the current ad. 
  • Example: For a 30-second ad that starts at 15:00 in the stitched stream, the 'Impression' beacons for that ad should be set to 900 seconds and the 'Midpoint' beacons for that ad should be 915 seconds (i.e., @15:15).  The 'time' member should still be omitted for beacons that do not depend on time (such as 'Pause' or 'AcceptInvitation').
• The meaning of postroll stitched ads is slightly different than for client-inserted ads, since the ads are part of the stream.  Client code can still set the 'renderSequence' for the pod to 'postroll', but all time values should still refer to the absolute position within the stitched stream.

Scheduling and rendering is then initialized by first calling the stitchedAdsInit() method with the ad structure constructed by the client:

adIface.stitchedAdsInit(myAdPodArray)

Playback of the stitched stream is then started via an roVideoPlayer object (or optionally, a wrapped interface that matches the specification described in stitchedAdHandledEvent()). In the event loop for the video player, the app should then first check if an ad renderer handled the event, as well as checking for exit condition. If no ad renderer handled the event, control falls through to the application’s regular event-handling logic:

playContent = true
while playContent 
  msg = Wait(0, videoPlayer.GetMessagePort()) 
  currentAd = adIface.stitchedAdHandledEvent(msg, videoPlayer) 

  if currentAd <> Invalid and currentAd.evtHandled 
    ' ad handled event, take no further action 
    if currentAd.adExited 
      ' user exited, return to content selection 
      playContent = false 
    end if
  else 
    ' if no current ad or ad did not handle event, fall through to default event handling here 
    ' ... Your application's usual event-handling code here ... 
  end if 
end while

• If currentAd = invalid, then no current ad is being rendered, and the app can handle the event normally.
• If currentAd <> invalid and currentAd.evtHandled = true, then the ad renderer handled the event, and no further action should be taken on that event.
• If currentAd.adExited = true, then the user exited the ad renderer and the app should exit playback and return to content selection.
• Only if no current ad is being rendered or currentAd.evtHandled = false should the app handle the event in any way.  Keep in mind that ad rendering can create new roImageCanvas objects with their own navigation, or roVideoPlayer objects with their own internal state and position.  These will in general have nothing at all to do with any such object created by the content playback app, yet they will share the same message port so that the application event loop can forward all events to the ad renderer first.

Alternatively, an roAssociativeArray can wrap and mimic the interface of the roVideoPlayer parameter of stitchedAdHandledEvent(). See method description for the minimum required key-value pairs. This wrapped interface is useful if there are other actions to be taken on player control methods (such as analytics fired when the stream is paused, etc.)

Testing your RAF Implementation

To test your RAF implementation, you do not need to pass any URL argument to setAdUrl(). Use setAdUrl() as you would for the revenue split agreement and either omit the URL argument or the setAdUrl() call entirely. This allows you to check that ads are served correctly to users of the channel, but no revenue will actually be generated.

API Reference

Construction

Control

General

Client Ad Insertion

{ start: Integer, total: Integer }

Server-Stitched Ads

{ ' 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
}

{ 
  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
}

Configuration

General

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

{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) }

Nielsen DAR

Nielsen DCR

General Audience Measurement

Server-Stitched Ads

Buffer Screen Customization 

{ 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)
}

Function(obj as Dynamic, eventType as String, ctx as Dynamic) as Void

{ ' 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
}

URL Parameter Macros

The video ad library allows parameter values to be substituted in ad request and tracking URLs. This allows for dynamic configuration of values that are either not directly exposed to the client application or are unnecessary for it to initialize and maintain. These values are typically used for ad targeting, interaction tracking, and development purposes, or to optimize the ad experience for the user’s device.

Example

To make an ad request that requires the application ID, user agent, and timestamp values, call setAdUrl() with those parameters set:

rokuAds = Roku_Ads()
url = "http://my.ad.server.net/?my_first_param=MyFirstValue&my_app_id=ROKU_ADS_APP_ID&my_user_agent=ROKU_ADS_USER_AGENT&my_timestamp=ROKU_ADS_TIMESTAMP&other_param=SomeOtherValue"
rokuAds.setAdUrl(url)

Ad Structure

For a client application that must implement its own ad rendering, it is necessary to understand how the ad structure is represented in the BrightScript object returned from getAds(). The following is a description of the ad structure. Ad pods passed to showAds() must conform to this structure.

adPods : [{
         +viewed         : Boolean,
         +renderSequence : String ("preroll" | "midroll" | "postroll"),
         +duration       : Float (in s),
         +renderTime     : Float (in s),
          slots          : Int,
          backfilled     : Boolean,
         +tracking: [{
            +event: String,
            +url: String,
            +triggered: Boolean,
             valid: Boolean
          }],
         +ads : [{
                 +duration     : Float (in s),
                 +streamFormat : String,
                 +adServer     : String,
                  adId         : String,
                  adTitle      : String,
                  advertiser   : String,
                  creativeId   : String,
                  creativeAdId : String,
                  clickThrough : String (URL),
                 +streams : [{
                             +url      : String (URL),
                             +bitrate  : Int (in kbps),
                             +width    : Int,
                             +height   : Int,
                             +mimeType : String,
                              provider : String
                  }],
                 +tracking : [{
                              +event     : String,
                              +url       : String (URL),
                              +triggered : Boolean,
                               valid     : Boolean,
                               time      : Float (in s)
                  }],
                  companionAds: [{
                                 +url          : String (URL),
                                 +width        : Int,
                                 +height       : Int,
                                 +mimeType     : String,
                                  clickThrough : String (URL),
                                  provider     : String,
                                 +tracking : [{
                                              +event     : String,
                                              +url       : String (URL),
                                              +triggered : Boolean,
                                               valid     : Boolean,
                                               time      : Float (in s)
                                  }]
                  }]
          }]
}]

The object returned from a new call to getAds() with no parameters is an array of adPods in this format.

Tracking

Tracking events are triggered automatically during ad rendering by showAds(). 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 by:

Roku Genre Tags

Tagging content by genre via setContentGenre() is specific to the ad provider, and may not be uniformly implemented.  For ads provided by the Roku ad service, there is currently a canonical set of genre tags that can be used to improve ad targeting:

• Action
• Adventure
• Animated
• Ballet
• Biography
• Children
• Comedy
• Comedy drama
• Crime drama
• Cuisine
• Dark comedy
• Docudrama
• Documentary
• Drama
• Entertainment
• Fantasy
• Historical drama
• Horror
• Martial arts
• Music
• Musical
• Musical comedy
• Mystery
• Performing arts
• Romance
• Romantic comedy
• Science fiction
• Special
• Suspense
• Talk
• Theater
• Thriller
• Travel
• War
• Western

Nielsen DAR Genre Tags

Tagging content by genre via setNielsenGenre() requires a single primary genre code for the selected content from the following set of values. Publishers should provide the most specific category applicable to the content for which ads are to be shown.