LongTail Video is now JW Player - New Name, Same Passion For Video

Close

Open Video Ads Support

Configuration Guide

Please note that this support doc applies only to the JW Player 5 Open Video Ads Plugin (OVA). JW Player 6 has built-in VAST/VPAID support. See the JW6 product pages and support guides for more info.

Purpose

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

Contents

This guide is broken into the following sections:

  1. The JSON Approach
  2. An Example Configuration
  3. Configuration Structure
  4. General Configuration Options
  5. Player Specific Configuration Group Options
    1. Hard Coding the Player Dimensions
    2. Setting the Control Bar Operating Rules
    3. Setting the Display Margins
    4. Hiding the Custom Player Logo During Ad Playback
  6. Show Stream Configuration Group Options
    1. General Show Configuration Options
    2. Overlays and Live Streams
  7. Regions Configuration Group Options
    1. General Configuration
    2. Declaring regions
    3. Default region mappings
    4. Configuration options
  8. Ads Configuration Group Options
    1. General ad options
    2. Configuring the Ad Notice
    3. Configuring the Linear Click-Through Notice
    4. Configuring Companions
    5. Configuring the Ad Server(s)
    6. Ad Scheduling Options
    7. Configuring VPAID Ad Support
    8. Configuring RTMP Ads
    9. Excluding Ad Media Files based on Mime Type
    10. Changing the Default Ad Title and Description
  9. Provider Group Configuration Options
  10. Debug Group Configuration Options
    1. Debug Levels
    2. Supported Debuggers
  11. Controls Group Configuration Options
  12. Analytics Configuration Options

Recommended Reading

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


1. The JSON Approach

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 (Javascript Object Notation) form which is fairly easy to read and write.

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.

2. An Example

Embed code:

Resulting player:


