Table of Contents
The Roku Advertising Framework (RAF) is a universal video ad solution integrated directly into the core Roku SDK as a common library. RAF is required for channels that include ads, see Certification.
RAF natively integrates baseline and advanced advertising capabilities, including:
Other benefits of the framework include:
Automatically updates without rebuilding/resubmitting your app
Standardizes client-side ad insertion across all apps
The Roku Advertising Framework is intended to provide advanced advertising fulfillment and rendering capabilities to applications. The library supports a variety of ad services, and rendering of both video ads and interactive ads. By deploying as a common library, we reduce the overhead of implementation and maintenance for individual channel application developers, and provide a consistent user experience for all applications. The library is designed to support multiple use cases, providing applications with flexibility to control as little or as much of the ad rendering process as desired.
1The International Advertising Bureau is an organization comprised of 650+ media and technology companies. The IAB evaluates and recommends standards and practices and conducts research on interactive advertising.
2Video Ad Serving Template is an IAB specification for a universal XML schema for serving ads to digital video players.
3Video Multiple Ad Playlist is an IAB specification for an XML template that video content owners can use to describe the structure for ad inventory insertion. It is commonly used in conjunction with VAST to structure ads into ad pods.
4[RIDA] The Roku ID for Advertising is a device identifier to track activity for development and marketing purposes. It is designed to generally follow the guidelines established for the IDFA (Identifier for Advertising) used by 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. The RIDA ID must only be passed if "limit ad tracking" is not set in the Roku Settings UI. See GetAdvertisingId(), IsAdIdTrackingDisabled(), and GetPublisherId() for details.
The Roku Advertising Framework (RAF) positions the publisher for the future of video advertising on the Roku platform. RAF exists as a universal ad structure across all channels and Roku devices. All channels that have integrated RAF will benefit from Roku’s development of new ad features.
FreeWheel SmartXML5 parsing
|VAST 2.0 Feature||Supported||VAST 3.0 Feature||Supported||VMAP Feature||Supported|
|Wrapper and Inline Ads||Y||Ad pods6 via sequence attribute||Y||Ad pods playlists||Y|
|Tracking Events||Y||Extended error tracking||Y||Tracking events||Y|
|Linear Ads||Y||VAST tracking macros||Y||‘repeatAfter’ AdBreak attribute||N|
|ClickThrough (interactive ads)||Y||Ad “buffet” selection||Y||Extension elements||N|
|Companion Ads||“image/jpeg”, “image/png” (parsing only, not rendered)||Skippable linear ads||N|
|MediaFile||“video/mp4”, “video/x-mp4”, “application/x-mpegurl”, “application/json”||OBA7 industry icon||N|
5FreeWheel’s proprietary standard combines ad payload and ad scheduling in a single XML file.
6In the context of ad delivery, a pod is a sequence of ads that is rendered consecutively during a single ad break. An ad pod may also consist of a single ad.
7Online Behavioral Advertising refers to the practice of collecting information about online activity to target ads based on relevance.
Roku Ads are integrated with Nielsen audience measurement and is required for all Ad-supported channels. When integrating the Roku Ad Framework, you acknowledge and agree to the following:
(i) that turning on these features will cause device and content viewing information provided by your Roku Channel to the Roku SDK to be automatically appended to Nielsen digital ad ratings (“DAR”) beacons received in VAST responses and sent to Nielsen;
(ii) Nielsen may have personally identifiable information (“PII”) on certain end users of the Roku platform;
(iii) these features will enable third party advertisers, agencies and media resellers (including Roku’s ad sales team if Roku is a reseller of your ad inventory) to serve VAST responses with Nielsen DAR campaign beacons into your channel, and receive reports on the performance of those DAR campaigns; and
(iv) if you are not a Nielsen DAR customer, you may not receive reports on DAR campaigns. If you choose to turn on the Nielsen audience measurement features, you hereby represent and warrant:
(i) that you will notify your users of the occurrence of audience measurement;
(iii) you have and will maintain all necessary rights from Nielsen and consents from users to use the Nielsen audience measurement features; and
(iv) your use of the Nielsen audience measurement features will comply with all applicable laws, rules and regulations.
In the event that Roku runs an ad campaign on your channel, Roku may, in its sole discretion, provide to you or your ad agency, as applicable, excerpts of the Nielsen DAR that relate to the delivery and performance of advertisements on your ad inventory. You hereby agree to
(i) maintain the confidentiality of any Nielsen DAR reports provided to you by Roku; and
(ii) maintain in the Nielsen DAR reports any sourcing and copyright information provided by Nielsen.
YOU AGREE YOU WILL NOT USE THE NIELSEN AUDIENCE MEASUREMENT SOFTWARE AND FEATURES IN CONNECTION WITH CONTENT OR CHANNELS DIRECTED TOWARD CHILDREN OR IN CONNECTION WITH USERS KNOWN TO BE CHILDREN. If Roku discovers or determines in its sole discretion that you are using the Nielsen audience measurement software and features in connection with content or channels directed toward children or with users known to be children, Roku reserves the right to disable or otherwise limit functionality.
YOU MAY NOT ENABLE THE NIELSEN AUDIENCE MEASUREMENT FEATURES IF YOU DO NOT AGREE TO ABOVE. PLEASE CONTACT ROKU OR NIELSEN FOR FURTHER INFORMATION.
A channel publisher can have the Roku Ad sales team sell ads on the channel on their behalf. In such cases, Roku and the channel publisher can agree to share the advertising revenue in one of two ways:
When implementing RAF for your channel, it is important to set the URL to the correct ad server according to the revenue share agreement between Roku and your channel publisher, if it exists. The ad server URL is set as the argument to
For an inventory split agreement, set the URL in
setAdUrl() to the ad server used by your channel for those ads sold by your channel publisher. For the percentage of inventory served by Roku, please contact email@example.com to request a VAST tag.
Since by default, any ads served without an ad server URL will be served by a Roku ad server, you can omit the URL argument, or the
setAdUrl() call entirely, for revenue split agreements.
For steps to getting started, use cases, and the full API reference, see Integrating the Roku Advertising Framework.
The table below provides a number of samples channels to help you get started with your own RAF implementations:
|Download File||SDK Version||Description|
|RAF Video Node Sample||SceneGraph||This sample demonstrates the use of RAF in a Video node with support for pre, mid, and post roll ads.|
|FullRAFSceneGraphSample.zip||SceneGraph||This sample shows how to add RAF to a channel, configure Nielsen, obtain ads and play them as pre-, mid- and post-rolls.|
It also shows how to import Ads from non-standard feed (neither VMAP, VAST or SMartXML.)
|CustomBufferScreenSceneGraphSample.zip||SceneGraph||This sample shows how to change default ad buffering screen background, title and description.|
It also shows how to create a completely custom buffering screen.
This sample shows how to add RAF to a channel, configure Nielsen, obtain ads and play them as pre-, mid- and post-rolls.
|CustomBufferingScreenSDK1Sample.zip||Legacy SDK||This sample shows how to change default ad buffering screen background, title and description.|
It also shows how to create a completely custom buffering screen.
|ServerStitchedAdSDK1Sample.zip||Legacy SDK||This sample demonstrates the interactive stitched ads feature. It shows how to configure RAF with interactive ads and process interactive ad events.|
For the full RAF integration cases, the samples:
For non-standard ad responses, ads are imported from a non-standard feed, neither VMAP, VAST or SmartXML. RAF is configured as if for a standard feed, with backfill ads disabled and extra debug output enabled. Ads are parsed from local JSON file, then formatted as an ad pods array, and imported into RAF using the
importAds() method. After that, the sample checks for particular ads to play by passing video playback events to the RAF
getAds() method inside event loop. If any ads were returned from
getAds(), they are rendered using the RAF
showAds() method. For the Scene Graph example, after
importAds(), the sample checks for particular ads to play by passing fake video events created with
createPlayPosMsg() to the RAF
getAds() method before event-loop (preroll ads) and inside it (midroll/postroll ads). If any ads were returned from
getAds(), they are rendered using the RAF
New feature: JIT ("Just In Time") ad resolution for VMAP, SmartXML to reduce overhead incurred by prefetching all ad pods before content playback starts
New feature: RIA ("Roku Interactive Ads") to allow rendering of Roku interactive ad overlays for OTT content (previously only available for ACR on linear content)
BrightLine bug fixes and performance improvements
Innovid bug fixes and new templates ("User Satisfaction Survey" and "Skippable" interactive ads)
Added a native RSG renderer for Brightline interactive ads
Enabled the firing of tracking events on empty ad breaks (SmartXML and VMAP; relevant to FreeWheel forecasting)
Fixed the autoscaling of interactive ads for FHD-only RSG apps on a HD UI device
Fixed an error when the ad response is invalid XML
Improved the RIDA hashing when "limit ad tracking" is set
Improved the draining of pending beacons cache, to benefit low memory devices
Enhanced the handling of non-standard view sizes (RSG)
Fixed various minor issues
Added support for comScore vCE campaign measurement service
Introducing a generalized audience measurement API (see enableAdMeasurements() for details)
Fix for a display resolution issue when a FHD-only RSG app was playing ad video on a HD UI device
Miscellaneous other fixes
Support for RSG apps to use RAF from Task node
SceneGraph ad rendering support (video ads and Innovid interactive ads)
view parameter for showAds() - this is required for all SceneGraph applications
VAST 3.0 "ad buffet" support
Extended companion ad tag parsing from VAST to allow multiple ad renderers for different companion creatives
New interactive ad template support
adCompleted return value for
provider member for
companionAds metadata in Ad Structure
Fix in VAST parser to address problem with DFP waterfall containing invalid ads
Multiple bug fixes to address ad rendering in both SDK1 and RSG apps built with different combinations of supported