Order Now AdSolution Sign Up | Login » Bits on the Run Sign Up | Login »

Open Video Ads

OVA Configuration Guide

This guide walks through the various configuration options available when using Open Video Ads.

1. Table of Contents

This guide is broken into the following sections:

Recommended Reading
Introduction
An Example Configuration
Configuration Structure
General Configuration Options
Player Specific Configuration Options
Show Stream Configuration Options
Overlay Configuration Options
Ad Configuration Options
Provider Configuration Options
Debug Configuration Options
1. The Debug Levels
2. Supported Debuggers

2. Recommended Reading

The following examples, guides and tutorials are recommended reading with this guide:

3. Introduction

A common approach to configuration is taken across all Open Video Ads products. The same configuration data will work for the framework, the JW Player plugins and the Flowplayer plugin.

Configuration data is specified in JSON form.

A wide range of configuration options are available to ensure that Open Video Ads can sequence and schedule just about any form of VAST compliant video advertising across any number of programme streams.

4. An Example Configuration

The following example is a more complex demonstration of the range of configuration options available. The code snippet below has been taken from a Flowplayer example. You can see this example running here, or if you want to view the equivalent JW Player example, you will find it here.

{
   "shows": {
      "streams": [
         {
            "file":"http://streaming.openvideoads.org/
                    shows/the-black-hole.mp4",
            "duration":"00:00:30"
         }
      ]
   },

   "overlays": {
      "regions": [
         {
            "id": "bottom",
            "verticalAlign": "bottom",
            "horizontalAlign": "center",
            "backgroundColor": "#000000",
            "width": 450,
            "height": 50
         }
      ]
   },

   "ads": {
      "servers": [
         {
            "type": "OpenX",
            "apiAddress": "http://openx.openvideoads.org/
                           openx/www/delivery/fc.php",
         }
      ],
      "schedule": [
         {
            "zone": "5",
            "position": "pre-roll"
         },
         {
            "zone": "33",
            "position": "bottom",
            "width": 450,
            "height": 50,
            "startTime": "00:00:05",
            "duration": "15"
         }
      ],
   },

   "debug": {
      "levels": "fatal",
      "debugger": "firebug"
   }
}

In the example above a single show stream (the-black-hole.mp4) is to play for 30 seconds. Before the show stream begins a pre-roll ad is to be served. During the playback of the stream an overlay ad is to be displayed in a region defined as "bottom". All debug output is to be sent to "firebug" as OVA operates.

To explore more configuration examples, review the following:

5. Configuration Structure

While reviewing that specific configuration it is important to acknowledge that the configuration data is broken into 7 separate "groupings":

General
Player
Show
Overlay
Ads
Provider
Debug

Each of these "groupings" have a specific set of configuration options that impact the way ads are played by the VAST Framework and OVA plugins.

As a result, at a high level a typical configuration template appears as follows:

{
   // "general" options here

   "player": {
       // player specific configuration items go in here
   },

   "shows": {
       // show stream options here
   },

   "overlays": {
       // overlay options here
   },

   "ads": {
       // ad schedule options here
   },

   "provider": {
       // provider settings go in here
   },

   "debug": {
       // debug configuration here
   }
}

The only grouping that is mandatory is the "ad" grouping - without that, OVA is unable to play any ads. The rest of the groupings are really supporting items for the scheduling of ads against show streams.

Let's assess the detailed options available in each of these configuration groups.

5.1 General Configuration Options

