The Roku Ad Framework (RAF) is responsible for a consistent ad experience across the Roku platform. For channels that implement ads using server-side ad insertion (SSAI), this can prove challenging due to the various steps involved. To simplify this process, developers can leverage the Roku-approved approaches via the adapter samples provided by Roku below.
Note: Before using the adapters, please refer to Requirements for Server Side Ad Insertion.
Roku Ad Framework Requirements
All channels including video advertisements are required to meet Roku's certification requirements for RAF. Notably, the app must always use client-side firing (all SSAI providers support client-side firing) through RAF.
The Roku adapters provide two options:
- Firing off all metrics through the adapter and RAF
- The app is responsible to fire metrics through RAF with the adapter callbacks (See examples for using callback below)
It is encouraged that the developer uses the first option, but with either option, the metrics must be fired using RAF APIs.
The APIs used are different depending on the approach, but audience measurement is always required to be dispatched client side at Roku. We recommend channels adopt the comScore VCE-inclusive audience measurement API.
RAFX SSAI Adapters
In general, the RAFX SSAI Adapters provide interfaces to both SSAI manifest servers (stitchers) and RAF, including:
- Parsing of the masterURL response, and extraction of playURL, AdURL, and ad metadata
- Transforming SSAI ad metadata into RAF-usable ad metadata and configuring RAF for playback
- Observing stream events and timed metadata
- Matching the stream events and ad metadata and firing event pixels on time
- Pinging/Polling AdURL as required by the SSAI manifest server, parsing, and reconfiguring RAF
Server-Side Ad Insertion Playback
To playback an SSAI stream, the developer would typically follow these steps:
- Initialize a playback Task
- Make a request to the masterURL
- Enable the client-side ad tracking and get the playURL, AdURL and/or ad metadata
- Configure playback content and observe stream events
- Start playing stream and fire event pixels on time as responding to observed events and ping/poll ad metadata
How to playback SSAI content using the adapters
These are the high level instructions on how to playback server-side ads content using the adapters:
Note: For detailed working instructions, refer to the adapter samples below.
1) Loading the adapter
The following entry loads the adapter into your task:
Note: At the beginning of the playback Task, instantiate the adapter with proper parameters and then initialize it. The valid values of the parameter name are uplynk, adobe, onceux, yospace, awsemt, and ggldai.
2) Make an initial request to SSAI manifest server getting Ad metadata: Request Ad Metadata
The value of the parameter URL depends on which SSAI manifest servers to integrate and which type of stream it is. (The app may query the initial request to SSAI manifest server by itself rather than using the adapter.requestStream() call). Valid values of the parameter type are VOD or LIVE. VOD is when Ad metadata is fetched before the playback starts, LIVE is when Ad metadata is provided as ping/poll/in-stream (such as X-MARKER) content playback.
3) Read Stream Info
The initial request to SSAI manifest servers returns content URL (like Adobe and Uplynk). The following entry gets the content URL:
4) Enable Ads
Once the content playback URL is known, the adapter is ready to track Ads. Pass the adapter player object and observe the position event on the video node.
The value of params.player is given to RAF internally as the second parameter of RAF.stitchedAdHandledEvent(). adapter.enableAds() parses Ad metadata and/or configure additional settings such as observing timedMetadata2 of given video node. It then calls RAF.stitchedAdsInit() when valid Ad metadata was found in the initial response from the SSAI manifest servers.
The app can provide an optional parameter, params.useStitched = false. If the parameter is set to false, the app is required to:
- Set the callback functions to proper AdEvents
- Fire pixels by using RAF.fireTrackingEvents()
- Run and manage Interactive Ads
By default, params.useStitched is set to true. In this case:
- Setting callback functions is optional
- Pixels are fired internally by the adapter and RAF
- Interactive Ads are running and managed by the adapter and RAF
a) Optional: Enable Ads Without stitchedAdHandledEvent
b) Optional: Set Callbacks
A callback parameter is an object with keys, event, and position.
When using PODS, the object has an additional key, adPods, and the value of the parameter is an array of the adPod metadata.
When using POD_START, the object has an additional key, adPod, and the value of the parameter is the current adPod metadata.
Supported callbacks are:
Note: When params.useStiched = true or, not provided in the param (this is the default), setting callbacks is optional and for informational purposes only. The app MUST NOT call RAF.fireTrackingEvents() in such a case.
When params.useStitched = false, it is required to set callbacks and the app MUST call RAF.fireTrackingEvents().
Setting the callback functions to the Adapter:
5) Enable Ad Measurements
When you are ready to start playback, you need to configure RAF by enabling ad measurements:
Note: It is recommended to use enableAdMeasurements.
6) Playback Loop
The developer can now start the playback and run the message loop:
adapter.onMessage() calls RAF.stitchedAdHandledEvent() and returns the object as it is. It is thus recommended to evaluate the returned value and call setFocus() on the video node in case the interactive ad changes focus while playing.
When not using RAF.stitchedAdHandledEvent(), the app must fire AdEvent pixels in the callback functions.
Once the playback is completed, discard the adapter. Do not reference the adapter outside of the Task or re-use the same adapter instance.
Roku Ad Framework APIs
For apps playing SSAI streams, it is required to call RAF APIs using the guidelines below.
It is required for apps to call the following every time the content is played back in the Task:
- Enable ad measurement: enableAdMeasurements(true)
- Set content/app info: setNielsenProgramId(), setNielsenGenre(), setNielsenAppId(), setContentLength()
When the useStitched:true, the adapter itself will:
- Generate RAF ad metadata from SSAI specific format and call stitchedAdsInit(), stitchedAdHandledEvent() to fire ad events and measurement pixels
When the useStitched:false, the developer should make sure that the app:
- Sets callback functions to the adapter
- Fires event pixels via: fireTrackingEvents() when called back
RAFX SSAI Adapter Samples
The following RAFX SSAI Adapter samples are built to provide client-side integration with SSAI, for both VOD and LIVE.
Note that VOD mode means ad metadata is fed from the SSAI server before content playback.
LIVE mode means ad metadata is given as a part of the content stream such as ID3 (HLS) and emsg (DASH), and/or periodic ping/poll request to SSAI server.
Before using the adapter samples, the developer must be familiar with the SSAI providers’ documentation:
Note: The SSAI providers may have undocumented formats, parameters and API behaviors.
RAFX SSAI Adapter for Uplynk Preplay and Ping mode, showing ad rendering via stitchedAdsInit()/stitchedAdHandledEvent().
The Uplynk Adapter provides the following services:
See UplynkTask.brs to find out how to use the adapter. Copy rafxssai.brs to your project and integrate it with the content playback Task.
RAFX SSAI Adapter for Adobe Manifest Server simple and x-marker mode, showing ad rendering via stitchedAdsInit()/stitchedAdHandledEvent().
Adobe Adapter provides the following services:
See AdobeTask.brs to find out how to use the adapter. Copy rafxssai.brs to your project and integrate it with the content playback Task.
RAFX SSAI Adapter for OnceUX VOD mode, showing ad rendering via stitchedAdInit()/stitchedAdHandledEvent().
OnceUX Adapter provides the following services:
When reading stream info, "playURL" field is not available because OnceUX provides a pair of video contentURL and metadata URL.
Read Stream Info:
However, the returned value of getStreamInfo() includes a field called tracking. This returns a list of event info generated from XML element: <uo:contentImpressions><uo:Impression>. The app is responsible for sending those pixels when playback starts.
Sending Content Start Beacon:
See OnceUXTask.brs to find how to use the adapter. Copy rafxssai.brs to your project and integrate it with the content playback Task.
RAFX SSAI Adapter for Yospace server, showing ad rendering via stitchedAdInit()/stitchedAdHandledEvent().
Yospace Adapter provides the following services:
See YospaceTask.brs to find how to use the adapter. Copy rafxssai.brs to your project and integrate it with the content playback Task.
AWS Elemental MediaTailor Adapter
RAFX SSAI Adapter for AWS Elemental MediaTailor(AWSEMT), showing ad rendering via stitchedAdInit()/stitchedAdHandledEvent() .
AWSEMT Adapter provides following services:
See AEMTTask.brs to find how to use the adapter. Copy rafxssai.brs to your project and integrate it with the content playback Task.