Video Ads

Apps that display video ads need a custom Roku Ad Framework (RAF) integration. RAF is a Roku library that handle ad UI, tracks ads, fires beacons, and so on. Both server-side and client-side ads are supported. RAF integration can be complex. Typically, it deals little with the Cloud Solution and almost exclusively with BrightScript, Roku and ad provider elements.

The following describes typical operation:

1. Application code provides video metadata as usual (including everything needed to make the ad request).
2. On the client, the custom ads task is specified and defined.
3. When video playback is started the custom ads task is instantiated to run the video event loop. (If your app is using an intrusive analytics package such as Conviva, it needs to be integrated here too.)
4. RAF is retrieved and is provided with the required metadata, most importantly the URL for the ads (generally in VMAP format).
5. Once RAF has parsed the ad pods, it processes the ads using either showAds() for client side ads or stitchedAdsHandleEvent() for server-stitched ads.

Roku may require an additional channel certification process for channels with ads. This can include the injection of test ads to verify correct handling.

Note the following:

• The results of the VMAP request is just XML. You can view it by putting the VMAP URL into a browser or other tool.
• If your ad service is not ready yet or is not reliably delivering ads, you can load a predetermined VMAP file from the channel package or point the client to a static VMAP that you host online.
• You can enable debug output from RAF with adInterface.setDebugOutput(true). On slow devices, it that can cause playback delays.
• You can use SetAdPrefs() to disable the default behavior of using the Roku Ad Network for backfill ads.
• RAF underwent significant changes when the Roku platform started using SceneGraph. Most Roku examples refer to legacy functionality and may not apply.

See also:

• A modern RAF sample

• A forum post on SceneGraph RAF integration

Reference Implementation

The Cloud Solution includes a reference implementation of Auditudes. To use Auditudes, you need to:

• Add a property in the client manifest
• Implement an ads handler in a BrightScript file
• Define some SceneGraph XML
• Modify the reference implementation to suit your particular needs

Note If you want to implement other ads services, You.i TV recommends that your implementation follow a pattern similar to that used for Auditudes.

Manifest Changes

Define a property named ads_class in the client manifest; for example:

ads_class=AuditudeAds

If the property is not defined, the default Ads handler is created and used. The default Ads handler does not have any actual operation. Currently, a client allows only one ads configuration.

SceneGraph XML Code

Define XML client code such as the following:

<?xml version="1.0" encoding="utf-8" ?>
<component name="AuditudeAds" extends="ContentNode">
   <interface>
      <function name="initialize"/>
      <function name="initiatesPlayback"/>
      <function name="getPlayerTaskName"/>
      <function name="playVideo"/>
   </interface>
 
   <script type="text/brightscript" uri="pkg:/components/auditudeAds.brs"/>
   <script type="text/brightscript" uri="pkg:/source/nielsen.brs" />
   <script type="text/brightscript" uri="pkg:/source/utils.brs" />
</component>

The <Component name> entry in the XML must match with the ads_class entry in the manifest. It must also extend ContentNode.

The list of function interfaces can vary according to your actual ads implementation. It is called by ads task.

Add the name of the BrightScript file containing your implementation of the actual ads handler to the script section of the XML code. In this example, the implementing file is auditudeAds.brs.