BrightLine Roku Guides

Served by: Google Ad Manager
Last Updated: 01/17/2022
Supports: Roku RAF and Direct SDK Integration (with or without RAF support) SSAI and CSAI served by VAST 2.0, 3.0, 4.0

Device Compatibility:
Whether you're integrating with the BrightLine Direct SDK or RAF, older Roku devices may not perform as well with interactive ads as the new generation models with faster processors do. Depending on the complexity of your video player implementation and your overall channel code, you may see lag with remote response and rendering.

Interactive ads should be targeted away from these Roku devices for RAF and Direct SDK integrations:

Blacklisting older Roku models:
Older Roku models that do not behave efficiently with interactive ads and complex channel code should be blocked at the ad server level to maintain acceptable user experiences. Roku NO LONGER allows client-side blacklisting and has mandated all device blacklisting MUST be done at the ad server level. (Depending on the complexity of your video player or channel code, you might need to add more devices to the above list)

 

Recommendations on how to blacklist at the ad server level:
When a request is made from the Roku client to your ad server, you should add at least the first of the three keys below to your ad tag:

 

Populate your ad tags with these keys and their values to give your ad server the ability to target interactive ads away from these devices and/or firmware versions.
Here's a list of all the URL parameter macros you can access through RAF: URL Parameter Macros

 

Example ad tag with keys and values:
You'll mostly be targeting against the device model, but just in case a RAF or firmware version goes into production that might be problematic (Roku hot fixes), you can target away from them also as a fallback temporarily.

This is what a Roku client side ad tag using GAM/DFP looks like which allows for keyword anti-targeting on values (the key names below are what we chose. You can use your own):

http://pubads.g.doubleclick.net/gampad/adx?iu=/52320903/qa&sz=2x2&c=ROKU_ADS_CACHE_BUSTER&cust_params=roku_device%3DROKU_ADS_DEVICE_MODEL%26roku_firmware%3DROKU_ADS_USER_AGENT%26raf_version%3DROKU_ADS_LIB_VERSION&m=text/xml

Interactive ads with BrightLine's Roku Direct SDK:

SceneGraph Direct SDK Integration Server-Side Ad Insertion:

If you have a SceneGraph channel app and would like to have the BrightLine SceneGraph SDK work directly alongside RAF, use our direct SDK integration method where you would include BRS/PKG files to access the BrightLine renderer.

You can also use this SDK if your channel does not use RAF (this is very rare and you'll need a waiver from Roku and will not have access to RAF URL paramater macros).

Roku SceneGraph Direct SDK Integration Guide

Interactive ads with RAF:

RAF BrightScript 1.0 and SceneGraph Client and Server-Side Ad Insertion:

BrightLine's render is built into RAF. If you're integrated with RAF, it's just a matter of trafficking a BrightLine RAF test tag and certifying data with BrightLine. Link to documentation on the Roku Developer Portal is included as a shortcut in this package. As of RAF 2.6, some changes have been documented. Please see this link to make sure you're allowing interactive ads through RAF properly:

RAF ad object:
When integrating with RAF, the following link provides Roku adapters that work with your SSAI provider to format the ad response RAF is expecting:

Implementing Server-Side Ad Insertion Using Roku Adapters

Roku ad object example WHEN NOT using Roku's SSAI Adapters:

The following JSON is a Google DAI example of what RAF is expecting if you're not able to use Roku's SSAI adapters. Roku's SSAI adapters format ad requests automatically in the following format from the VAST response:

					
ad = {
    ads : [{
        companionads : companionads
        duration : ad.duration
        streamformat : streamformat
        rendertime : ad.adBreakInfo.timeoffset + ad.adBreakInfo.adPosition
        streams : [
            {
                mimetype : companion.creativetype
                url : companion.url 'This is the BrightLine companion URL derived from the BrightLine VAST response
            }
        ],
        'These are the quartile trackers for a 30 second spot derived from the final unwrapped BrightLine VAST response
        tracking : [
            {"event":"Impression","time": 0,"triggered":false,"url":"http://events.brightline.tv/track?data=%7B%22type%22%3A%22impression%22%2C%22valid%22%3Afalse%2C%22ad_id%22%3A-1%7D"},
            {"event":"FirstQuartile","time": 7,"triggered":false,"url":"http://events.brightline.tv/track?data=%7B%22type%22%3A%22duration%22%2C%22duration_type%22%3A%22impression%22%2C%22percent_complete%22%3A25%2C%22ad_id%22%3A-1%7D"},
            {"event":"Midpoint","time": 15,"triggered":false,"url":"http://events.brightline.tv/track?data=%7B%22type%22%3A%22duration%22%2C%22duration_type%22%3A%22impression%22%2C%22percent_complete%22%3A50%2C%22ad_id%22%3A-1%7D"},
            {"event":"ThirdQuartile","time": 22,"triggered":false,"url":"http://events.brightline.tv/track?data=%7B%22type%22%3A%22duration%22%2C%22duration_type%22%3A%22impression%22%2C%22percent_complete%22%3A75%2C%22ad_id%22%3A-1%7D"},
            {"event":"Complete","time": 30,"triggered":false,"url":"http://events.brightline.tv/track?data=%7B%22type%22%3A%22duration%22%2C%22duration_type%22%3A%22impression%22%2C%22percent_complete%22%3A100%2C%22ad_id%22%3A-1%7D"}
        ]
    }]
    duration : ad.duration
    rendertime : ad.adBreakInfo.timeoffset + ad.adBreakInfo.adPosition
    viewed : false,
    tracking : []
}
You are also able to force provide a VAST URL if you want to force show an ad for testing purposes outside your ad server environment.
You can do so by setting the value of the ad variable for Roku_Ads() 
                    
adIface = Roku_Ads()
adIface.setAdUrl("Your VAST URL here")

RAF integration support:
BrightLine only provides technical support for our BrightLine Direct SDK. If you're integrating with RAF, you'll need to refer to Roku support.
RAF Integration for SSAI
RAF Integration for CSAI