3. Configuration Structure

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

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
   },

   "regions": {
       // regions options here
   },

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

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

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

   "controls": {
       // controls specific configuration items go in here
   }

   "analytics": {
       // analytics specific configuration items go in 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.

3.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,
"delayAdRequestUntilPlay": true,
"canFireAPICalls": true,
"canFireEventAPICalls": true,

// The following options are for OVA for JW5 only

"blockUntilOriginalPlaylistLoaded": true,  
"allowPlaylistControl": true, 
"clearPlaylist": true, 
"supportExternalPlaylistLoading": true, 
"autoPlayOnExternalLoad": true

A description of each property follows:

Option Values Default Description
allowPlaylistControl true | false false OVA for JW5 only: Turn on playlist control - enables the next/previous controlbar buttons and load the entire playlist into the player in one go.
assessControlBarState true | false true OVA for JWx only: Specifies whether or not overlays and ad notices are to be repositioned based on whether or not the control bar shows and hides.
autoPlayOnExternalLoad true | false false OVA for JW5 only: If OVA triggers a revised ad schedule based on a trigger from an player.load() external call, "autoPlayOnExternalLoad" determines if OVA should start playback immediately upon loading that newly ad scheduled playlist
autoStart true | false false Trigger the player to automatically start playing the first stream once OVA has completed initialisation
blockUntil
OriginalPlaylistLoaded
true | false false OVA for JWx 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.
canFireEventAPICalls true | false false Specifies if OVA can fire off the Javascript Event Tracking API callbacks as it operates.
clearPlaylist true | false true OVA for JW5 only: Clear the playlist from the player before loading up the ad scheduled playlist.
delayAdRequestUntilPlay true | false false Delay the first ad request until the user presses the "play" button
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
supportExternalPlaylistLoading true | false false OVA for JW5 only: Enable OVA to react to player.load() external API calls

Clearing the Playlist (OVA for JW5 Only)

When OVA for JW5 initialises, the original playlist is cleared from the player. This ensures that the first clip in the list doesn't start playing while a VPAID pre-roll is loaded.

In the case of a playlist that has a VPAID pre-roll, the player playlist will remain empty until the VPAID pre-roll is played. This may have the undesired effect of stopping a splash image from showing in the player when it loads (e.g. 'image=X' flashvar will stop working).

There may be times when it is not desirable to have OVA clear the original playlist.

OVA can be instructed to not clear the playlist on initialisation with the "clearPlaylist" option.

The following code snippet illustrates how to use this option:

{
    "clearPlaylist": false,
    "ads": {
         ....
    }
}

If "delayAdRequestUntilPlay: true" is set and there is a splash image to show, OVA for JW5 will force "clearPlaylist: false" to be set. This ensures that the splash image shows until the user presses play and the ad scheduled playlist is generated and installed.

3.2 Player Specific Configuration Options

The "player" specific config block allows various display related configuration options to be set. These options include hard coding the dimensions of the player, setting the control bar operating rules, declaring whether or not a custom logo should be shown during ad playback (OVA for JW5 only) and specifying the bottom margins to apply to the display when OVA positions visual elements on it.

The following code snippet illustrates how to use this block:

{
    "player": {
        "height": 250,
        "width": 400,
        "modes": {
           "linear": {
              "controls": {
                 "hideLogo": true,
                 "stream": {
                      visible: true,
                      manage: true,
                      enablePlay: true,
                      enablePause: true,
                      enablePlaylist: false,
                      enableTime: false,
                      enableFullscreen: true,
                      enableMute: true,
                      enableVolume: true
                 },
                 "vpaid": {
                      visible: false                   
                 }
              },
              "margins": {
                 "normal": {
                     "withControls": 0,
                     "withoutControls": 0,
                     "withControlsOverride": 0,
                     "withoutControlsOverride": 0
                 },
                 "fullscreen": {
                     "withControls": 0,
                     "withoutControls": 0,
                     "withControlsOverride": 0,
                     "withoutControlsOverride": 0
                 }
              }
           }
        }
    },
    "ads": {
         ....
    }
}

3.2.1 Hard Coding the Player Dimensions

In the case of OVA for JW and OVA for Flowplayer, OVA automatically extracts the width and height dimensions of the player. It is possible however to hard code the player dimensions via the width and height options:

{
    "player": {
        "height": 250,
        "width": 400,
        "modes": {
           "linear": {
               ....
           }
        }
    }
    "ads": {
        ...
    }
}

3.2.2 Setting the Control Bar Operating Rules

During linear ad playback, it is possible to change the way OVA manipulates the control bar. By default, for linear ad streams, the control bar will be disabled. For linear VPAID ads, the control bar will be hidden.

To specify how OVA is to handle the control bar during linear ad playback, use the "player.modes.linear" option as follows:

{
    "player": {
        "modes": {
           "linear": {
               "stream": {
                  "controls": {
                      "visible": true
                  }
               },
               "vpaid": {
                  "controls": {
                      "visible": false
                  }
               }
           }
        }
    }
    "ads": {
        ...
    }
}

Control bar operating rules can be independently specified for linear ad "streams" and linear VPAID ads.

It is possible to specify the control bar rules once for both "streams" and "vpaid" ads as follows:

{
    "player": {
        "modes": {
           "linear": {
               "controls": {
                   "visible": true
               }
           }
        }
    }
    "ads": {
        ...
    }
}

In general, the control bar options can be enabled/disabled with fine grained control using the following options:

  • manage - when set to false, stops OVA manipulating the control bar. True by default
  • enabled - sets all individual control settings to this value (e.g. setting this to false will disable all controls in one go unless individually overridden)
  • enablePlay - the play button - true by default
  • enablePause - the pause button - true by default
  • enableStop - the stop button - true by default
  • enablePlaylist - the playlist buttons - false by default
  • enableTime - the time/scrubber - false by default
  • enableVolume - the volume controls - true by default
  • enableMute - the mute button - true by default
  • enableFullscreen - the fullscreen button - true by default
  • enableLinearSkipAd - the skip ad button - false by default

For a detailed description of these options and in general how to manipulate the control bar with OVA, refer to the Configuring the Control Bar guide.

3.2.3 Setting the Display Margins

Occasionally it is important to declare bottom margins to OVA so that when it is calculating the positions of various visual elements (ad notices, click through notices and regions in general), a bottom margin can be deducted from the player height.

Bottom margin values can be independently specified for linear and non-linear ads as illustrated by the following code snippet:

{
    "player": {
        "modes": {
           "linear": {
               "margins": {
                   "normal": {
                       "withControls": 0,
                       "withoutControls": 0,
                       "withControlsOverride": 0,
                       "withoutControlsOverride": 0
                   },
                   "fullscreen": {
                       "withControls": 0,
                       "withoutControls": 0,
                       "withControlsOverride": 0,
                       "withoutControlsOverride": 0
                   }
               }
           }
           "nonLinear": {
               "margins": {
                   "normal": {
                       "withControls": 0,
                       "withoutControls": 0,
                       "withControlsOverride": 0,
                       "withoutControlsOverride": 0
                   },
                   "fullscreen": {
                       "withControls": 0,
                       "withoutControls": 0,
                       "withControlsOverride": 0,
                       "withoutControlsOverride": 0
                   }
               }
           }
        }
    }
    "ads": {
        ...
    }
}

When specifying bottom margin values, they can be independently specified for "normal" and "fullscreen" modes.

It is also possible to set the margin values once for both "normal" and "fullscreen" modes as follows:

{
    "player": {
        "modes": {
           "linear": {
               "margins": {
                   "withControls": 0,
                   "withoutControls": 0,
                   "withControlsOverride": 0,
                   "withoutControlsOverride": 0
               }
           }
        }
    }
    "ads": {
        ...
    }
}

3.2.4 Hiding the Custom Player Logo During Ad Playback

In the case of OVA for JW5, it is possible to instruct OVA to hide the Custom Player Logo when OVA is used with the Commercial JW player.

The following code snippet illustrates how to do this:

{
    "player": {
        "modes": {
           "linear": {
               "hideLogo": true
           }
        }
    }
    "ads": {
        ...
    }
}

3.3 Show Stream 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.

3.3.1 General Show Configuration Options

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
setDurationFromMetaData true | false false When the option is set to "true", OVA will forcibly set the duration will always be set according to the metadata duration for the stream. The option is "false" by default.
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
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.

3.3.2 Overlays and Live Streams

Support for running overlays with live streams has been added to OVA for Flowplayer and OVA for JW Player 5.

To support overlays on live streams in JW Player 5, a new option "streamTimer" has been introduced to the "shows" config block. This option allows a "timer" to be started when the live stream starts to play. The timer generates time events every 10th of a second (by default) - these timing events are critical for OVA to receive so that it knows when to start playing the overlay. JW Player 5 does not generate these timing events on live streams by default. Flowplayer does - as a result this option is not required for the Flowplayer implementation.

The following code snippet illustrates how to use the "streamTimer" option:

{
    "shows": {
          "streamTimer": { "enabled": true, "tickRate": 100 }
    },
    ....
}

Two parameters are specified with the "streamTimer" option - "enabled" which should be set to true (turn it on) or false (turn it off). "tickRate" is an integer value that dictates how often the timer is fired - in the case above, it is fired every 100 milliseconds (1/10 of a second) which mirrors the standard behaviour of JW Player timer events for non-live streams.

3.4 Region Configuration Options

The "regions" configuration grouping allows multiple rectangular display "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.

The following code snippet illustrates the the "regions" configuration grouping in action.

{
   ...
   "regions": {
       "declarations": [
          // an array of region declarations
       ]
   }
   ...
}

3.4.1 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:

....
    "regions": {
            "declarations": [
                 { 
                     "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": {
        "declarations": [
             {
                 "id": "top-center",
                 "verticalAlign": "top",
                 "horizontalAlign": "center",
                 "backgroundColor": "#000000",
                 "opacity": 0.8,
                 "borderRadius": 15,
                 "padding": "-10 -10 -10 -10",
                 "width": 450,
                 "height": 50
             }
        ]
    }
....

3.4.2 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";
}

3.4.3 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%')

3.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 up to 8 sets of configuration data:

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

3.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": {
    "acceptedLinearAdMimeTypes": [ "video/x-flv", "video/x-mp4"],
    "companions": {
        "restore": false,
        "nativeDisplay": false,
        "millisecondsDelayOnInjection": 100,
        "regions": [
           { "id": "companion-300x250", "width": 300, "height": 250 }
        ],
        "additionalParamsForSWFCompanions": [{ "name": "wmode", value: "transparent" }],
    },
    "enableProxies": true,    
    "enforceLinearAdsOnPlaylistSelection": true,
    "filterOnLinearAdMimeTypes": false,
    "holdingClipUrl": "http://my-domain/my-holding-clip.mp4",    
    "keepOverlayVisibleAfterClick": true,
    "linearScaling": true,
    "parseWrappedAdTags": true,
    "pauseOnClickThrough": true,
    "setDurationFromMetaData": true,
    
    // OVA for JW5 only

    "hideLogoOnLinearPlayback": true,
    "positionMidRollSeekPosition": true
}

The options that can be used include:

Option Values Default Description
acceptedLinearAdMimeTypes Array of Strings null Allows media files to be excluded during OVA search to identify relevant linear streams to playback. Must be specified in the format of an Array of Strings with each string being a valid MIME type - e.g. [ "video/x-flv", "video/x-mp4"]. See the section on "Excluding Mime Types During Linear Playback" in this guide. To turn this option on, acceptedLinearAdMimeTypes must be used in conjunction with the filterOnLinearAdMimeTypes option (see below).
companions Object null Declaration of the companion display attributes (see the section below on how to enable companions)
enableProxies true | false false OVA for Flowplayer only: Support had been added into OVA for Flowplayer to enable URL resolvers/proxies such as the Akamai plugin to be used with RTMP based ad stream URLs. Setting "enableProxies:true" in the OVA config allows the final ad stream URLs (e.g. the netConnectionURL etc) to be derived at runtime by supporting plugins such as the Akamai plugin.
enforceLinearAdsOnPlaylistSelection true | false false OVA for JW5 only: When used on conjuction with "allowPlaylistControl:true", "enforceLinearAdsOnPlaylistSelection" ensures that user driven playlist changes assess whether or not there are pre-rolls to be played before the newly selected item is played by the player.
filterOnLinearAdMimeTypes true | false false Turns on custom filtering of Linear ad playback types based on the mime types specified with the acceptedLinearAdMimeTypes option.
hideLogoOnLinearPlayback true | false false OVA for JW5 only - when "true" ensures that the custom logo configured on the player is hidden when linear ads are played
holdingClipUrl String Longtail CDN When linear ad clips are loaded "onDemand", they need to have a spare "holding clip" specified to allow the playlist structure to be created initially by OVA - as ad calls are successfully completed, the holding clips are replaced with actual clips. A holding clip should be a very short, blank (black) MP4. It must always be hosted on your servers to ensure that it is always available as OVA operates. An unavailable holding clip will cause OVA to incorrectly operate. You can download the sample holding clip that we use in the demos from here: http://static.openvideoads.org/ads/blank/blank.mp4
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.
linearScaling String null This option has been added to allow the "linear scaling" attributes of ad streams to be forcibly set. "linearScaling" takes a string value. The value is dependant upon the player implementation. For Flowplayer, the value can be either - "orig", "fit" or "scale". For JW Player, the value can be either - "uniform", "fill", "exactfit", "none"
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
parseWrappedAdTags true | false false allows OVA variables such as "site-url", "random-number" etc. housed in Wrapper URLs to be dynamically replaced when the ad tag is called. Turned off by default.
positionMidRollSeekPosition Integer -1 OVA for JW5 Only: Used in conjuction with live streams (and "positionMidRollSeekPosition:0") to ensure that the live stream is resumed appropriately upon the completion of a mid-roll. Turned off by default.
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.

 

3.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.

3.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": "<p class="smalltext" align="right">
                   My New Ad Notice - _seconds_ seconds</p>"
   }
   ...
} 

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