General configuration options are applied across all configuration groups. In general they apply to the way streams are to be played by the player (e.g. indicating if the ad streamer is only to serve "progressive" or "streaming" types, the bit rate of the streams, the type of stream (mp4 or flv), if file extensions are to be automatically removed, and the base address for streams.

A full example of a general config grouping options is as follows:

"autoStart": true,
"deliveryType": "progressive",
"removeFileExtension": true,
"blockUntilOriginalPlaylistLoaded": true  // JW plugins only

A description of each property follows:

Option	Values	Default	Description
assessControlBarState	true \| false	true	OVA for JW only: Specifies whether or not overlays and ad notices are to be repositioned based on whether or not the control bar shows and hides.
autoStart	true \| false	false	Trigger the player to automatically start playing the first stream once OVA has completed initialisation
blockUntil OriginalPlaylistLoaded	true \| false	false	JW OVA plugins only: Specifies whether or not the player is to block initialisation of the OVA plugin until the playlist is completely loaded. Required to ensure that the streams specified in an externally accessed XML file (e.g. RSS playlist etc.) are loaded into the player configuration before OVA tries to access them and schedule against against each. Consider this option mandatory for JW configurations that use external playlist files in the "file=" flashvar setting
canFireAPICalls	true \| false	true	Specifies if OVA can fire off the Javascript API callbacks as it operates.
deliveryType	progressive \| streaming \| any	any	Specifies the type of stream to be served - can be either "progressive", "streaming" or "any". "any" is the default. Overriding the default setting will be very rarely required unless you want to guarantee that only HTTP Progressive or RTMP/HTTP pseudo-streaming streams are specifically selected and played
ignoreOriginalSplashImage	true \| false	false	Used by OVA for JW5 only. When a pre-roll is the first stream in the playlist, set this to "true" to stop the flickering of the splash screen as the player initialises.
removeFileExtension	true \| false	false	Forces the removal of file extensions for video stream file names returned in the VAST response - particularly useful for ensuring that FLV streams plan on a streaming server that requires the ".flv" extension to be removed in the stream address

5.2 Player Specific Configuration Options

The "player" specific configuration group allows specific player oriented configuration items to be included in the OVA. For example, you may wish to ignore metadata completely when the player is reading the stream as well as maintain original aspect ratios on the streams that are played back. For Flowplayer, to achieve this type of behaviour you would specify the following config in the "player" configuration group:

"player": {
    "metaData": false,
    "scaling": "orig"
}

At present, this grouping is only used by the OVA for Flowplayer plugin. Any valid Flowplayer specific clip configuration property can be included here for application across all streams scheduled by OVA.

You can find an example of the player specific configuration options in action here.

5.3 Show Streams Configuration Options

While it is preferred that player specific show stream specification mechanisms (e.g. JSON based playlist definitions in Flowplayer, the "file=" flashvar in JW Player be used with OVA, it is possible to identify the show streams to play within an OVA configuration block. The "shows" configuration block exists for this purpose.

Below is an example of a "shows" configuration:

"shows": {
   "baseURL": "rtmp://ne7c0nwbit.rtmphost.com/videoplayer",
   "streams": [ 
       { 
         "file":"mp4:bbb_640x360_h264.mp4", 
         "duration":"00:00:35",
         "player": {
            "scaling": "orig"
         } 
       } 
   ]
   "autoPlay": true,
   "removeFileExtension": true
}

The "streams" configuration entry is probably the most important property in the "Shows" group as it declares the actual streams to be played. It is only mandatory field in the group.

A stream must be declared with either:

An optional baseURL address
With a fully qualified file address

The following examples illustrate valid show stream definitions:

"shows": {
    "baseURL": "http://streaming.openvideoads.org:81/shows",
    "streams": [
        {
            "file":"the-black-hole.mp4",
            "duration":"00:01:00",
            "providers": {
               "http": "pseudo"
            }
        }
    ]
}

In the case above, a single stream is defined to be served from a specific baseURL. The stream will be played via a "pseudo" streaming provider - if this is a Flowplayer setup, OVA will expect an appropriate provider plugin to be made available with the plugin ID "pseudo".

"shows": {
   "streams": [
       { 
          "file":"http://streaming.openvideoads.org/
                  shows/the-black-hole.mp4" 
       }
   ]
}

The example above illustrates the minimum stream configuration - in this case a single stream is provided without a duration or provider. It is assumed to be delivered using the standard HTTP provider and the duration will be derived from the stream metadata.

Option	Values	Default	Description
autoPlay	true \| false	false	A true or false value that identifies whether or not each stream is to automatically start playing
baseURL	URI	none	The base URL from which the file is to be served. In the case of an RTMP stream, the baseURL is normally the connection address of the RTMP server
deliveryType	progressive \| streaming \| any	any	The type of streams to be served - can be either "progressive", "streaming" or "any" to cover a mixed set of types
fireTrackingEvents	true \| false	true	OVA can fire a range of different Javascript events as show streams are played. These include onShowStart, onShowComplete, onShowStopped, onShowPaused, onShowResumed, onShowMute/Unmute and onShowFullscreen. If this option is set to "false" the tracking events will not be fired.
metaData	true \| false	true	Indicates whether or not the player should wait for the metadata information in the stream to be received before starting to play - always set to "false" if you notice a video can be heard but not seen - the value is "false" by default
player	Object	null	Player specific settings to be applied to the show streams only. See the "Player" configuration grouping section above to find out which properties can be set in here. At present this configuration option is only used for the Flowplayer OVA plugin
removeFileExtension	true \| false	false	Forces removal of file extensions for video stream file names returned in the VAST data - particularly useful for ensuring that FLV streams play on a streaming server
streams	list of streams	empty list	An array of stream definitions which identifies the main programme streams to be played by the player - ads are sequenced in accordance with the Ad Slot schedule against these streams. As the property is an array, the following format is expected [ { stream1-name, stream1-duration }, ... { streamN-name, streamN-duration} ]. The stream-duration must be declared in time stamp format HH:MM:SS (e.g. 01:10:15 for a duration of 1 hour 10 minutes and 15 seconds). Streams may be declared as a fully qualified filename (e.g. rtmp://ne7c0nwbit.rtmphost.com/vp/mp4:bbb.mp4) or as files relative to the baseURL declared in the shows configuration grouping.
streamType	mp4 \| flv \| any	any	A specific value that identifies the type of stream to be played - can be either "mp4", "flv" or "any"

For each show stream, a number of configuration options are available:

Option	Values	Default	Description
baseURL
duration	"HH:MM:SS"	"00:00:00"	The duration of the stream. Always specified in the format "HH:MM:SS". Not a mandatory field. If not specified the value will be derived from the stream metadata
file	String	None	The address of the file to serve. If no baseURL is specified, the file address must be fully qualified (e.g. "http://..." or "rtmp://...")
player	Object	None	Player specific settings - see the "Player" configuration grouping details for options that can be provided here. Currently only used by the Flowplayer OVA plugin
providers	Object	{ "http":"http", "rtmp":"rtmp"}	A string value that can be used by an OVA plugin to identify the "provider" to use to stream the file - in the case of Flowplayer, this will be a provider plugin ID. Values by default are "http" for HTTP streams, "rtmp" for RTMP streams.

5.4 Overlay Configuration Options

The "overlays" configuration grouping allows multiple rectangular "regions" to be defined on the player canvas. These regions in turn can be used to display non-linear (overlay) advertising, ad notices and general messages.

A region is in essence a region of the player stage that allows various types of content (text, limited html, swf objects and images) to be inserted via using a restricted set of HTML tags.

This example illustrates the the overlay configuration grouping in action.

5.4.1 General Overlay Configuration Options

Overlays support a number of configuration options at a general level as illustrated by the following code snippet:

{
   ...
   "overlays": {
       "stagePaddingBottomNoControls": 2,
       "stagePaddingBottomWithControls": 30,
       "regions": [
          // an array of region declarations
       ]
   }
   ...
}

Option	Values	Default	Description
regions	array	None	An array of region declarations - see the section below on how to declare individual regions for a description of the values that can be specified here
stagePaddingBottomNoControls	int	0	The number of pixels to leave as margin at the base of the player stage when displaying regions during playback where the player does not have a visible control bar
stagePaddingBottomWithControls	int	0	The number of pixels to leave as margin at the base of the player stage when displaying regions during playback where the player does have a visible control bar

5.4.2 Overlay Templates

As Non-linear ads may be of the form:

Text
HTML
Flash (SWF)
Image (JPG, PNG, GIF - including animated GIF)

Overlay regions can also take these forms. For each form is a default "template" that is used to identify how to place the "overlay" content into a region.

The default template for text overlays is:

<body> 
      <p align='left' class='title'>_title_</p>
      <p align='left' class='description'>_description_</p> 
      <p align='left' class='callToActionTitle'>_callToActionTitle_</p>
</body>

The default template for HTML overlays is:

<body>_code_</body></pre>

The default template for overlays of type image is:

<img src='_code_'/>

Flash (SWF) files are placed directly into the region using the AS3 framework.

For more information on how to override the default overlay template and customise the way overlay content is placed into a region, refer to section 5.5.6.2 Modifying Overlay Templates.

5.4.3 Declaring Regions

By default, 14 regions have been declared for general use by non-linear ads and system messages.

reserved-bottom-w100pct-h78px-000000-o50 - a region at the bottom of the player screen, 100% wide, 78 pixels high, with a black background at 50% opacity, with an active close button
reserved-bottom-w100pct-h50px-000000-o50 - a region at the bottom of the player screen, 100% wide, 50 pixels high, with a black background at 50% opacity, with an active close button
reserved-bottom-w100pct-h50px-transparent - a region at the bottom of the player screen, 100% wide, 50 pixels high with a transparent background, with an active close button
reserved-bottom-w100pct-h50px-transparent-0m - a region at the bottom of the player screen, 100% wide, 50 pixels high with a transparent background, 0 margins all around, with an active close button
reserved-bottom-w450px-h50px-000000-o50 - a region at the bottom of the player screen, 450 pixels wide, 50 pixels high, with a black background at 50% opacity, with an active close button
reserved-bottom-w450px-h50px-transparent - a region at the bottom of the player screen, 450 pixels wide, 50 pixels high, with a transparent background, with an active close button
reserved-bottom-w450px-h50px-transparent-0m - a region at the bottom of the player screen, 450 pixels wide, 50 pixels high, with a transparent background and 0 margins all around, with an active close button
reserved-bottom-center-w450px-h50px-000000-o50 - a region at the bottom center of the player screen, 450 pixels wide, 50 pixels high, with a black background with 50% opacity, with an active close button
reserved-bottom-center-w450px-h50px-transparent - a region at the bottom center of the player screen, 450 pixels wide, 50 pixels high, with a transparent background, with an active close button
reserved-bottom-center-w450px-h50px-transparent-0m - a region at the bottom center of the player screen, 450 pixels wide, 50 pixels high, with a transparent background, 0 margins all around
reserved-bottom-center-w300px-h50px-000000-o50 - a region at the bottom center of the player screen, 300 pixels wide, 50 pixels high with a black background with 50% opacity, with an active close button
reserved-bottom-center-w300px-h50px-transparent - a region at the bottom center of the player screen, 300 pixels wide, 50 pixels high with a transparent background, with an active close button
reserved-bottom-center-w300px-h50px-transparent-0m - a region at the bottom center of the player screen, 300 pixels wide, 50 pixels high with a transparent background, 0 margins all around, with an active close button
reserved-system-message - a thin region at the base of the player screen, 100% wide, 20 pixels high, no close button, and 2 font definitions - one large sized writing 12pt (class if normaltext), one small sized writing 10pt (class is smalltext)

In addition, any number of customised regions can be declared. To illustrate how this is done, review the following Flowplayer Ad Streamer example that illustrates the options that are declared for the default "message" region:

....
    "overlays": {
            "regions": [
                 { 
                     "id": "message",
                     "verticalAlign": "bottom",
                     "horizontalAlign": "right",
                     "width": "100%",
                     "height": 20
                 } 
             ]
    },
....

Region configurations can be quite complex. There is a wide range of options that can be specified to define the "appearance" of a region. Many of these options mirror the standard CSS style attributes.

Here is a more example configuration:

....
            "regions": [
                  {
                      "id": "top-center",
                      "verticalAlign": "top",
                      "horizontalAlign": "center",
                      "backgroundColor": "#000000",
                      "opacity": 0.8,
                      "borderRadius": 15,
                      "padding": "-10 -10 -10 -10",
                      "width": 450,
                      "height": 50
                  }
            ]
....

5.4.4 The Default Overlay Ad Type/Region Mappings

By default, each region format has a default pre-defined region that is set. If no region is specified for an AdSlot, the default region ID is chosen based on the width of the overlay and type of creative. The following code snippet identifies the ID of each region selected given a creative type and width:

if(width == 300) {
	regions.text = "reserved-bottom-w300px-h50px-000000-o50";
	regions.image = "reserved-bottom-w300px-h50px-transparent-0m";
	regions.swf = "reserved-bottom-w300px-h50px-transparent";
	regions.html = "reserved-bottom-w300px-h50px-000000-o50";								
}
else if(width == 450) {
	regions.text = "reserved-bottom-w450px-h50px-000000-o50";
	regions.image = "reserved-bottom-w450px-h50px-transparent-0m";
	regions.swf = "reserved-bottom-w450px-h50px-transparent";
	regions.html = "reserved-bottom-w450px-h50px-000000-o50";				
}
else {
	regions.text = "reserved-bottom-w100pct-h78px-000000-o50";
	regions.image = "reserved-bottom-w100pct-h50px-transparent-0m";
	regions.swf = "reserved-bottom-w100pct-h50px-transparent";
        regions.html = "reserved-bottom-w100pct-h50px-000000-o50";
}

5.4.5 Region Configuration Options

A wide range of configuration options are available for a region. You can define regions of pretty much any shape and style. Below is a complete list of the options available:

Option	Values	Default	Description
background	String	None	A shorthand way of setting all background properties at once. Similar to CSS. The format is as follows: backgroundImage backgroundRepeat left top. For example: url(/my/image.jpg) no-repeat 100 30. The last two numbers specify the background image positioning
backgroundColor	String	None	Background color as a hexadecimal value. For example: #ffcccc. The length of the value is 6 characters and the prefix # is optional.
backgroundImage	String	None	The absolute or relative path to the image that should be used as the background to this plugin. Supported formats are GIF, JPEG and PNG. The syntax is similar to CSS in that you must enclose your path inside a url() wrapper. See example above
backgroundGradient	String	None	Defines a region's background gradient (ie, the way the background is faded in and out vertically). The value can be one of the predefined values "low", "medium" or "high", or you can supply an array of values, each one representing how much transparency is applied at a particular point. For example, the array [0.2, 1.0] means that the background will be 80% visible at the top edge and 0% visible at the bottom, and there will be a linear gradient of transparency between the two edges. You can supply any number of point definitions in your array and they will be placed so that there is equal distance between them. For example, passing the array [0.4, 0.6, 1.0] will result in points at the top, middle and bottom of the background
backgroundTransparent	true \| false	false	Defines whether or not a region is to be transparent. Values are true or false - the default is false
border	String	0px none	Draws a border around a region's edges. The syntax follows the CSS standard: width style color. For example: "1px solid #cccccc". The only supported style currently is "solid", but the width and colour can be set to any valid value
borderColor	String	#000	A CSS style hex value that specifies the color to apply for the border
borderRadius	Numeric	0	Specifies the amount of rounding for each corner. Larger values mean more rounding
borderWidth	Xpx	0px	A CSS style value in pixels that specifies the width of the border
clickable	true \| false	true	Identifies whether or not the region is to be clickable. This value does not override any click action properties that may be defined on at the HTML level for the objects shown in the region. This value enables or stops theOnClick() javascript callback from firing
height	Y% \| Ypx		Specifies the height of the region - the values can either be numeric (the number of pixels) or a percentage of the screen width (e.g. '100%')
horizontalAlignment	left \| right \| X	None	Specifies the horizonal alignment of the region - values can be 'left', 'right' or a numeric value representing the X coordination (in pixels)
html	String	None	Specifies the initial HTML content to be loaded by default for the region
id	String	None	very region that is declared using the regions tag must be identified by a unique name. This id is used by OVA to identify which region is to be used to display a specific overlay or non-overlay AdSlot
padding	String	0 0 0 0	Specifies the level of padding to be allocated inside of the region - uses the standard CSS format - top right bottom left
showCloseButton	true \| false	true	Indicates whether or not a close button is to be shown on the region
style	Object	None	A styling object that is specified directly in the configuration. If an external stylesheet is in use, these settings override those external settings. You can find more information about styling here
stylesheet	URI	None	Path to the stylesheet file which specifies how each tag in the content is styled. You can find more information about styling here
verticalAlign	top \| bottom \| Y	None	Specifies the vertical alignment of the region - values can be 'top', 'bottom' or a numeric value representing the Y coordination (in pixels)
width	X% \| Xpx	None	Specifies the width of the region - the values can either be numeric (the number of pixels) or a percentage of the screen width (e.g. '100%')

5.5 Ads Configuration Options

The Ads grouping captures all ad specific configuration settings.

An example configuration is as follows:

"ads": {
   "servers": [
       {
          "type": "OpenX",
          "apiAddress": "http://openx.openvideoads.org/
                         openx/www/delivery/fc.php"
       }
   ],

   "schedule": [
       {
          "zone": "1",
          "position": "pre-roll"
       },
       {
          "zone": "2",
          "position": "bottom",
          "width": 450,
          "height": 50,
          "startTime": "00:00:05",
          "duration": "15"
       }
   ],
}

In this example the ad server is defined to be of type "OpenX", a request URL is specified, and an ad schedule is defined as two separate ad slots - a pre-roll ad followed by a non-linear ad (overlay) placed in the region named "bottom".

Generally speaking, an ad configuration grouping has three sets of configuration data:

"ads": {
    // general level settings
    "notice": {},
    "clickSign": {},
    "companions": {},
    "servers": [],
    "schedule": []
}

5.5.1 Configuring ads at a general level

General settings specify the general behaviour of OVA when it plays ads. A limited number of general options are available. A typical configuration that includes "general" ad level configuration options appears as follows:

"ads": {
    "disableControls": false,
    "keepOverlayVisibleAfterClick": true,
    "pauseOnClickThrough": true,
    "displayCompanions": false,
    "processCompanionsExternally": true,
    "restoreCompanions": false,
    "setDurationFromMetaData": true    
}

The options that can be used include:

Option	Values	Default	Description
disableControls	true \| false	true	Indicates whether or not the ability to skip through an ad (via the controlbar) is enabled/disabled during playback
displayCompanions	true \| false	true	Indicates whether or not the ability to display companions is enabled. Companions will not be displayed unless the DIV containers are specified via the "companions" options (see the section below on how to enable companions)
keepOverlayVisibleAfterClick	true \| false	false	Instructs OVA to either hide or keep an overlay visible on the player screen after it has been clicked. False by default.
pauseOnClickThrough	true \| false	true	Indicates whether or not OVA is to pause the current ad stream if the user clicks on an ad during playback
restoreCompanions	true \| false	true	Identifies whether or not the original DIV content should be restored to the DIV after the companion ad has been displayed for the required duration. By default the content is restored which makes companions appear and disappear. Use false to turn that feature off.
setDurationFromMetaData	true \| false	true	Indicates whether or not OVA should derive the ad duration from the stream metadata. By default this option is set to true which means that if the duration specified for an ad in the VAST response differs from the actual stream duration, the stream duration will override the VAST value. Set this option to false to take the VAST value as the truth.
millisecondsDelayOnCompanionInjection	n	0	Specifies the number of milliseconds to wait between the insertion of each companion into the page. 0 (off) by default.

5.5.2 Configuring the Ad Notice

When a linear pre, mid or post-roll ad stream is played, an "ad notice" can be displayed.

A range of examples have been provided to illustrate changes to the ad and click-through notices. You can find them here.

By default the notice reads "This advertisement runs for X seconds" where X is the duration of the ad. The notice appears in the bottom right hand side of the player screen, typically just above the player controlbar.

The default region used by the ad notice is "reserved-system-message"
The reserved-system-message region:
- Is placed in the bottom 50 pixels of the player screen (excluding the controlbar)
- Covers the width of the player screen
- Has two text styles defined:
  - "smalltext" - fontsize: 10pt; font-family:"sans-serif"; font-style: normal; color: #CCC;
  - "normaltext" - fontsize: 12pt; font-family:"sans-serif"; font-style: normal; color: #CCC;

The content, location and styling of the ad notice can be modified using both the "notice" configuration option and optionally, new overlay/region definitions. The ad notice can also be turned off.

5.5.2.1 Changing the Ad Notice Text

It is possible to just change the text of the ad notice with the following config:

"ads": {
   ...
   "notice": { 
       "message": "&lt;p class=\"smalltext\" align=\"right\"&gt;
                   My New Ad Notice - _seconds_ seconds&lt;/p&gt;"
   }
   ...
}

_seconds_ is a reserved word that will be replaced with the ad duration.

5.5.2.2 Deploying a Countdown Ad Notice

A countdown ad notice can be set - a "countdown" ad notice displays the time remaining in the ad notice.

The default wording for the countdown timer is:

"This advertisement runs for X seconds"

where the X is progressive reduced as the ad plays.

The following config snippet illustrates how to set a countdown ad notice.

"ads": {
   ...
   "notice": { "type": "countdown" },
   ...
}

When changing the text of a "countdown" ad notice, use the reserved word _countdown_ to identify where the reducing seconds total is to be placed in the new ad notice text.

5.5.2.3 Changing the Appearance of the Ad Notice

The following configuration snippet illustrates how to change both the appearance and text of the ad notice:

...
  "overlays": {
     "regions": [
         {
            "id": "my-ad-notice",
            "verticalAlign": "bottom",
            "horizontalAlign": "right",
            "backgroundColor": "transparent",
            "width": "100pct",
            "height": 40,
            "style": ".smalltext { font-style: italic; font-size:10; }"
         }
      ]
  },

  "ads": {
      "servers": [
         {
            "type": "OpenX",
            "apiAddress": "http://openx.openvideoads.org/
                           openx/www/delivery/fc.php",
         }
      ],
      "schedule": [
         {
            "zone": "5",
            "position": "pre-roll",
            "notice": {
                "show": true,
                "region": "my-ad-notice",
                "message": "&"
            },
         }
      ]
  },
...

To modify the standard appearance (placement on the screen or the colors etc.) of the ad notice, a new region is defined. In the example above, this region is identified as "my-ad-notice".

To associate the new region with the ad notice, a "notice" configuration is placed into the ad schedule and the region "my-ad-notice" specified. Any styles to be applied to the ad notice text are derived from the associated ad region.

5.5.2.4 Changing the Size of the Ad Notice Text

There are easier ways to change the ad notice. For example, say you just want to use "smalltext" when displaying the ad notice. The following configuration achieves this:

"ads": {
   ...
   "notice": { "textStyle": "smalltext" },
   ...
}

"smalltext" is a valid value because it is one of the pre-defined styles for the reserved-system-message region. "normaltext" would be used to set the message to a standard 12pt size font.

5.5.2.5 The Ad Notice Configuration Options

The following table summarises the configuration options available to modify the ad notice:

Option	Values	Default	Description
message	HTML String	"This advertisement runs for X seconds"	An option that allows the default ad notice text to be modified. The value must be a valid HTML string. An example is "&;lt;p align=\"right\" class=\"smalltext\">My New Ad Notice - _seconds_ seconds&lt/p>". Two reserved words can be used to identify the ad duration - _seconds_ and _countdown_
region	String	reserved-system-message	Identifies the region to be used to display the ad notice. The ad notice uses the default system message region by default. That region has two text styles pre-defined - smalltext and normaltext
show	true \| false	true	Turns the ad notice on and off. By default it is on - true
textStyle	String	normaltext	Allows a pre-defined text style to be identified for use with the ad notice. By default the ad notice is shown with a CSS style called "normaltext". If the ad text is to be displayed in small text, use "smalltext" with the reserved-system-message region

5.5.3 Configuring the Linear Click-Through Notice

The Linear "Click-Through" Notice appears when a pre, mid or post-roll ad stream is played and that ad has a "click-through" specified on it. When the user mouses over the ad stream, a "Click Me" notice appears on the screen.

5.5.3.1 Modifying the Appearance of the Notice

The appearance and text of default message can be changed.

The following config snippet illustrates the range of options available to change the Click-Though Notice.

"ads": {
   ...
   "clickSign": {
       "enabled": true, 
       "verticalAlign": "center",
       "horizontalAlign": "center",
       "width": 150,
       "height": 32,
       "opacity": 0.5,
       "borderRadius": 20,
       "backgroundColor": "#000000",
       "style": ".smalltext { font-size:12pt; }",
       "html": "&lt;p class=\"smalltext\" align=\"center\"&gt;
                CLICK ME!&lt;/p&gt;",
       "scaleRate": 0.75
   },
   ...
}

Most of the options impact the appearance of the notice. To change the text, the "html" option is used. The notice displays a message based on a HTML template that is configured.

The following configuration snippet illustrates how to change the text of the message:

"ads": {
   ...
   "clickSign": { 
       "html": "&lt;p class=\"smalltext\" align=\"center\"&gt;
                MY NEW CLICK-THROUGH TEXT&lt;/p&gt;"
   }
   ...
}

You will notice when the "html" option is used, the HTML tags are specified using "<" and "gt;" for the "less-than" and "greater-than" signs, and all quotes are escaped with a slash ("\"). This ensures that the HTML is effectively parsed when read in JSON form.

<p class="smalltext" align="center">MY NEW CLICK-THROUGH TEXT</p>

is entered as:

&lt;p class=\"smalltext\" align=\"center\"&gt;
MY NEW CLICK-THROUGH TEXT&lt;/p&gt;

The styling of the text can be changed by specifying new styles and applying those to the HTML. The styling options mirror those that can be used to define new regions.

By default, a single text CSS style is defined:

smalltext - defined as "{ font-size: 10pt; }"

It is very easy to change the text of the message and the CSS style used to display it. The following code snippet illustrates an example:

"ads": {
   ...
   "clickSign": {
       "style": ".my-style { font-family: sans-seif; 
                 font-size:14pt; font-style: normal; color:#CCC;",
       "html": "&lt;p class=\"my-style\" align=\"center\"&gt;
                MY NEW MESSAGE&;lt;/p&gt;" 
   }
   ...
}

The range of configuration options available to change the appearance of the click-through notice reflect the same options that can be used to define a region - backgroundColor, width, height etc. Refer to the section on "Declaring Regions" to view the various properties that can be used on the Ad Notice configuration block.

5.5.3.2 Turning off the Click-Through Notice

To turn off the click-through notice, use the following configuration option:

...
    "clickSign": { 
        "enabled": false 
    },
...

5.5.4 Configuring Companions

OVA is capable of triggering the display of "companion" ads to accompany linear or non-linear ads.

A companion ad can be of the following types:

Static - image (JPG, GIF or PNG) or SWF
IFrame
HTML

OVA places companion ads into <DIV> blocks on the containing HTML page.

A single option is required to enable Companion ads on a web page:

"companions": [ { companion-descriptor-1 }, { companion-descriptor-2 } ... { companion-descriptor-N } ]

The following configuration snippet illustrates a typical OVA companion configuration block:

...
  "restoreCompanions": false,
  "companions": [
     { 
         "id":"companion-160x600", 
         "width":"160", 
         "height":"600" 
     },
     { 
         "id":"companion-300x250", 
         "width":"300", 
         "height":"250" 
     }
  ],
...

In the example above, two companion regions are identified on the surrounding web page - the first region is 160x600 pixels in size, the second 300x250 pixels. The first region has a DIV ID "companion-160x600", the second "companion-300x250".

When OVA runs, it searches for companions that match the dimensions of the specified companion descriptors. If the dimensions are matched, then the appropriate content is generated and inserted into the DIV with the specified ID.

"restoreCompanions" specifies that the original DIV content is to be restored after the associated ad duration has been shown. This has the effect of showing and hiding ad related companions on the page.

"millisecondsDelayOnCompanionInjection" can be used to specify the number of milliseconds to wait between insertion of the companion code. This option can be useful if a significant number of SWF companions are to be inserted into a page at once loading down the browser as they startup.

The display of companion ads can be disabled via the "displayCompanions": false option.

5.5.5 Configuring the Ad Server(s)

OVA obtains the information needed to display a video from a VAST compliant ad server.

To identify the way OVA is to address that ad server, the "servers" configuration option is required within the "ads" configuration block.

The following configuration snippet illustrates a typical ad server configuration - in this case, for calls to AdTech:

...
  "ads": {
      "servers": [
          {
              "type": "AdTech",
              "apiAddress": "http://adserver.adtech.de/?adrawdata/3.0/990.1",
          }
      ],
      "schedule": [
          {
              "zone": "2366662/0/1725", 
              "position": "pre-roll"
          },
          {
              "zone": "2366662/0/1725",
              "position": "post-roll"
          }
      ]
  }
...

5.5.5.1 Out-of-the Box Ad Server Support

Some ad servers allow more complex calls to be configured to support targeting, aggregation of multiple ads in 1 response etc. Others don't and use standardised URLs that can be directly called without first being manipulated by OVA.

OVA supports a number of ad servers out-of-the-box. These include AdTech, OpenX, OASIS, 24/7 Real Media, Adify and Google DoubleClick.

For each of the out-of-the-box ad servers that OVA supports, a specific Configuration Guide is provided. Refer to the guide Configuring OVA to work with VAST Ad Servers or the Supported Ad Servers guide for a detailed account of how to configure of these ad servers.

5.5.5.2 Using Ad Tag URLs Directly

Regardless, OVA supports calls to all VAST compliant ad servers.

If an ad server type is not explicitly supported, the ad server "type" can be specified as "direct" and the complete ad tag (URL) specified.

The following configuration snippet illustrates a "direct" ad server call:

...
   "ads": {  
       "pauseOnClickThrough": true, 
       "schedule": [ 
          { 
              "position": "pre-roll", 
              "server": { 
                  "type": "direct", 
                  "tag": "http://adserver.adtech.de/
                          ?adrawdata/3.0/990.1/
                          2366662/0/1725/noperf=1;
                          cc=2;header=yes;alias=myalias; 
                          cookie=yes;adct=204;
                          key=key1+key2;grp=[group]; 
                          misc=__random-number__" 
              } 
          } 
       ] 
   }
...

For a complete account of how to use direct addressing with an ad server, refer to the Direct: OVA Configuration Guide.

Take Care with Ampersands

If the ad tag that you are inserting has ampersands in it (e.g. value&value&value), the ampersands must be replaced with "__amp__" to ensure that the OVA JSON configuration is correctly parsed. When OVA formulates the final ad server call, the __amp__ values are replaced with actual ampersands in the URL.

The following configuration snippet illustrates a direct ad server call where the ampersands have been replaced in the OVA configuration:

...
   "ads": {
       ...
       "schedule": [
           {
               "position": "pre-roll",
               "server": {
                  "type": "Adify",
                  "tag": "http://ad.afy11.net/ad?
                          enc=4__amp__asId=1000002629107
                          __amp__sf=0__amp__ct=256"
               }
           }
       ]
   }
...

5.5.5.3 Ad Server Configuration Examples

A range of ad server configuration examples have been provided for OVA for Flowplayer and OVA for JW Player. Consult these examples to gain insight into how to best configure your ad server to work with OVA.

5.5.6 Configuring the Ad Schedule

The core function of OVA is to schedule a range of ad types against a set of show streams.

The central element of the OVA configuration is therefore the ad schedule that details which ad types are to be scheduled when against the specified show streams. For example, if a pre-roll, mid-roll and post-roll linear video ad were to be scheduled when a stream plays, three individual ad spots would have to be defined - one for each video ad type. If alternatively a pre-roll and overlay ad were to be scheduled, two unique ad spot definitions would be required.

Ad Spot definitions can be limited to a particular "stream" or duration, and in the case of overlay/non-overlay video ads, can be scheduled to start at a particular time during a programme stream.

Ad Spots are defined as an array with the format [ { adspot1-options }, ... { adSpotN-options} ]. Each ad definition may contain:

A zone (optional)
A position (mandatory)
A duration (optional)
An ad server declaration (optional)

In addition, Overlay and Non-Overlay ads must also define a width and height.

5.5.6.1 Identifying Ad Positions

The following configuration snippet illustrates an ad schedule that declares a pre-roll, overlay and post-roll ad requirement, where the pre-roll is limited to the first show stream, the overlay is to be played on all streams 5 seconds into the stream for 15 seconds while the post-roll only on the third show stream:

...
   "ads": {
       "schedule": [
           {
              "zone": "5",
              "position": "pre-roll",
              "applyToParts": [0]
           },
           {
              "zone": "33",
              "position": "bottom",
              "startTime": "00:00:05",
              "duration": 15,
              "width": 300,
              "height": 50
           },
           {
              "zone": "6",
              "position": "post-roll",
              "applyToParts": [2]
           }
       ]
   }
...

The following table summarises the ad schedule configuration options that are available:

Option	Values	Default	Description
applyToParts	Array	None	Allows an ad spot declaration to be restricted to a specific set of programme streams. The value is specified as an array of integers between 0 and the number of programme streams declared. For example if an Ad Spot is to be limited to only the first stream, a value of [0] would be declared. To limit a spot to the second and third streams [2,3] would be declared and so forth.
duration	Seconds	Unlimited	The duration of an ad - mandatory in the case of time restricted non-linear overlay and non-overlay ads. The value is specified as a number of seconds or 'unlimited' if the ad is to play for the entire duration of the programme stream. The default value is unlimited.
height	Integer	0	The height of the ad spot - applicable for non-linear overlay/non-overlay ads which are bound by strict dimensions. An ad must be found in the VAST data to match this width to ensure that it is displayed.
notice	Object	n/a	Identifies whether or not a special notice is to be displayed when a video ad plays. For example, wording such as "This advertisement runs for 30 seconds" may be displayed. Notices are declared in the format { show: value, region: value, message: value, ...} where show is a true or false value, region is the id of the region where the message is to be shown and message is a HTML text block that specifies what to show. The message can contain a keyword _seconds_ to allow the duration of the ad to be placed into the text when the message is shown. Any class styling defined in the message must be declared as available in the associated region declaration.
position	String	None	The position of this ad - can be one of the following values: for linear ads pre-roll, mid-roll, post-roll, for non-linear overlay and non-overlay ads the value must be specified as a region ID.
startTime	HH:MM:SS	00:00:00	The time an ad is to start - used by mid-roll and non-linear ads to identify when an ad is to be started during the programme stream. The value must be specified in the form of a timestamp 'HH:MM:SS'
server	Object	None	Definition of the ad server call to be made to acquire the creative for this ad spot. See the second on Configuring Ad Servers for a description of how to configure an ad call at the Ad Spot level
template	Object	None	Allows the default template for various overlay content types to be overridden. The setting takes the form of { html: "", text: "", image: "" }. See the section below entitled Modifying the Default Overlay Templates for more information on this configuration option.
width	Integer	0	The width of the ad spot - applicable for non-linear overlay/non-overlay ads which are bound by strict dimensions. An ad must be found in the VAST data to match this width to ensure that it is displayed.
zone	String	None	A string value that provides a unique identifier for this ad slot when a call is made to an ad server. See the OpenX, AdTech etc. Ad Server Configuration Guides for more information on how zones are used

5.5.6.2 Attaching an Ad Server Call to an Ad Spot

Using the "server" configuration option it is possible to attach a specific ad server call to an ad spot.

The following configuration example illustrates how this is achieved:

...
   "ads": {  
       "pauseOnClickThrough": true, 
       "schedule": [ 
          { 
              "position": "pre-roll", 
              "server": { 
                  "type": "direct", 
                  "tag": "http://adserver.adtech.de/
                          ?adrawdata/3.0/990.1/
                          2366662/0/1725/noperf=1;
                          cc=2;header=yes;alias=myalias; 
                          cookie=yes;adct=204;
                          key=key1+key2;grp=[group]; 
                          misc=__random-number__" 
              } 
          } 
       ] 
   }
...

The "server.tag" configuration option allows an ad server ad tag URL to be directly attached to an ad slot. When OVA requires the creative for that ad slot, that URL is called to obtain the VAST response.

5.5.6.2 Modifying the Overlay Ad Templates

The content for an overlay is derived based on the overlay type.

If the overlay is of type "text", then a "text" is formulated using a HTML template, and the resulting HTML string is then inserted into the region.

Image based overlays are constructed using the HTML img tag.

HTML overlays are inserted directly with a surrounding set of <body> tags.

It is possible to override the default template for each overlay type to customise it's appearance on your site.

The following code snippet illustrates how to use the "templates.html" configuration option to override the template for HTML overlay types.

"ads": {
    "schedule": [
        {
            "zone": "31",
            "startTime": "00:00:05",
            "duration": "15",
            "templates": {
               "html": "&lt;body&gt;MY NEW TEMPLATE: _code_&lt;/body&gt;",
            }
        }
    ],
}

If the image overlay template is to be overridden use the configuration option "image" (e.g. "templates": { "text": "new value" }).

For text overlay types, use the "text" configuration option.

5.5.6.3 Mapping Overlay Ad Slots to Regions

When overlay ad spots are scheduled, they must be mapped to a valid, pre-defined overlay region.

By default, a range of overlay regions have been pre-defined to cover the top, bottom, center, left and right of the player screen. These regions can be used to place the overlay without a requirement to specifically define a custom region. Refer to the section in this guide entitled "Declaring Regions" to review the full set of pre-defined regions.

The following code snippet illustrates how to define an overlay based ad spot that is to be shown at the bottom of the player screen using a region with a transparent background.

...
  "ads": {
      "servers": [
          {
             "type": "OpenX",
             "apiAddress": "http://openx.openvideoads.org/
                            openx/www/delivery/fc.php"
          }
      ],
      "displayCompanions": true,
      "companions": [
          { "id":"companion", "width":"150", "height":"360" }
      ],
      "schedule": [
          {
             "zone": "29",
             "startTime": "00:00:05",
             "duration": "15", 
             "position: "reserved-bottom-center-w450px-h50px-transparent"
          }
      ],
  },
...

It is possible however to leave out the "position" setting for an overlay. In this case, the default "region" for the overlay type will be selected.

The default regions per overlay type are as follows:

text: reserved-bottom-w450px-h78px-000000-o50
html: reserved-bottom-w450px-h50px-000000-o50
image: reserved-bottom-w450px-h50px-transparent-0m
swf: reserved-bottom-w450px-h50px-transparent

5.6 Provider Configuration Options

The "providers" configuration block allows new player streaming providers to be specified.

By default, the following settings are active in the OVA framework:

"providers": {
    "http": "http",
    "rtmp": "rtmp"
}

The providers block is currently only actively used by OVA for Flowplayer. By default when a HTTP stream is to be played, the default Flowplayer HTTP streaming provider is used. If you wish to override the default and use a pseudo-streaming plugin for instance, the Flowplayer Plugin ID configured to provide pseudo-streaming would be provided as the "http" provider setting.

"providers" {
    "http": "pseudo"
}

Equally, if a different RTMP streaming provider plugin is to be used, the "rtmp" value would be overridden with the required Flowplayer plugin ID.

Please refer to the How to Configure New Providers tutorial for more information on this option.

5.7 Debug Configuration Options

The debug level output by OVA is controlled via the "debug" configuration group. A typical configuration is:

"debug": {
      "debugger": "firebug",
      "levels": "fatal, config, vast_template"
},

If you do not specify a debug configuration, a default level of "fatal" is assumed. "Levels" are specified as a comma delimited list.

5.7.1 The Debug Levels

To fine tune and identify the debug information to output, a range of options can be specified in the levels configuration parameter

The following table identifies the various debug information categories that can be output:

Option	Description
all	Prints all debug messages
clickthrough_events	Prints debug messages associated with click through events
cuepoints_events	Prints all debug messages fired when cuepoints are triggered
config	Prints all debug messages generated as the config data is read
cuepoint_formation	Prints all debug messages associated with establishing cuepoints
display_events	Prints all debug messages associated with non-linear ad display events
fatal	Prints all debug messages marked as fatal
http_calls	Prints all debug messages generated as HTTP calls are made
mouse_events	Prints all debug messages associated with mouse events
none	Turns off all debug output
playlist	Prints all debug messages generated as playlists are manipulated
region_formation	Prints all debug messages associated with the construction of regions
segment_formation	Prints all debug messages generated when the stream sequence is formed
tracking_events	Prints all debug messages tied to tracking events
tracking_table	Prints all debug messages tied to the tracking table
vast_template	Prints debug messages generated during requesting and parsing the VAST ad data

5.7.2 Supported Debuggers

At present only the firebug console is supported.