Server Side Ad Insertion in Yospace player

The fl-ad-yospace library integrates with Yospace to offer Server Side Ad Insertion capability for both VOD and Live.

Setup

Yospace AdManagement library must be embedded with app. The Yospace library has components and source files which must be copied to your channel app's components and source folder as in below strucure.

• App
  • components
    • Yospace
  • source
    • AdManagement

note

Please use the Yospace library version shipped with the Quickplay libraries.

note

Please add bs_libs_required=roku_ads_lib on your manifest file

Wiring Authorization Response

Once an asset is authorized for Playback (refer Authorize Playback for an Asset), the authorization response indicates if the content is ad enabled. The Ad player must be setup only when this flag is enabled.

Name	Description
ssaiEnabled	Indicates whether the content is Ad enabled

Create Ad Player

The FLAdYospacePlayer component can be created programmatically as well as can be added to a Scene Graph node component directly.

Create FLAdYospacePlayer

flPlayer = createObject("roSGNode", "FLAdYospacePlayer")

This ad player can be used like conventional player from FLPlayer library for playback.

Player Fields and Functions

The FLAdYospacePlayer component is an extension of FLPlayer component and has its own fields and function in addition to existing ones from FLPlayer. The fields and function names can be accessed from fields FLPlayerFields and FLPlayerFunctions on player.

Get FLAdYospacePlayer field and function name constants

' get Player field name constants
flPlayerFields = flPlayer.FLPlayerFields
' get Player function name constants
flPlayerFunctions = flPlayer.FLPlayerFunctions

FLAdYospacePlayer fields

Ad Player Field Name Constants

REQUEST_TIMEOUT
USER_AGENT
CUE_POINTS
AD_BREAK_STARTED
AD_BREAK_FINISHED
AD_STARTED
AD_FINISHED
AD_PROGRESS
AD_TRACKING_EVENT

FLAdYospacePlayer functions

Ad Player Function Name Constants

SET_CONTENT_GENRE
SET_CONTENT_ID
SET_CONTENT_LENGTH
SET_NIELSEN_GENRE
SET_NIELSEN_APP_ID

Playback with Ad Player

Since FLAdYospacePlayer is an extension of FLPlayer it provides the same playback features as the base player. You can set PlaybackAssetto the player and invoke player control functions to perform playback.

Observering Ad Playback Events

You can listen events from FLAdYospacePlayer by observing fields on the ad player node. All the node fields can be observed for change as supported with SceneGraph. Please refer player component for the complete list of fields that provide ad events.

Sample demonstrating Ad state change observation

flPlayer.observeField(flPlayerFields.AD_BREAK_STARTED, "onAdBreakStarted")
flPlayer.observeField(flPlayerFields.AD_BREAK_FINISHED, "onAdBreakEnded")
flPlayer.observeField(flPlayerFields.AD_STARTED, "onAdStarted")
flPlayer.observeField(flPlayerFields.AD_FINISHED, "onAdEnded")

sub onAdBreakStarted(event as Object)
    adBreakStarted = event.getData()
    ? "adBreakStarted: ", adBreakStarted
end sub

sub onAdBreakEnded(event as Object)
    adBreakEnded = event.getData()
    ? "adBreakEnded: ", adBreakEnded
end sub

sub onAdStarted(event as Object)
    adStarted = event.getData()
    ? "adStarted: ", adStarted
end sub

sub onAdEnded(event as Object)
    adEnded = event.getData()
    ? "adEnded: ", adEnded
end sub

Ad Metadata

FLAdBreakInfo

Represents an ad break object. This object is available on observing ad break start and end.

Property	Type	Description
adBreakID	String	Ad Break Identifier
contentTimePosition	String	The position of the ad break, can be on of preroll, midroll or postroll
adBreakStartTimeOffset	Double	The start position in seconds
duration	Double	The duration of the ad break, in seconds
totalAds	Integer	Total number of adverts in the ad break

FLAdInfo

Represents an advert object. This object is available on observing ad break start and end.

Property	Type	Description
adID	String	The identifier of the advert
sequence	Integer	The sequence of the advert
adStartTimeOffset	Double	The start position in seconds
duration	Double	The duration of the advert in seconds
adBreakInfo	FLAdBreakInfo	The ad break which the advert belongs to
vastProperties	FLVastProperties	Represents a VAST properties object.

VASTProperties

Represents a VAST properties object.

Property	Type	Description
adSystem	String	The name of the system
adTitle	String	The title of the Ad.
description	String	The description of the Ad

RAF (Roku Advertising Framework)

Since Roku mandates all channel apps that include video advertising to use RAF, the fl-ad-yospace library uses RAF by default through Yospace library. The Yospace Ad Management SDK contains a class named YoRAFTasks which supports a subset of the Roku Advertising Framework (RAF) API functions.

RAF APIs with FLAdYospacePlayer

The ad player exposes the Yospace RAF APIs as follows.

RAF Functions

SET_CONTENT_GENRE
SET_CONTENT_ID
SET_CONTENT_LENGTH
SET_NIELSEN_GENRE
SET_NIELSEN_APP_ID

These functions can be invoked as follows:

Call RAF API function, using FLAdYospacePlayer

flPlayer.callFunc(m.flPlayerFunctions.SET_CONTENT_GENRE, "Drama, Dark Comedy")

flPlayer.callFunc(m.flPlayerFunctions.SET_CONTENT_LENGTH, "1800")

YoRAFTasks and Roku Library Private APIs

The Roku RAF library interface contains functions which are private, or which require a subscriber licence (for example, the Demand API). The fl-ad-yospace library is unable to support these directly. Instead, YoRAFTasks from Yospace library provides direct access to its instance of the RAF library interface in order that the client app may call such functions.

note

Please note you must include the Yospace library scripts to whichever component from where Yospace RAF api is consumed using. Check for script that has class YoRAFTasks with Yospace library and use the same.

For the YoRAFTasks API to work correctly, it is suggested to consume these APIs after FLAdYospacePlayer component init as Yospace library is prepared within ad player initialisation and before starting playback.

Example of how a client app might call a licensed function which retrieves data which it can then use to modify a stream URL

raftasks = YoGetRAFTasks()

' next, get the RAF library interface
adinterface = raftasks.GetAdInterface()

' use the interface to call the required licensed function
m.licensedData = adinterface.licensedFunction({licence_id: “1234”, tag_id: “TAG”})

The Object returned is an instance of Roku_Ads() and can be used to call any private or licensed function.

note

In order to ensure that the interface remains correctly synchronised with the Ad Management SDK, the client app must continue to call public RAF API methods using the YoRAFTasks interface.