Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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 some intricate steps of the process. Developers can, therefore, leverage the Roku-approved approaches via the adapter samples provided by Roku belowSSAI adapters to simplify this process (See the samples below).

Note: Before using the adapters, please refer to Requirements for Server Side Ad Insertion.

Roku Ad Framework Requirements

All channels including that have video advertisements are required to meet Roku's certification requirements for RAF. Notably, the app channel must always use client-side firing event (all All SSAI providers support client-side firing events) through RAF.

The Roku adapters provide two options:

  • Firing off all the metrics through the SSAI adapter and RAF
  • The app channel is responsible to fire for firing the metrics through RAF with the adapter callbacks (See examples for using callback below)

...

The APIs used are different depending on the approach, but audience measurement is always required to must be dispatched on the client side at Roku. We recommend channels adopt the . Roku recommends that the channel adopts the comScore VCE-inclusive audience measurement API

RAFX SSAI Adapters

In general, theThe RAFX SSAI Adapters provide interfaces to both SSAI manifest servers (stitchers) and RAF, including:

...

To playback an SSAI stream, the developer would typically must follow these steps:

  1. Initialize a playback Task
  2. Make a request to the masterURL 
  3. Enable the client-side ad tracking and get the playURL, AdURL and/or ad metadata 
  4. Configure playback content and observe stream events
  5. 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 Following are the high level instructions on how to playback server-side ads content using the adapters: 

Note: For detailed specific working instructions for a particular adapter, refer to the adapter samples below.

...

The following entry loads the adapter into your the task:

Note: At 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.

Code Block
linenumberstrue
adapter = RAFX_SSAI({name:"uplynk"})  ' Supported: uplynk, adobeonceux, yospace, awsemt, ggldai
adapter.init()

2) Make an initial request to the SSAI manifest server getting Ad metadata: Request Ad Metadata

 


Code Block
linenumberstrue
request = {

    type: adapter.SreamType.VOD  ' Required, VOD or LIVE

    url:  "http://admanifest.ssai.com/api?assetid=abcdefg"' Ad metadata URL, provided by SSAI

}

result = adapter.requestStream(request)

The value of the parameter URL depends on which SSAI manifest servers are to integrate be integrated and which type of stream it is . used (The app channel 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 used when Ad ad metadata is fetched before the playback starts, ; LIVE is used when Ad ad metadata is provided as ping/poll/in-stream (such as X-MARKER) content playback.

...

4) Enable Ads
Once the content playback URL is known, the adapter is ready to track Adsads. 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 ad metadata and/or configure configures additional settings such as observing timedMetadata2 of given video node. It then calls RAF.stitchedAdsInit() when valid Ad ad metadata was is found in the initial response from the SSAI manifest servers.

Code Block
linenumberstrue
port = CreateObject("roMessagePort")
params = {player: {sgnode:m.top.video, port:port}}
adapter.enableAds(params)
m.top.video.observeField("position", port)


The app channel can provide an optional parameter, params.useStitched = false. If the parameter is set to false, the app channel is required to:

  • Set the callback functions to proper AdEvents
  • Fire pixels by using RAF.fireTrackingEvents()
  • Run and manage Interactive Adsads

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 ads are running ran and managed by the adapter and RAF

...

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 channel MUST NOT call RAF.fireTrackingEvents() in such a case. 

When params.useStitched = false, it is required to set callbacks and the app channel MUST call RAF.fireTrackingEvents().

Setting the callback functions to the Adapter:

 

Code Block
linenumberstrue
' Set adapter callback functions

adapter.addEventListener(adapter.AdEvent.POD_START, rafxCallback)

adapter.addEventListener(adapter.AdEvent.POD_END, rafxCallback)

adapter.addEventListener(adapter.AdEvent.IMPRESSION, rafxCallback)

...

...

function rafxCallback(eventInfo as object) as void

    if adapter.AdEvent.POD_START = eventInfo.event

        m.top.adPlaying = true

    else if adapter.AdEvent.POD_COMPLETE = eventInfo.event

        m.top.adPlaying = false

    end if

    print "Callback at : ";eventInfo.position

end function


5) Enable Ad Measurements 

When you are the channel is ready to start playback, you need to configure RAF by enabling ad measurements:

Note: It It is recommended to use enableAdMeasurements.

...

Roku Ad Framework APIs

For apps channels playing SSAI streams, it is required to call RAF APIs using the guidelines below. 

It is required for apps channels to call the following every time the content is played back in the Task:

  • Enable ad Enable ad measurement: enableAdMeasurements(true)
  • Set content/app info: setNielsenProgramId(), setNielsenGenre(), setNielsenAppId(), setContentLength()

When the useStitched:When useStitched is set to true, the adapter itself will

  • Generate Generates RAF ad metadata from SSAI specific format and call calls stitchedAdsInit(), stitchedAdHandledEvent() to fire ad events and measurement pixels

When the useStitched :is set to false, the developer should make sure that the appchannel:

  • Sets callback functions to the adapter
  • Fires event pixels via: fireTrackingEvents() when called back

...