Integrating OVA into an MRSS based Custom Player with an In-Player Playlist Controller

This tutorial explores how to integrate OVA to work with an MRSS based custom player that has an in-build playlist controller.

1. The Custom Player

The custom player works as follows:

1. The player loads an MRSS playlist (declared to the player as a flashvar)
2. An in-built playlist controller displays each show clip in the MRSS playlist
3. Users select the required clip to play
4. Upon selection, the player loads up and plays the clip

2. The OVA Integration Requirements

When OVA is integrated, the player is to work as follows:

1. The player loads an MRSS playlist - the MRSS playlist contains a custom field against each playlist item declaring the ad server call to make for the clip in question
2. The in-built playlist controller is to display the MRSS playlist items - no ad clips are to be displayed in the playlist
3. When a user selects a clip to play, the associated ad call is to be made resulting in the playback of a pre-roll clip before the selected show clip

3. The OVA Operating Model

Because an MRSS playlist may contain many clips, it does not make sense for OVA to instantiated once resulting in a flood of ad calls to obtain pre-rolls for each ad in the playlist.

The preferred model is to use OVA to load and manage the ad "on demand" as each clip is selected for playback.

Under this model, the player will control the playback of clips one clip at a time. It is responsible for loading the ad and show clips into the player as required when the user clicks on a clip in the playlist.

4. Implementing OVA to work "on demand" managing clip playback clip by clip

OVA is controlled via a class called VASTController.

To integrate OVA and implement an "on demand" playback model, complete these steps:

• Section 4.1: Implement the OVA org.openvideoads.vast.config.ConfigLoadListener interface
• Section 4.2: Instantiate an instance of the OVA VASTController via new VASTController()
• Section 4.3: Create an OVA configuration Object (just a raw AS3 Object), load in the show clips to schedule ads against and then pass that into the VASTController via _vastController.initialise(myConfig, false, this)
• Section 4.4: Wait for the VASTController to inform you that configuration process has been complete via the onOVAConfigLoaded() method (which is part of the ConfigLoadListener interface)
• Section 4.5: Implement ad register the additional OVA listener methods against the VASTController so that when OVA completes the ad calls and ad scheduling, the player can respond to the required playback actions that will be triggered by the VASTController
• Section 4.6: Ask the VASTController to get the ads and schedule them against the specified playlist
• Section 4.7: Respond to OVA callbacks (from the VASTController) as OVA completes the process of grabbing the ads and scheduling them
• Section 4.8: Start the playback of the new ad scheduled playlist and control the playback one clip at a time
• Section 4.9: Notify OVA when an ad stream plays and it's progress in terms of time played so that it can trigger the required ad tracking events, show/hide ad notices, companions etc.

4.1 Implementing the org.openvideoads.vast.config.ConfigLoadListener Interface

The org.openvideoads.vast.config.ConfigLoadListener interface is a key interface within OVA. It allows the OVA framework to callback to the player and inform it that it has finished configuring itself and is ready to go.

The interface is declared as follows:

package org.openvideoads.vast.config {
	public interface ConfigLoadListener {
		function isOVAConfigLoading():Boolean;
		function onOVAConfigLoaded():void;
	}
}

Two methods need to be implemented in your player - isOVAConfigLoading() and onOVAConfigLoaded().

The isOVAConfigLoading() is a low priority method that you do not have to implement this as part of your player implementation.

The onOVAConfigLoaded() method you do have to implement however.

In short, the player should only continue setting up OVA after OVA has reported that the config has been successfully loaded. In this sense, once the player gives the OVA framework the config via VASTController.initialise(), the player in essence blocks until OVA reports that the config is accepted and it is all ready to proceed.

4.2 Instantiating OVA

The following code illustrates how to instantiate the framework (the VASTController):

var _vastController:VASTController = new VASTController();

4.3 Configuring the OVA Framework (via the VASTController)

Typically to configure the OVA framework, the following code is used:

_vastController = new VASTController();

_vastController.startStreamSafetyMargin = 500; 	
_vastController.endStreamSafetyMargin = 500; 

// some code goes in here to create a configuration 
// Object that holds the OVA configuration

_vastController.initialise(rawConfig);

This code tells OVA to set a 500 millisecond delay on triggering tracking events at the start and end of ad clips, and to initialise itself with the supplied raw Object that contains the OVA configuration properties.

Eventually that OVA configuration object will be converted into an org.openvideoads.vast.config.Config object. The VASTController does this as part of the initialise() method.

Setting up the raw object is relatively straight forward.

There are two ways to setup the raw OVA configuration object:

• Directly as an AS3 object
• Indirectly via JSON configuration

4.3.1 Setting up the Raw OVA Configuration Object via JSON configuration data

This method is normally used if you have dynamic OVA configuration data that is loaded at runtime.

The following OVA JSON configuration represents a simple pre-roll setup with a direct ad server call. Some debug levels are also set.

{
    "debug": { "levels": "fatal, config, vast_template" },
    "ads": {
         "schedule": [
               {
                   "position": "pre-roll",
                   "tag": "your-ad-server-ad-tag-goes-in-here"
         ]
    }
}

To create a org.openvideoads.vast.config.Config object given this JSON setup, use the following code snippet (this code snippet uses the Adobe as3corelib JSON parser):

import org.openvideoads.vast.config.Config;
...

var ovaJSONData:String = "{ 'debug': { 'levels': 'fatal, config, vast_template' },
                                           'ads': { 'schedule': [ { 'position': 'pre-roll', 
                                           'tag': 'your-ad-server-ad-tag-goes-in-here' ] } }";

try {
   var rawConfig:Object = JSON.decode(ovaJSONData, false);
}
catch(e:Error) {
   // parsing exception when config read in
}

4.3.2 Setting up the Raw OVA Configuration Object directly as a AS3 Object

Alternatively you can setup the raw OVA config object directly.

This method is normally used if your OVA configuration data is static.

var rawConfig:Object ;
rawConfig = {
    debug: { levels: "fatal, config, vast_template" },
    ads: {
         schedule: [
               {
                   position: "pre-roll",
                   tag: "your-ad-server-ad-tag-goes-in-here"
         ]
    }
}

4.3.3 Adding Playlist Information to the OVA Configuration Data

When the OVA configuration information is passed into the VASTController, two parts of configuration need to be set:

• The ad schedule and general OVA configuration (as per the above examples)
• An account of the show streams in the playlist against which the ads are to be scheduled

OVA uses both of these pieces of configuration information to work out how many ads to request, the type and where they are to appear in a playback sequence.

Playlist clips are recorded in the OVA configuration object as configObject.shows.streams which is an Array of stream configuration Objects.

Let's look at an example - consider that we want to initialise OVA for a single show stream and against that show stream configure a pre-roll ad.

The easiest way to do this is to create an OVA configuration Object that has the following structure:

var rawConfig:Object ;
rawConfig = {
    debug: { levels: "fatal, config, vast_template" },
    shows: {
         streams: [
               file: "the-url-of-my-show-stream",
               duration: "the-duration-of-my-show-stream",
               customProperties: {
                    originalClipItem: place-your-original-clip-object-here-for-safe-keeping
               }
         ]
    }
    ads: {
         schedule: [
               {
                   position: "pre-roll",
                   tag: "your-ad-server-ad-tag-goes-in-here"
         ]
    }
}