3.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.

3.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.

3.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.

3.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

For a detailed account of how to configure the Ad Notice, please refer to the Customising the Ad Notice guide.

3.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.

3.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": "<p class="smalltext" align="center">
                CLICK ME!</p>",
       "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": "<p class="smalltext" align="center">
                MY NEW CLICK-THROUGH TEXT</p>"
   }
   ...
}

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. 

So

<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.

For a detailed account of how to customise the Click-Through Message, please consult the Customising Click-Throughs guide.

3.5.3.2 Turning off the Click-Through Notice

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

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

3.5.3.3 Modifying the target window for click-through URLs

A "target" option has been added to the "clickSign" config element to allow a target browser window to be specified for a click-through action. The valid options are "_self", "_blank", "_parent" and "_top". The default setting is "_blank".

The option can be used as follows:

{
    "ads": {
          "clickSign": {
                 "target": "_self"
                 ...
          },
          ...
    }
}

3.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": { "regions": [ { companion-descriptor-1 }, { companion-descriptor-2 } ... { companion-descriptor-N } ] }

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

...
  "ads": {
     "companions": {
        "restore": false,
        "regions": [
           { 
               "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.

"restore" 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.

"millisecondsDelayOnInjection" 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.

For a more detailed account of how to configure Companions, please consult the Delivering Companions guide.

3.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"
          }
      ]
  }
...

3.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. 

3.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 optionally 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": { 
                  "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 Using Static Ad Tags 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"
               }
           }
       ]
   }
...

3.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.

3.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

3.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.

3.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.

3.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"
          }
      ],
      "companions": 
          "regions": [
              { "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

3.5.7 Enabling the "Skip Ad" Button

A "skip" button can be enabled as follows:

{
     "ads": {
          "controls": {
               "skipAd": {
                   "enabled": true
               }
          },
          ....
     }
}

3.5.7.1 The Standard Skip Ad Button

By default a button with a pre-defined image is used.

To see the standard "skip ad" button in action, click here.

That image can be overridden.

Using a Custom Image for the Skip Ad Button

To override the standard skip ad button image, use the "image" property and specify the new image "width" and "height":

{
    "ads": {
         "controls": {
                "skipAd": {
                     "enabled": true,
                     "image": "../../images/my-new-skip-button.jpg",
                     "width": 65,
                     "height": 15
                }
        },
        ....
    }
}

3.5.7.2 Using Region Attributes with the Skip Ad Button

It is also possible to use the region attributions to declare a skip button - background color, margins, borders and html content can be specified to construct the look of the button.

{
     "ads": {
           "controls": {
                "skipAd": {
                     "enabled": true,
                     "html": "<p>SKIP!</p>",
                     "region": {
                            "id": "my-new-skip-ad-button",
                            "verticalAlign": 3,
                            "horizontalAlign": 3,
                            "backgroundColor": "#FF3300",
                            "opacity": 0.8,
                            "borderRadius": 15,
                            "padding": "0 1 1 13",
                            "width": 60,
                            "height": 20
                     }
                }
           },
           ....
      }
}

An example of an overridden button image can be found here.

3.5.7.3 Showing the Skip Button on Ads with a minimim duration

It is possible to configure the "skip ad" button so that it only shows on ads that are longer than a specific duration.

For example, the following configuration configures the "skip ad" button to show only on ads that are 10 seconds or longer in duration.

{
     "ads": {
          "controls": {
               "skipAd": {
                   "enabled": true,
                   "minimumAdDuration": 10
               }
          },
          ....
     }
}

3.5.8 Configuring VPAID Specific Options

Support has been added for VPAID 1.1 linear ads.

For a detailed account of the VPAID API as defined by the IAB, please refer to the VPAID specification.

3.5.8.1 Enabling VPAID for OVA for Flowplayer

VPAID ads will be played by default with OVA for Flowplayer. No specific configuration is required.

To see an example VPAID linear ad in action with Flowplayer, click here.

VPAID Ads and "always" autoHide control bars

By default, VPAID ads will cover "always" autoHide configured control bars.

For some reason however, the control bar may occasionally appear over the VPAID ad when the mouse is moved over the control bar area. This is not a consistent bug and seems to happen randomly.

If you notice this behaviour and wish to size the VPAID ad so that it is not appearing over the control bar area, use the following option in conjunction with the "autoHide": "always" Flowplayer player configuration:

    "ads": {
          "vpaid": {
                "controls": { "hideOnLinearPlayback": "false" }
          }
    }

3.5.8.2 Enabling VPAID for OVA for JW Player 5

For VPAID Linear Ads to work with OVA for JW Player 5, a "holding" clip must be placed in the position of the linear ad within the playlist. A holding clip is a "minimal" clip - for example, a one second black FLV or MP4 stream.

OVA automatically places this "holding" clip into the player when it schedules a VPAID ad to play. By default this holding clip is loaded from the Longtail CDN.

We have provided a default (1 second black MP4) clip that you can download and use http://lp.longtailvideo.com/5/ova/blank.mp4 and optionally host on your servers. This may help improve the performance of OVA running on your site.

Never reference the holding clip from the OVA QA server ("static.openvideoads.org") as the file cannot be guaranteed to always be available.

The following configuration structure is used to instruct OVA for JW4 as to the location of the holding clip:

{
    "ads": {
        "vpaid": {
             "holdingClipUrl": "http://xxx.longtailvideo.com/5/xxx/blank.mp4",
        },
        "schedule": [
               .....
        ]
    }
}

It is also possible to declare the holding clip as follows - if you are deploying "on demand loading", the same holding clip can be used for "on demand" ad slots as well as VPAID ads:

{
    "ads": {
        "holdingClipUrl": "http://xxx.longtailvideo.com/5/xxx/blank.mp4",
        "schedule": [
               .....
        ]
    }
}

To see an example JW5 VPAID linear ad in action, click here.

3.5.8.3 Instructing OVA to pass a Referrer URL to the VPAID Ads

Sometimes VPAID ads require a "referrer" URL to be passed to them.

To enable this information to be passed, configure OVA as follows:

      ...
          "ads": {
             "vpaid": {
                 "supplyReferrer": true
             },
     ....

It is also possible to manually specify the value of the "referrer" string that is passed into a VPAID ad. The following config snippet illustrates how to achieve this:

      ...
          "ads": {
             "vpaid": {
                 "supplyReferrer": true,
                 "referrer": "www.my-domain.com"
             },
     ....

3.5.8.5 Setting the Maximum Timeout Option

If a VPAID ad has an internal exception that cannot be caught by OVA, a default timer can be set to ensure that OVA will eventually close down the VPAID ad and continue on to the next clip.

The following configuration sets the default timer to 30 seconds. The timer is disabled by default.

   ...
       "ads": {
            "vpaid": {
                  "enableMaxDurationTimeout": true,
                  "maxDurationTimeout": 30
            },
   ...

3.5.9 Supporting RTMP Streaming Ads

RTMP ads are more difficult to deliver than HTTP because three critical pieces of information are required to configure an RTMP clip:

  • The Net Connection Address of the RTMP server
  • The Filename of the stream
  • Any adornments that are to accompany the filename as required by the RTMP server (e.g. "MP4:")

VAST responses typically deliver RTMP based Media File URLs in either of the following formats:

rtmp://ne7c0nwbit.rtmphost.com/videoplayer/mp4:ads/30secs/country_life_butter.mp4
rtmp://ne7c0nwbit.rtmphost.com/videoplayer/ads/30secs/country_life_butter.mp4

The key difference between both of these RTMP URLs is that the first includes a specific "file marker" that allows OVA to easily determine the "netConnectionAddress" of the RTMP server as well as the filename for the RTMP ad stream. Often in the case of MP4 streams, the "file marker" doubles as an important prefix that the RTMP server expects on the filename address.

The second URL doesn't include any of these distinguishing characteristics.

So the challenge for OVA is to work out how to extract both the Net Connection Address, Filename and File Adornments from a simple URL.

RC4 implements two mechanisms to improve OVA's ability to play RTMP ad streams:

  • A new ad "streamers" configuration block
  • A default set of rules that govern the splicing of a standard URL into it's Net Connection Address and Filename components

The Ad "streamers" configuration block

To help OVA identify the Net Connection Address and Filename components of an RTMP URL, a set of "ad streamers" may now be declared.

Each ad streamer declaration has the following elements:

  • A "netConnectionAddress" pattern
  • A definition of which types of files to explicitly remove the file extension if one is provided
  • A definition of which types of files to add a prefix

The following config snippet illustrates how to declare a set of "ad streamers" for RTMP ads:

{
    ...
          "ads": {
              "streamers": [
                  {
                      "netConnectionAddress": "rtmp://ne7c0nwbit.rtmphost.com/videoplayer",
                      "removeFilenameExtensions": [ "flv" ],
                      "addFilenamePrefixes": [ "mp4" ]
                  },
                  {
                      "netConnectionURL": "rtmp://another-ad-streamer.com/ads"
                  }
              ],
              "schedule": [
                  {
                      "position": "pre-roll",
                      "tag": "../../../dist/templates/rtmp-ads/vast1-mp4-no-markers.xml"
                  }
              ]
         }
   ...
}

In this configuration block two ad streamers are declared. The first states:

That RTMP ads will be streamed from "rtmp://ne7c0nwbit.rtmphost.com/videoplayer"

  • If the RTMP ad is an "flv" ad, remove the file extension when configuring
  • If the RTMP ad is an "mp4" ad, add a prefix ("mp4:") to the filename when configuring it

The first ad streamer configuration will match on an RTMP URL such as:

rtmp://ne7c0nwbit.rtmphost.com/videoplayer/ads/30secs/country_life_butter.mp4

and produce the following components:

  • netConnectionAddress: rtmp://ne7c0nwbit.rtmphost.com/videoplayer
  • filename: mp4:ads/30secs/country_life_butter.mp4

The Default RTMP URL Splicing Rules

In the absence of a set of "ad streamers" being declared, OVA will implement a default set of "splicing" rules when configuring RTMP ad streams from URLs that do not have any relevant "file markers".

Consider the following URL:

rtmp://ne7c0nwbit.rtmphost.com/videoplayer/ads/30secs/country_life_butter.mp4

The following rules will be applied:

  • The netConnectionAddress will be determined as the domain name part of the URL followed by the first directory name in the URL string
  • The filename will be determined by removing the part derived as the netConnectionAddress
  • If the URL has either an ".mp4" file extension or an MP4 mime type set on the VAST Media File tag set, "mp4:" will be prefixed to the filename
  • If the URL has a ".flv" file extension it will be removed

As a result, the following components will be derived:

  • netConnectionAddress: rtmp://ne7c0nwbit.rtmphost.com/videoplayer
  • filename: mp4:ads/30secs/country_life_butter.mp4

Enabling/Disabling "rtmp.subscribe" (OVA for JW5 only)

When "rtmp.subscribe" is set for show clips in JW5, any RTMP ad clips *may* need to have the "rtmp.subscribe" value forcibly set to false.

To support this, the following configuration options have been implemented:

{
   ...
   "ads": {
        "providers": { 
             "enforceSettingSubscribeRTMP":true, 
             "subscribeRTMP": false 
        },
        "schedule": [
            ....

"enforceSettingSubscribeRTMP" forces OVA for JW5 to set a "rtmp.subscribe" value on the ad clip if it is an RTMP stream.

"subscribeRTMP" is the value that gets set as "rtmp.subscribe" on the ad clip if it is an RTMP ad stream and "enforceSettingSubscribeRTMP" is set to true.

3.5.10 Excluding Ad Media Files based on Mime Type

Two configuration options have been added to the "ads" configuration block to allow media files to be excluded during OVA search to identify relevant linear streams to playback.

The two options are illustrated below.

"ads": {
      "acceptedLinearAdMimeTypes": [ "video/x-flv" ],
      "filterOnLinearAdMimeTypes": true,
      ...
}

In this example, only FLV based ad streams will be selected.

"acceptedLinearAdMimeTypes" is an Array based configuration property. A set of mime types can be configured as per a normal Array based definition. For instance, to limit the filtering to FLV and MP4, the following declaration should be made:

"acceptedLinearAdMimeTypes": [ "video/x-flv", "video/x-mp4"]

By default:

  • In the AS3 framework "filterOnLinearAdMimeTypes" is false
  • In the OVA JW4, JW5 and Flowplayer plugins, "filterOnLinearAdMimeTypes" is true and "acceptedLinearAdMimeTypes" is set to ["video/x-flv","video/x-mp4","application/x-shockwave-flash"]

To turn off the default filtering in the OVA plugins just set "filterOnLinearAdMimeTypes" to false - all "media files" elements of the VAST response will then be searched for a match to playback.

3.5.10 Changing the Default Ad Title and Description (OVA for Flowplayer only)

The "metaData" config group can be used to modify the default title and description for ads to be changed when shown in playlist selection controls.

By default, OVA sets the clip title and description fields to the following values:

  • Default Title: "Advertisement"
  • Default Description: The value in the title field of the VAST response for the ad

In all cases, the title and description are set on the clip objects as:

  • title
  • description

To modify the default values that OVA inserts for the title and description, use the "metaData" config option within the "ads" config group as follows:

{
    ...
    "ads": {
        "metaData": {
             "linear": {
                  "title": "my new title goes here",
                  "description": "my description goes here"
             }
        }
        .....
    }
}

Two variables are available to use in the title and description text:

  • __duration__ - insert this variable if you want to add the duration to the text
  • __index__ - insert this variable if you want to insert the sequence number of the ad

For example, if you specify a line of text such as:

"My ad is __duration__ seconds and is ad number __index__"

You will end up with a line like:

"My ad is 30 seconds and is ad number 1"

3.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.

3.7 Debug Configuration Options

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

"debug": {
      "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.

3.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

3.7.2 Supported Debuggers

OVA uses "console.log()" to output the debug data. Any browser that supports a Javascript console should be capable of displaying the debug lines generated by OVA.

Further information is available within the "Debugging OVA" guide.

3.8 Analytics Configuration Options

The "analytics" configuration block enables various tracking systems to be turned on to support reporting of OVA impression and tracking events.

The first analytics system integrated with OVA is Google Analytics.

Today the "analytics" mechanism can only be used to support impression reporting. Over time support for additional analytics systems and metric points will be added.

3.8.1 Enabling Custom Tracking

To configure a custom account ID, use the following configuration approach:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                        "enable": true,
                        "accountId": "UA-10158120-1",
   	        	"impressions": {
                              "linear": "put-your-custom-url-here",
                              "nonLinear": "put-your-custom-url-here",
                              "companion": "put-your-custom-url-here"
                        }
	         }
          }
     },
     "ads": {
           ....
     }
}

The code snippet presented above turns on impression tracking to the GA account "UA-10158120-1". For further information on the Google Analytics tracking options available, please consult to the OVA and Google Analytics guide.

Still don't have the new JW Player? Get It Here