wiki:OvaReleaseNote-0.5.0-RC5

Version 39 (modified by paul, 3 years ago) (diff)

--

What's New? (Release Candidate 5)

The following versions have been issued as "release candidates".

  • OVA for AS3 v0.6.0 RC5
  • OVA for JW Player 4 v0.5.0 RC5
  • OVA for JW Player 5 v0.5.0 RC5
  • OVA for Flowplayer v0.6.0 RC5

The following API changes have occurred in this release:

  • Javascript API calls into the OVA SWF are now prefaced with "ova" - see section 17 for details. If you are using the OVA Javascript plugin, the API names remain unchanged
  • The javascript callback events - onVASTLoadSuccess(), onVASTLoadFailure(), onVASTLoadTimeout() have been renamed to onTemplateLoadSuccess(), onTemplateLoadFailure(), onTemplateLoadTimeout()
  • onTemplateLoadDeferred() has been added as part of the support for "on demand" loading of ad slots
  • VASTController. preprocessImpressionsToForceFire() has been renamed to VASTController.processImpressionFiringForEmptyAdSlots()
  • Removed Javascript callbacks onRegionClicked() and onRegionCloseClicked() - replaced with onNonLinearAdClicked(ad) and onNonLinearAdCloseClicked(ad)

The following functional changes are in this release:

  • VAST 2 wrapper support
  • VPAID 1.1 Linear Ad support
  • An ability to configure a "Skip Ad" button
  • Dramatically simplified configuration for pre-roll only setups
  • Support for the specification of 'fail-over' ad servers
  • The OVA for AS3 SWC has been renamed to 'ova-as3-<version>.swc'
  • Deferred loading of ads via the 'delayAdRequestUntilPlay' option
  • A "cache-buster" parameter is can be added to the end of wrapped VAST ad requests (config driven)
  • Finer grain control when disabling the control bar during linear ad playback
  • Support added for a range of new ad tag variables - e.g. "page-url" etc.
  • Several ad server examples added:
    • AdForm - VAST 2 Linear
    • Lightningcast - VAST 1 Linear
    • Adap.tv - VAST 2 Linear
    • Spotxchange - VAST 2 Linear
    • Smartclip - VAST 1 Linear and VAST 2 VPAID Linear
    • Telemetry - VAST 1 and 2 VPAID Linear
    • TidalTV - VAST 2 VPAID Linear
    • Liverail VPAID Linear
    • Eyewonder VPAID Linear
    • Mov.ad VPAID Linear
    • Adotube VAST2 Linear/Non-Linear and VPAID Linear/Non-Linear
    • OpenX V3 (Hosted) - See section 21
  • Show clips can now have the duration forcibly set via a shows "setDurationFromMetaData" config option
  • Completely rewritten logic for setting the show stream based on the meta data - fixes pseudo-streaming control bar issues
  • Media files can be excluded from a VAST response based on mime type
  • Ticket 226 - Critical Timestamp.secondsToTimestamp() fix - was producing invalid timestamp for times greater than 60 mins
  • Support for new Media, Player width/height and AS version based dynamic ad tag variables
  • Added onLinearAdSkipped() Javascript callback method - this is triggered when the user skips an ad via the skip ad button
  • Resolved a parsing issue with international characters in ad notice definitions by replacing the JSwoof JSON parser used in OVA for JW Player 4 & 5 with the standard Adobe parser
  • Ensured that a "allowScriptAccess" param tag is used when a companion SWF is inserted into a page
  • Added support for custom impression tracking using Google Analytics tracking (and standard OVA impression tracking which is enabled by default but can be turned off)
  • A new set of Javascript callback events supported with VPAID Ads
  • Added support for the direct injection of a VAST Response into OVA via the "ova.vast" flashvar or the "inject" ad server type
  • Added a new configuration option "tagParams" to allow custom parameters to be added to an ad tag at runtime
  • OVA for Flowplayer is now compatible with the Flowplayer BWCheck plugin
  • Cleaned up and extended the Javascript callback API methods - ad object now passed back and some method names changed
  • Added support for Companion <AdParameters> to be passed in to SWF companions
  • Added "linearScaling" config option to allow scaling parameters on linear ad streams to be forcibly set (JW5 and Flowplayer only)
  • Improved support for RTMP ads - auto-detection of netConnectionAddress (where feasible) and new support for custom "streamer" definitions
  • Confirmed OVA for Flowplayer works with Clustering plugin
  • "allowPlaylistControl" option re-introduced for OVA for JW 4/5 to allow the full playlist to be maintained in the player once OVA has finished scheduling the ads
  • "enforceLinearAdsOnPlaylistSelection" option introduced for OVA for JW5 to allow playlist selections to check if pre-rolls should first be played
  • Implemented overlay ad support on live streams - OVA for JW5 and OVA for Flowplayer only
  • Added a config option to allow the control bar height to be specified
  • Made sure "blockUntilOriginalPlaylistLoaded" actually works with OVA for JW5
  • Now clear the JW5 playlist on OVA initialisation unless "clearPlaylist" is set to "false" (OVA for JW5 only)
  • OVA for Flowplayer tested against Flowplayer 3.2.6
  • Corrected the sizing of the Click Through region on linear ads so that it excludes the control bar in fullscreen mode (OVA for JW5 only)
  • Support added into OVA for Flowplayer for URL resolvers/proxies to be used on RTMP ad stream URLs (e.g. Akamai etc.)
  • SWF Companions now have the click tag passed as the following flashvar variables - "clicktag, clickTag, clickTAG"
  • A configuration option has been added to allow a timeout value to be set on ad calls - this stops ad servers blocking the player if they don't return a value and hold the call open
  • Fixed an issue that stopped "keepOverlayVisibleAfterClick" working with custom regions
  • Modified the click through open URL logic to ensure that IE browsers use the ExternalInterface("window.open") rather than the AS3 navigateToURL() method - this fixes an issue where IE popup blockers blocked click throughs if "wmode" was set to opaque
  • Added a "target" option to the "clickSign" notice element to allow a "target" window to be specified for a click through ("_self", "_blank", "_top", "_parent") - default is "_blank"
  • Added support for hard coding the player dimensions in the OVA configuration (JW5 only)
  • A config option has been added to allow the default title and description for ads to be changed when shown in playlist selection controls
  • Added support for a splash image to be set (via the "image=X" flashvar) on a playlist that only contains a linear ad (OVA for JW5 only)
  • (OVA for JW 5 only) - upgraded support for JW 5.6 that allows nested JSON configuration (which means the configuration of OVA for JW 5 is now equivalent to OVA for Flowplayer when using the JW Javascript Embedder approach)
  • (OVA for Flowplayer only) - added an example to illustrate how to use OVA with Flowplayer Secure Streaming
  • Added Ads config group setting 'additionalParamsForSWFCompanions' to allow additional parameters to be added to the companion SWF object/embed tags as the code is inserted into the page
  • Added support for RTMP subscribe to be forcibly set to true or false on ad clips (OVA for JW5 only)
  • An "on-demand" model has been implemented to ensure that ad requests are only made when required (via the "loadOnDemand" option)
  • A "refreshOnReplay" option has been provided to ensure that the ad slot is refreshed each time it is played (only available when paired with the "loadOnDemand" option)
  • Added support for ad scheduling javascript callbacks
  • Added a VASTController.unload() call to allow any open URLLoaders and SWFs to be forcibly closed by the parent SWF
  • Support has been added for OVA to reschedule against new playlists/clips loaded into JW Player via the Javascript API jwplayer("container").load() - that allows HTML playlists to be supported
  • Added option "resetTrackingOnReplay" to turn off VAST tracking on ad replays
  • Added a "positionMidRollSeekPosition" config option for mid-roll support on live streams (OVA for JW5 ONLY)
  • Added support for automatically spacing the start time of repeated ad slots via an "interval" config option

IMPORTANT NOTE: OVA for JW 4/5 in RC4 uses a different JSON parser (the default Adobe parser is now used). This parser requires strict compliance to the JSON definition rules - additional commas etc. in an OVA JSON configuration will result in the JSON parser throwing an exception. For this reason, when upgrading to the latest OVA for JW Player plugin, please check your configuration for JSON compliance. If your setup does not work with the new release of OVA it is likely to be due to the fact that your OVA configuration was slightly non-compliant. It is worth nothing that many of the previous OVA examples had extra commas etc. specified in the OVA configuration blocks breaking those examples when run against the latest OVA release.

For example, the following configuration will throw a JSON exception now (notice the extraneous comma after the second ad slot definition):

     ...
     "ads": {
          "schedule": [
                {
                },
                {
                },
          ]
     }

The exception will appear in the OVA debug output as follows:

14:02:12 GMT+0000 Debuggable: OVA Configuration parsing exception - Unexpected ]

1. Download the Release Candidates

You can grab the latest development builds from  here.

2. RC5 Examples

You can find the full set of RC5 examples here:

3. VAST2 wrapper support

Support has been added for the VAST 2 wrapper. For more information on the format of VAST 2 wrappers, refer to the  IAB site.

For an example of the VAST 2 wrapper in action, click  here.

Automatic support for a cache-buster parameter being added to the wrapped ad tag has been provided via the "addCacheBuster" config variable. Set this config option to true to turn on the cache buster parameter.

...
      "server": {
              "type": "direct",
              "addCacheBuster": true,
              "tag": "your-ad-tag-goes-here"
      }
...

4. VPAID support

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.

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

4.1.1 VPAID and Flowplayer 3.2.6 Control Bars

The standard Flowplayer 3.2.6 Control Bars currently have a small issue that may cause problems with the sizing of VPAID linear ads.

Flowplayer 3.2.6 when used with flowplayer-controls.3.2.4 or flowplayer-controls.3.2.5 will report the height of the controls as 0.

OVA uses the sizing information for the control bars when configuring VPAID ads. Incorrect sizing information will result in the VPAID ad not displaying correctly around the control bar area.

To force the sizing of the control bar to be correctly recognised by OVA, a control bar "height" option has been introduced.

Use this option as follows:

   "ads": {
        "controls": {
             "height": 30
        }
   }

This option can be found in action  here.

4.1.2 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" }
          }
    }

This option can be found in action  here.

4.2 Enabling VPAID for OVA for JW Player 4 & 5

For VPAID Linear Ads to work with OVA for JW Player 4 & 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 1 second black FLV or MP4 stream.

OVA automatically places this "holding" clip into the player when it schedules a VPAID ad to play.

We have provided a default (1 second black FLV) clip that you can download and use  here ( http://static.openvideoads.org/ads/blank/blank.mp4)

The holding clip must be hosted on a server of your choice. Never reference the holding clip from the OVA servers 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://content.bitsontherun.com/videos/CWV6XUu0-8ULb9uN9.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://content.bitsontherun.com/videos/CWV6XUu0-8ULb9uN9.mp4",
        "schedule": [
               .....
        ]
    }
}

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

4.3 Showing the Control Bar during VPAID Linear Playback

OVA for JW Player 4/5 hides the control bar by default during VPAID Linear Ad playback.

OVA can be instructed to show the control bar during playback via the following configuration:

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

An example can be found  here.

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

An example can be found  here.

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

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

An example can be found  here.

4.6 Integrating VPAID Into your Custom Player via OVA for AS3

The code shown in this section has been taken from the OVA for JW Player 5 implementation. Please use that implementation as a reference implementation when integrating the OVA VPAID functionality into your custom player.

4.6.1 How OVA Treats VPAID Ads

VPAID ads are delivered to OVA via a VAST response.

A linear VPAID ad is identified within a VAST response via the "apiFramework" attribute on the <MediaFile> tag. For instance:

<MediaFile delivery="progressive" width="300" height="250" type="application/x-shockwave-flash" apiFramework="VPAID">
   <![CDATA[http://chibis.adotube.com/vast/UA.swf?mode=vpaid&adLinear=true&omlSource=http%3A%2F%2F
      www.adotube.com%2Fphp%2Fservices%2Fplayer%2FOMLService.php%3Favpid%3D2ChPxDe%26platform_
      version%3Das3%26vast_cache_get%3D7-cff0cc9320fa4510824a6b7ee3543ab0%26integration%3Dlongtail
      &publisher=__domain__&title=ova test&tags=ova&description=video description&videoURL=]]>
</MediaFile> 

Non-linear VPAID ads are identified within the VAST response via the "apiFramework" attribute on the <NonLinear> tag. For instance:

<NonLinear width="300" height="250" apiFramework="VPAID" > 
   <StaticResource creativeType="application/x-shockwave-flash"> 
       <![CDATA[http://chibis.adotube.com/vast/UA.swf?mode=vpaid&omlSource=http%3A%2F%2F
       www.adotube.com%2Fphp%2Fservices%2Fplayer%2FOMLService.php%3Favpid%3DOBpMj3k%26
       platform_version%3Das3%26vast_cache_get%3D7-54aac9181937ecb5d8ce2ae3c1cd0053&
       publisher=www.longtailvideo.com&title=The Black Hole&tags=ova,test&description=ova test stream&videoURL=]]> 
   </StaticResource> 
</NonLinear> 

OVA expects to play back a VPAID ad via an overlay on the player rather than through the more standard clip playback mechanisms of the player.

As such, VPAID ads need to be treated differently during playback to the standard linear ad clips.

In principal, OVA does all the work to playback a VPAID ad. The custom player just has to recognise when an ad to be played is a VPAID ad and trigger the OVA VPAID playback functionality accordingly.

4.6.2 The Three Steps to Integration

To implement OVA VPAID functionality within your player, three steps should be taken:

  1. Register the VPAID event handlers
  2. Implement the VPAID event handlers
  3. Implement the clip control logic to ensure that if the active ad to play is a VPAID ad, play it using the OVA "playVPAID" method rather than loading it as a clip into the player

4.6.3 The VPAID Events

Two sets of VPAID events are provided by OVA - those generated by linear VPAID ads, and those generated by non-linear VPAID ads.

The linear VPAID events are as follows:

VPAIDAdDisplayEvent.LINEAR_START - generated when a VPAID ad starts
VPAIDAdDisplayEvent.LINEAR_COMPLETE - generated when a VPAID ad completes
VPAIDAdDisplayEvent.LINEAR_ERROR - generated when a VPAID ad generates an error event
VPAIDAdDisplayEvent.LINEAR_LINEAR_CHANGE - generated when the VPAID ad changes into and out of a "linear" state
VPAIDAdDisplayEvent.LINEAR_EXPANDED_CHANGE - generated when the VPAID ad is minimised/maximised
VPAIDAdDisplayEvent.LINEAR_TIME_CHANGE - generated by the VPAID ad to indicate that the remaining time left has changed

The non-linear VPAID events are as follows:

VPAIDAdDisplayEvent.NON_LINEAR_START - generated when a VPAID ad starts
VPAIDAdDisplayEvent.NON_LINEAR_COMPLETE - generated when a VPAID ad completes
VPAIDAdDisplayEvent.NON_LINEAR_ERROR - generated when a VPAID ad generates an error event
VPAIDAdDisplayEvent.NON_LINEAR_LINEAR_CHANGE  - generated when the VPAID ad changes into and out of a "linear" state
VPAIDAdDisplayEvent.NON_LINEAR_EXPANDED_CHANGE - generated when the VPAID ad is minimised/maximised
VPAIDAdDisplayEvent.NON_LINEAR_TIME_CHANGE - generated by the VPAID ad to indicate that the remaining time left has changed

Typically a full set of event handlers implemented for the type of VPAID ads (linear, non-linear) that you are delivering.

4.6.4 Implementing The VPAID Event Handlers

A VPAID Event handler is declared using the "addEventListener" VASTController method. The following code snippet illustrates how to declare event listeners for the full set of linear VPAID events:

_vastController.addEventListener(VPAIDAdDisplayEvent.LINEAR_START, onVPAIDLinearAdStart); 
_vastController.addEventListener(VPAIDAdDisplayEvent.LINEAR_COMPLETE, onVPAIDLinearAdComplete); 
_vastController.addEventListener(VPAIDAdDisplayEvent.LINEAR_ERROR, onVPAIDLinearAdError); 
_vastController.addEventListener(VPAIDAdDisplayEvent.LINEAR_LINEAR_CHANGE, onVPAIDLinearAdLinearChange); 
_vastController.addEventListener(VPAIDAdDisplayEvent.LINEAR_EXPANDED_CHANGE, onVPAIDLinearAdExpandedChange); 
_vastController.addEventListener(VPAIDAdDisplayEvent.LINEAR_TIME_CHANGE, onVPAIDLinearAdTimeChange); 

The following code snippet illustrates a typical implementation of an event handler for the VPAID start event:

protected function onVPAIDLinearAdStart(event:VPAIDAdDisplayEvent):void {
   doLog("PLUGIN NOTIFICATION: VPAID Linear Ad started", Debuggable.DEBUG_VPAID);
   if(_vastController.hideControlbarDuringVPAIDLinearPlayback()) {
      hideControlBar();
   }
   else disableControlBar();
}

Typically the custom player event handler for a VPAID start or complete event manipulates the control bar in some form.

In the code above, the VPAID start ad event handler checks to see if the OVA configuration specifies that the Control Bar should be hidden or just disabled during VPAID ad playback.

If the OVA configuration is as follows:

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

vastController.hideControlbarDurationVPAIDLinearPlayback() will return false. The default value is true which means that by default, OVA expects the controlbar to be hidden during playback.

VPAID event handlers receive a VPAIDAdDisplayEvent. Sometimes that event has "data" in it.

  • The VPAIDAdDisplayEvent passed to VPAID Error handlers will contain an error message that can be accessed via "event.data.message"
  • The VPAIDAdDisplayEvent passed to VPAID Linear change handlers will contain a boolean data value. If event.data == true, the VPAID ad is playing a Linear stream. If false, the stream has completed.
  • The VPAIDAdDIsplayEvent passed to VPAID Expanded change handlers will contain a boolean data value. If event.data == true, the VPAID ad is in an expanded state. If false, it is minimised.
  • The VPAIDAdDisplayEvent passed to VPAID Time Change handlers will contain an int that represents the time remaining in the playback of the VPAID ad. Note, this "remaining time" notification mechanism does not seem to be reliably implemented across ad providers so it should not be relied upon.

4.6.5 Triggering the Playback of a VPAID Ad

OVA AdSlots now have an "isInteractive()" method. This method can be used to query the AdSlot type. If AdSlot.isInteractive() == true, the AdSlot is a VPAID linear or non-linear ad.

To trigger a VPAID ad to play, the AdSlot containing the VPAID ad should be passed into the VASTController.playVPAID method. For example, the following code results in the playback of a VPAID ad in the first ad slot (typically a pre-roll ad slot):

var preRollAdSlot:AdSlot = _vastController.adSchedule.getSlot(0);
if(preRollAdSlot.isInteractive()) {
   _vastController.playVPAID(preRollAdSlot);
}

When the VASTController is instructed to play a VPAID ad, it:

  • Triggers the load of the VPAID swf into an overlay via the OVA VPAIDWrapper class
  • Once the VPAID SWF resource has been loaded, the OVAWrapper undertakes the VPAID handshake and initialisation process
  • If this is successfully completed, the VPAID ad is started and a VPAIDAdDisplayEvent.LINEAR_START (or NON_LINEAR_START) event will be fired
  • As the VPAID ad plays back, the appropriate events are fired when the ad is minimised, closed, maximised, starts linear playback, generates errors
  • On completion of the VPAID ad, the OVA VASTController takes care of cleaning up the VPAID ad resources and hiding the overlay used to display the VPAID ad

4.6.6 Getting hold of the active VPAID ad and then manipulate it

The following code snippet illustrates how to get hold of the active VPAID ad and change the volume on it:

if(_vastController != null) {
    if(_vastController.isVPAIDAdPlaying()) {
        var vpaidAd:org.openvideoads.vpaid.IVPAID = _vastController.getActiveVPAIDAd();
        if(vpaidAd != null) {
            vpaidAd.adVolume = my_new_player_volume;
        }
    }
    else ; // it's a linear ad stream
}

4.7 Known Limitations

  • An exception in the VPAID ad that does not throw an Error event will hang the player (unless timeout is defined)
  • OVA for JW4 does not fully support configuration of VPAID ad without a stream also being played (play button does not show unless file= defined) - recommend upgrade to OVA for JW5
  • OVA for JW4 does not support "autostart=true" on VPAID pre-rolls - recommend upgrade to OVA for JW5
  • Updates to the timeline on the control bar are not triggered by VPAID ads

5. Configuring the Skip Ad Button

The ability to "skip" on a linear ad has been added along with a set of examples illustrating how to configure OVA to activate the button ( Flowplayer,  JW4,  JW5 examples)

A "skip" button can be enabled as follows:

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

5.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 ( Flowplayer,  JW4,  JW5).

That image can be overridden.

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

An example of an overridden button image can be found here ( Flowplayer,  JW4,  JW5).

5.3 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 a HTML button can be found here ( Flowplayer,  JW4,  JW5)

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

If you want to see this option in action, view these examples ( Flowplayer,  JW4,  JW5)

6. Simplified Configuration

In the case of a straight forward pre-roll setup, the OVA configuration approach has been simplified to the point where only a single "shortcut" variable "ova.tag" is required.

That variable specifies the static ad tag to be used to obtain the pre-roll media to play.

6.1. Minimum OVA for JW Setup

To declare a pre-roll setup for OVA for JW Player 4/5, use the following flashvars:

flashvars="plugins=ova&ova.tag=put-your-ad-tag-here"

If you are using the Javascript Embed code for JW5, you can use the variables as follows:

<script type="text/javascript">jwplayer("container").setup({
       flashplayer: "player.swf", 
       file: "http://streaming.openvideoads.org:81/shows/the-black-hole.mp4",
       plugins: {
           "ova": 
                { 
                   tag: "your-tag-goes-here"
                }
       },
       height: 300,
       width: 450
});
</script>

You can find some examples of the minimum OVA for JW setup  here.

When the "ova.tag" option is used, a default 300x250 companion will also be configured - OVA will expect to place this companion into a DIV with an ID of "companion-300x250" on the page - e.g.

<div id="companion-300x250">OVA will insert the companion here</div>

Accordingly, the default companion config provided to OVA with "ova.tag" is:

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

Note that the "restoreCompanions" option is set to false which means the companion will remain on screen post the ad playing.

6.2 Minimum OVA for Flowplayer Setup

To declare a pre-roll setup for OVA for Flowplayer, use the following Flowplayer configuration:

   ova: {
        url: "ova.swf",
        tag: "put-your-ad-tag-here"
   }

6.2 Other Shortcut Setup Variables

To support the "ova.tag" variable, several other "shortcut" variables have been defined. These can be used with the same minimum configuration approach above:

  • ova.debug - maps to the "levels" debug setting - so "ova.debug": "fatal, config, vast_template" sets the debug levels to "fatal, config, vast_template"
  • ova.autoplay - maps to the "autoPlay" config option
  • ova.delayadrequestuntilplay - maps to the standard "delayAdRequestUntilPlay" config option
  • ova.clearplaylist - OVA for JW5 only - allows OVA to be instructed as to whether or not the playlist should be cleared from the player as it initialises
  • ova.allowplaylistcontrol - OVA for JW5 only - maps to the "allowPlaylistControl" option

7. Deferred Loading

Using the "delayAdRequestUntilPlay" configuration option it is possible to defer the ad request to an ad server until the play button has been hit.

An example of the deferred loading option in action can be found here ( Flowplayer,  JW4,  JW5)

8. Ad Server Failover

It is possible to specify secondary ad servers to "fail-over" too when the preceding ad server call fails to return a result.

Fail-over server ad tags are specified using the "failoverServers" configuration property. An array of tags may be declared - each will be tried in turn until a result is returned.

This property can be used at an AdSlot or Server declaration level.

"schedule": [
     {
          "zone": "5",
          "position": "post-roll",
          "server": {
                 "type": "OpenX",
                 "apiAddress": "http://openx.openvideoads.org/openx/www/delivery/fc.php",
                 "oneAdPerRequest": true,
                 "customProperties" : {
                       "target": "category=food" 
                 },
                 "failoverServers": [
                       {
                            "type": "AdTech",
                            "tag": "http://adserver.adtech.de/?adrawdata/3.0/990.1/2366662/
                                        0/1725/noperf=1;cc=2;header=yes;cookie=yes;adct=204;
                                        alias=;key=key1+key2;;=;grp=[group];misc=__random-number__"
                      }
                 ]
          }
     }
]

An example of the failover option in action can be found here ( Flowplayer,  JW4,  JW5)

9. Always setting the show stream duration from Metadata

The "setDurationFromMetaData" configuration option has been implemented for "show" streams in this release.

"shows": {
     "setDurationFromMetaData": true
}

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.

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.

11. New Ad Tag Template Variables

Support has been added for the following new ad tag template variables:

  • media-id - a manually completed field to be specified via "customProperties"
  • media-title - a manually completed field to be specified via "customProperties"
  • media-description - a manually completed field to be specified via "customProperties"
  • media-categories - a manually completed field to be specified via "customProperties"
  • media-keywords - a manually completed field to be specified via "customProperties"
  • media-url - a manually completed field to be specified via "customProperties"
  • page-stream-url - a manually completed field to be specified via "customProperties"
  • partner-id - a manually completed field to be specified via "customProperties"
  • allow-vpaid - a manually completed field to be specified via "customProperties"
  • page-url - an automatically completed field that will be populated with the full url of the page running OVA
  • random-number - an automatically completed field that will be populated with a random number. Used for cache busting
  • amp - replaces automatically with the actual "&" ampersand character. Used to get around Flowplayer JSON parsing issues
  • timestamp - automatically replaced with the current timestamp
  • zone - automatically replaced with the "zone" value (optionally) specified in an ad slot declaration

As usual these variables can be used in an ad tag URL by pre and post-fixing double underscore "__" to the variable name (e.g. __page-url__)

Here's an example ad tag that uses these variables:

http://track.adform.net/serving/videoad/?bn=453599&ord=1298928458467&site=__page-url__&random=__random-number__

When OVA parses this URL, the resulting URL is:

http://track.adform.net/serving/videoad/?bn=453599&ord=1298928458467&site=http%3A//localhost/ova/ova.jwplayer.5x/examples/pages/xml-wrapper/example2-04.html&random=R0.9084519133903086

An example of some of these fields in action can be found  here.

12. Fine Grained Control Over Control Bar Enabling/Disabling

A control bar configuration group has been added to the "ads" config block to allow fine grained control over the enabling/disabling of elements on the control bar during linear ad playback.

The config group is used as follows:

{
    ...
    "ads": {
         "controls": {
              "enableScrubber": false,
              "enableVolume": false,
              "enableMute": false
         },
         "schedule: {
              ...
         }
         ...
   }
}

The full set of control bar enable/disable options are:

  • 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

An example of the control bar configuration group can be found  here.

For JW5, fine level control of the control bar is only available if a custom skin is used. The standard control bar cannot be enabled/disabled this way.

13. Replaced JSwoof JSON with Adobe JSON Parser

To resolve a parsing issue with international characters being used in OVA configuration, the OVA for JW4/5 implementations have replaced the JSON parser used. The Adobe parser is now used instead of JSwoof. While the Adobe parser resolves the international character issue, it is less tolerant to erroneous JSON definitions (e.g. cases where additional commas are left etc.). As a result, when deploying RC4 you may notice that your old configuration doesn't work. If that's the case, check for un-necessary commas etc. in your declaration.

14. Tracking Impressions with Google Analytics

A new configuration option "analytics" has been added. 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.

Two sets of Google Analytics tracking accounts are supported:

  • A Master OVA Account (defaults to GA ID "UA-4011032-6")
  • A Custom Account

The two may be used in parallel, although by default only the Master OVA account is setup.

A full set of analytics examples can be found here:

14.1 Changing the Master OVA Account

By default, the "Master OVA GA account" is set to the OVA GA account ID "UA-4011032-6".

This account ID may be replaced with any account ID of your choosing via the following configuration:

{
     ...
     "analytics": {
          "google": {
                 "ova": {
                        "accountId": "UA-10158120-1"
	         }
          }
     },
     "ads": {
           ....
     }

In the example above, OVA has been instructed to use the GA account ID "UA-10158120-1" for all impression tracking requests.

When OVA makes GA calls, different URLs are used for linear, non-linear and companion impression tracking events.

By default, the following URL structure is applied:

  • linear - "/ova/impression-counter/ova-test/linear"
  • non-linear - "/ova/impression-counter/ova-test/nonLinear"
  • companion - "/ova/impression-counter/ova-test/companion"

A different set of tracking URLs can be specified at any time using the following configuration options:

{
     ...
     "analytics": {
          "google": {
                 "ova": {
                        "accountId": "UA-10158120-1",
   	        	"impressions": {
                              "linear": "/ova/impression-counter/ova-test/linear",
                              "nonLinear": "/ova/impression-counter/ova-test/nonLinear",
                              "companion": "/ova/impression-counter/ova-test/companion"
                        }
	         }
          }
     },
     "ads": {
           ....
     }

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

When enabled, custom tracking will run in parallel with the standard "ova" tracking account.

If you wish to disable the standard OVA tracking account and only use the custom account, use the following configuration:

{
     ...
     "analytics": {
          "google": {
                 "ova": {
                        "enable": false
                 },
                 "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": {
           ....
     }

14.1 Disabling Google Analytics

To disable Google Analytics impression tracking completely, use the "enable": false option as follows.

{
     ...
     "analytics": {
           "google": {
                 "enable": false
           }
     },
     "ads": {
           ....
     }

15. Direct Injection of a VAST Response into OVA via Config

It is now possible to directly inject a VAST response into OVA when configuring the OVA instance.

You can see a few examples of this mechanism in action here ( OVA for JW4,  OVA for JW5,  OVA for Flowplayer).

15.1 OVA for JW4/5 Config File Setup

To pass in a pre-fetched VAST response to OVA when configuring the player via an external config file, use an ad server type of "inject" and place the VAST response data into the "tag" field as follows:

<config>
   <ova.json>
      {
          "ads": {
              "schedule": [
                 {
                    "position": "pre-roll",
                    "server": {
                        "type": "Inject",
                        "tag": "%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22...."
                    }
                 }
              ]
          },

          "debug": {
              "levels": "fatal, config, vast_template, vpaid, playlist",
              "debugger": "firebug"
          }
      }
   </ova.json>
</config>

The VAST response data must be urlencoded when specified in the OVA config file.

15.1 OVA for JW4/5 Flashvars Setup

To pass in a pre-fetched VAST response to OVA when configuring JW Player, use the "ova.vast" flashvar as follows:

var VAST_RESPONSE='<?xml version="1.0" encoding="UTF-8" ?><VAST version="2.0">....';
...
... flashvars="&ova.vast=" + escape(escape(VAST_RESPONSE)) + "&file=OVA_HTTP_SHOW_STREAM_1&duration=30&provider=video" 
...

Notice that the VAST response must be passed into OVA in a double "escaped" (urlencoded) format.

15.2 OVA for JW5 Javascript Embed Setup

The following configuration example illustrates how to configure OVA for JW5 using the Javascript setup method and a pre-fetched VAST response:

<script type="text/javascript">jwplayer("container").setup({
       flashplayer: "/path/to/the/player.swf", 
       file: "http://streaming.openvideoads.org/shows/the-black-hole.mp4",
       plugins: {
           "../../../dist/swf/ova.swf": 
                { 
                  debug: "fatal, config, vast_template, vpaid, http_calls, tracking_events",
                  vast: escape('<?xml version="1.0" encoding="UTF-8" ?><VAST version="2.0">.....</VAST>') 
                }
       },
       height: 300,
       width: 450
});
</script>

To pass in a pre-fetched VAST response, use the "ova.vast" configuration variable. The VAST response string must always be escaped when being passed into OVA.

15.3 OVA for Flowplayer

A VAST response can be directly inserted into the OVA setup via the "tag" variable for the "inject" ad server type:

var VAST_RESPONSE='<?xml version="1.0" encoding="UTF-8" ?><VAST version="2.0">....';

flowplayer("a.example", "../../dist/swf/flowplayer-3.2.3.swf", {
    plugins: {
        controls: {
            autoHide: "always"
        },

        ova: {
            url: "../../dist/swf/ova.swf",

            "ads": {
                "schedule": [
                    {
                       "position": "pre-roll",
                       "server": {
                           "type": "inject",
                           "tag": escape(VAST_RESPONSE)
                       }
                    }
                ]
            }
        }
    }
});

The VAST response must be double escaped when passing into OVA for Flowplayer.

16. Adding Parameters to an Ad Tag at Runtime via "tagParams"

A new configuration option called "tagParams" has been added to allow additional parameters to be added to an Ad Tag URL at runtime. For example, you may want to add "&a=aa&b=bb&c=cc" to an ad tag to dynamically customise it (for example via Javascript) at runtime when OVA is configured.

OVA for JW Player 4 and 5 offer this configuration parameter in the form of a flashvar "ova.tagparams".

The fields to be added to the ad tag are declared using the "ova.tagparams" flashvar as a string that takes the format:

field-name:value,fieldname:value,.....

Below is an example setup using the option as a flashvar:

<OBJECT classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" 
  codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0" 
  WIDTH="450" HEIGHT="300" id="player">
 <PARAM NAME=movie VALUE="../../../dist/swf/5.4.swf">
 <PARAM NAME=quality VALUE=high>
 <PARAM NAME=bgcolor VALUE=#000000>
 <PARAM NAME=allowfullscreen VALUE="true">
 <PARAM NAME=allowscriptaccess VALUE="always">
 <PARAM NAME=flashvars VALUE="plugins=../../../dist/swf/ova.swf&config=../../config/ad-servers/ova04.xml">
<EMBED
 id="player"
 data="../../../dist/swf/5.4.swf"
 src="../../../dist/swf/5.4.swf"
 width="450"
 height="300"
 allowscriptaccess="always"
 allowfullscreen="true"
 flashvars="plugins=../../../dist/swf/ova.swf&config=../../config/ad-servers/ova04.xml&ova.tagparams=a:aa,b:bb,c:cc"
>
</EMBED>
</OBJECT>

A JW4 example can be found  here.

OVA for JW Player 5 also makes this parameter available via the Javascript embed code. The fields to be added to the ad tag are declared as a string that takes the format:

field-name:value,fieldname:value,.....

An example follows:

<script type="text/javascript">jwplayer("container").setup({
       flashplayer: OVA_PLAYER_2, 
       file: "http://streaming.openvideoads.org/shows/the-black-hole.mp4",
       config: "../../config/ad-servers/ova03.xml",
       plugins: {
           "../../../dist/swf/ova.swf": { 
                debug: "fatal, config, vast_template, vpaid, http_calls, tracking_events",
                tagparams: "a:aa,b:bb,c:cc"
           }
       },
       height: 300,
       width: 450
});
</script>

A JW5 example can be found  here.

This example results in the following parameters being added to the ad tag when it's called:

http://the-ad-tag-is-here&a=aa&b=bb&c=cc

OVA for Flowplayer supports it within the Ad Servers JSON configuration block. For example:

...
    "ads": {
         "pauseOnClickThrough": true,
         "servers": [
             {
                 "type": "OpenX",
                 "apiAddress": "http://openx.openvideoads.org/openx/www/delivery/fc.php",
                 "tagParams": {
                      "a": "aa",
                      "b": "bb"
                 }
             }
         ],
...

A Flowplayer example can be found  here.

17. Javascript API

OVA is starting to support a Javascript API. The API is available in two forms:

  • Callbacks from OVA to pre-declared Javascript functions
  • Javascript calls into OVA

17.1 The Javascript Callback API

A number of Javascript callback methods have changed in this release.

As OVA schedules ads to play, the following callbacks are made:

onAdSchedulingStarted()
onLinearAdScheduled(ad:Object)
onNonLinearAdScheduled(ad:Object)
onCompanionAdScheduled(divSpecification:Object, companionAd:Object, parentAd:Object)
onAdSchedulingComplete(ads:Array)

Ad server Template loads result in the following callbacks:

onTemplateLoadSuccess(template:String)
onTemplateLoadFailure(error:String)
onTemplateLoadTimeout(error:String)

The following callback methods are now declared for Linear ads:

onLinearAdStart(ad:Object)
onLinearAdStop(ad:Object)
onLinearAdPause(ad:Object)
onLinearAdResume(ad:Object)
onLinearAdFullscreen(ad:Object)
onLinearAdFullscreenExit(ad:Object)
onLinearAdMute(ad:Object)
onLinearAdUnmute(ad:Object)
onLinearAdReplay(ad:Object)
onLinearAdMidPointComplete(ad:Object)
onLinearAdFirstQuartileComplete(ad:Object)
onLinearAdThirdQuartileComplete(ad:Object)
onLinearAdFinish(ad:Object)

Linear ad notices generate the following callbacks:

onAdNoticeShow()
onAdNoticeHide()
onAdNoticeTick(remainingDuration:int)

Non-linear ads support the following methods:

onNonLinearAdShow(ad:Object)
onNonLinearAdHide(ad:Object)
onNonLinearAdClicked(ad:Object)
onNonLinearAdCloseClicked(ad:Object)

Companion ads generate the following callbacks:

onCompanionAdShow(ad:Object)
onCompanionAdHide(ad:Object)

Dynamically loaded ad slots have the following callback methods:

onAdSlotLoaded(adSlot:Object)
onAdSlotLoadError(message:String)
onAdSlotLoadTimeout(message:String)
onAdSlotLoadDeferred(message:String)

Linear Interactive (e.g. "VPAID" linear) ads have the following callbacks declared:

onVPAIDAdLoaded(ad:Object, runtimeState:Object)
onVPAIDAdImpression(ad:Object, runtimeState:Object)
onVPAIDAdStart(ad:Object, runtimeState:Object)
onVPAIDAdComplete(ad:Object, runtimeState:Object)
onVPAIDAdError(ad:Object, runtimeState:Object)
onVPAIDAdVideoStart(ad:Object, runtimeState:Object)
onVPAIDAdVideoFirstQuartile(ad:Object, runtimeState:Object)
onVPAIDAdVideoMidpoint(ad:Object, runtimeState:Object)
onVPAIDAdVideoThirdQuartile(ad:Object, runtimeState:Object)
onVPAIDAdVideoComplete(ad:Object, runtimeState:Object)
onVPAIDAdClickThru(ad:Object, runtimeState:Object)
onVPAIDAdUserAcceptInvitation(ad:Object, runtimeState:Object)
onVPAIDAdUserMinimize(ad:Object, runtimeState:Object)
onVPAIDAdUserClose(ad:Object, runtimeState:Object)
onVPAIDAdPaused(ad:Object, runtimeState:Object)
onVPAIDAdPlaying(ad:Object, runtimeState:Object)
onVPAIDAdExpandedChange(ad:Object, runtimeState:Object)
onVPAIDAdLinearChange(ad:Object, runtimeState:Object)
onVPAIDAdRemainingTimeChange(ad:Object, runtimeState:Object)
onVPAIDAdLog(ad:Object, event:Object)

The "ad" object passed back takes the following form:

{
   type:String // "linear", "linear-vpaid", "non-linear", "non-linear-vpaid",
   id:String,  
   uid:String,
   inlineAdId:String,  
   adId:String,
   sequenceId:String,
   creativeId:String,
   adSystem:String, 
   adTitle:String,
   description:String,
   survey:String,
   linearAd:Object,
   nonLinearAds:Array,
   companionAds:Array
   extensions:Array
};

The VPAID "runtimeState" object takes the following form:

{
    adExpanded:Boolean.
    adLinear:Boolean,
    adRemainingTime:Number,
    adVolume:int
}

You can find an example of the VPAID callbacks running  here. Inspect the debug output via Chrome Developer Tools or Firefox (with Firebug) and you'll be able to traverse both the Ad and runtimeState objects that are passed in the Javascript callbacks.

The "linearAd" object takes the following form:

   adId:String,
   id:String,
   uid:String,
   scalable:String,
   maintainAspectRatio:String,
   duration:String,
   mediaFiles:Array

the "mediaFiles" array is an array of MediaFile objects, each taking the form:

   id:String,
   bandwidth:String,
   delivery:String,
   scale:String,
   maintainAspectRatio:String,
   mimeType:String,
   bitRate:String,
   width:String,
   height:String,
   apiFramework:String,
   urlId:String,
   url:String,
   adParameters:String

"nonLinearAds" is an array of non-linear ad objects. Each non-linear ad object has:

{
   id:String,
   adId:String,
   uid:String,
   width:int,
   height:int,
   expandedWidth:int,
   expandedHeight:int,
   resourceType:String,
   creativeType:String,
   apiFramework:String,
   scalable:Boolean,
   maintainAspectRatio:Boolean,
   recommendedMinDuration:int,
   url:String,
   codeblock:String
}

"companionAds" is an array of companion objects. Each companion object has:

{
   id:String,
   adId:String,
   uid:String,
   divId:String,
   altText:String,
   width:int,
   height:int,
   resourceType:String,
   creativeType:String
   markup:String
}

"extensions" are the VAST extensions that have been provided by the ad server. The field is an array of Objects, with each element being the content of the <extension></extension> tagset in the VAST response- two attributes are declared on the objects in the array - "label" and "text". The "label" is the type declared for the extension and the "text" is the content within the extension tagset.

For example, an extension tagset as follows:

<Extensions>
   <Extension type="LR-Pricing">
      <Price model="CPM" currency="USD">6</Price>
   </Extension>
   <Extension type="SpotX-Count">
      <total_available>9</total_available>
   </Extension>
   <Extension type="Location">
       London
   </Extension>
</Extensions

yields:

ad.extensions[0] == { label: "LR-Pricing", text: "<Price model="CPM" currency="USD">6</Price>" }
ad.extensions[1] == { label: "SpotX-Count", text: "<total_available>9</total_available>" }
ad.extensions[2] == { label: "Location", text: "London" }

17.2 The Javascript API into OVA (Experimental)

Calls can be made from Javascript into OVA.

At present, these calls are limited to the following:

getOVAPluginVersion():String
setActiveLinearAdVolume(volume:Number):Boolean
setDebugLevel(levels:String):Boolean
getDebugLevel():String
getAdSchedule():Array
getStreamSequence():Array
scheduleAds(playlist, config)

setActiveLinearAdVolume(volume:Number):Boolean sets the volume level on the currently active linear ad (standard stream of VPAID linear ad). The volume parameter should be a value between 0 (mute) and 100 (full volume). If the volume has been successfully set, true will be returned.

setDebugLevels(levels:String) sets the active debug levels on the OVA instance in accordance with the "levels" specified (e.g. "fatal, config, vast_template, vpaid, api" etc.)

scheduleAds allows a new ad schedule to be generated by OVA - a playlist can be passed in (as an Array of playlist objects) along with the new OVA config to be applied - which can either be a JSON string or a valid OVA config object.

17.2.1 Calling the OVA for Flowplayer Javascript API

The following code snippet illustrates how to call the OVA Javascript API when using OVA for Flowplayer. This code snippet assumes the OVA plugin is configured within Flowplayer using the JSON ID "ova":

flowplayer().getPlugin('ova').setActiveLinearAdVolume(50);

You can find an example of this code running  here.

17.2.2 Calling the OVA for JW5 Javascript API

To use the API into the OVA SWF from Javascript, the JW5 OVA Javascript plugin needs to be deployed.

You can find a full source version of "ova.js"  here, or a minified version  here. Please do not reference the QA server directly to load up the OVA JS plugin - download it and place it on your servers with the OVA SWF.

It is important to note that the OVA Javascript plugin file "ova.js" or "ova.min.js" must be placed in the same directory/location as your OVA SWF because the Javascript plugin loads the OVA SWF and expects to find it in the same location as the Javascript file.

To configure OVA to use the Javascript plugin that bridges the OVA SWF, configure OVA with JW5 as follows:

plugins: {
    "/path/to/your/ova.js": {
            put your standard OVA config here
    },

or if you are running the minified version of the OVA Javascript plugin:

plugins: {
    "/path/to/your/ova.min.js": {
            put your standard OVA config here
    },

By declaring the "ova.js" Javascript file as the plugin to JW, the OVA plugin is loaded in "hybrid" mode which ensures that Javascript calls to OVA will be forwarded to the OVA SWF.

Once active, you can then make calls to OVA getPlugin("ova") - for example:

jwplayer().getPlugin("ova").setActiveLinearAdVolume(50);

You can find an example of this setup running  here.

Making Direct Calls

It is possible to make direct calls into the OVA SWF from Javascript without using the JW Embedder to setup the player. You may want to do this if you are using SWFObject etc. to setup your player. To call OVA under this circumstance, use document.getElementById(player-id-goes-in-here).apiCall() - for example:

document.getElementById("myplayer").ovaSetActiveLinearAdVolume(volume)

Please note, when making direct calls into the OVA for JW5 SWF via Javascript, all API calls need to be prefaced with "ova" (e.g. ovaSetActiveLinearAdVolume()). Failure to do so will result in a Function not found error being reported by Javascript. API calls made with the OVA Javascript plugin do not have the prefacing "ova" characters.

18. Support Click Throughs with SWF Companions

If a Companion Ad has either the <AdParameters> and/or a <CompanionClickThrough> declared in the VAST response, the values will be passed through to the SWF as follows:

  • If there is a <CompanionClickThrough> specified, the escaped value (e.g. escape(value)) is passed through as a "clickTAG" flashvar
  • If there are <AdParameters> specified, the value is passed through directly as flashvars
  • If both a specified, the <CompanionClickThrough> is specified first as "clickTag=" followed by "&" plus the value of the <AdParameters>

19. Setting the "linearScaling" Configuration Option

A configuration option has been added to allow the "linear scaling" attributes of ad streams to be forcibly set.

The option is used as follows:

   ...
      "ads": {
          "linearScaling": "value-goes-in-here",
          "schedule": [
               ...
          ]
      }
   ...

"linearScaling" takes a string value. The value is dependant upon the player implementation.

For Flowplayer, the value can be either:

  • "orig"
  • "fit"
  • "scale"

For JW Player, the value can be either:

  • "uniform"
  • "fill"
  • "exactfit"
  • "none"

20. Improved Support for RTMP Ads

RC4 includes improved support for RTMP 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

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

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

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

21. Configuring OpenX V3

Support has been added for OpenX V3.

OpenX V3 ad tags may be configured in two ways:

  • Directly as static ad tags
  • Dynamically using the new "OpenX3" ad server type

The following code snippet illustrates an example pre-roll setup using a static OpenX V3 ad tag:

{ 
   ...
   "ads": {
         "companions": [
         	{ "id": "companion-1", "width": 300, "height": 250 }
         ],
         "schedule": [
               {
                   "position": "pre-roll",
                   "tag": "http://oxdemo-d.openxenterprise.com/v/1.0/av?pgid=91__amp__test=true"
               }
         ]
   }
   ...
}

Where multiple ad calls are to be combined into a single ad call, the new OpenX3 dynamic ad server configuration should be used. The following code snippet illustrates an example setup where a linear and non-linear ad call are combined into a single call:

    ....
            "ads": {
                "servers": [
                    {
                      "type": "OpenX3",
                      "apiAddress": ""http://oxdemo-d.openxenterprise.com/v/1.0/av",
                      "tagParams": {
                          "test": "true",
                          "c.topic": "sports",
                          "c.gender": "male"
                      }
                    }
                ],
                "schedule": [
                    {
                       "zone": "auid=9",
                       "position": "pre-roll"
                    },
                    {
                       "zone": "pgid=127",
                       "position": "bottom:auto",
                       "startTime": "00:00:02"
                    }
                ]
            }
     ....

The "tagParams" configuration option allows additional parameters to be added to the end of the ad tag as it's formed. The ad tag for the case above ends up taking the following form:

http://oxdemo-d.openxenterprise.com/v/1.0/av?auid=9&pgid=127&test=true&test=true&c.gender=male&c.topic=sports

22. Maintaining the playlist with OVA for JW Player 5

By default OVA replaces the JW Player playlist and loads up each clip one clip at a time during playback.

This obviously causes issues with playlist controls that require the entire playlist to be maintained permanently in the player.

Two options have been introduced to allow OVA for JW Player 5 to maintain a full playlist and work with Playlist controls:

  • "allowPlaylistControl" - ensures that OVA maintains the full playlist in the player after ad scheduling (instead of placing 1 clip at a time into the player which is its default behaviour)
  • "enforceLinearAdsOnPlaylistSelection" - ensures that selections from a playlist enforce checks to determine if pre-roll(s) attached to show clips should be played first

You can find an example running  here.

This example uses the internal JW 5 playlist control. You will notice that the playlist shows "Open Video Ads Served Ads" in slots in the playlist. These are the scheduled pre-rolls that are to be played. Unless a playlist control explicitly identifies the OVA ads and excludes them from the display, they will appear as playlist items.

"enforceLinearAdsOnPlaylistSelection" is an interesting option. If this option is set to true, a click on a show clip in a playlist control will result in the associated pre-rolls being played before the show clip is played. This option is set to "false" by default.

The following code snippet illustrates a sample setup using these options:

{
     "allowPlaylistControl": true,
     "ads": {
          "enforceLinearAdsOnPlaylistSelection": true,
          "schedule": [ 
          ],
          ....
     }
}

22.1 How to exclude ad clips from showing in a JW5 Playlist Control

To explicitly exclude OVA linear ads from being displayed within a Playlist Control, the playlist control needs to recognise that the OVA clips are ads and elect to not show them.

To help Playlist controls identify OVA ad clips, a number of properties are set on each OVA scheduled clip:

  • For Ads
    • 'ova.hidden': true - this is set and is true if the clip is an OVA ad (legacy property)
    • 'ovaAd': true - this is set and is true if the clip is an OVA ad - preferred property to use in place of 'ova.hidden'
    • 'ovaZone' - the zone value recorded against the ad slot in the schedule
    • 'ovaSlotId' - the id given to the ad slot
    • 'ovaPosition' - the value of the "position" property set against the ad slot in the schedule
    • 'ovaPlaylistIndex' - the index of this clip in the playlist
    • 'ovaAssociatedStreamIndex' - the index of the show stream in the stream sequence that is associated with this ad clip
    • 'ovaAdType' - the type of ad - "pre-roll", "mid-roll", "post-roll"
    • 'ovaInteractive' - is true if the ad is a VPAID ad
  • For Show Streams
    • 'ovaAssociatedPrerollClipIndex' - the playlist index of the first pre-roll clip associated with this show stream
    • 'ovaPlaylistIndex' - the index of this clip in the playlist
    • 'ovaAssociatedStreamIndex' - the index of this clip in the show stream sequence
    • 'ovaIsEndBlock' - true if this clip marks the end of a block of streams

In OVA for Flowplayer, these OVA properties are set on the clip.customProperties object.

In OVA for JW5, the OVA properties are set directly on the JW Clip object.

23. Supporting Overlays on Live Streams (JW5 and Flowplayer Only)

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

An example of the option working can be found  here:

Here's the code snippet for the OVA config used by that example:

      {
            "shows": {
               "streamTimer": { "enabled": true, "tickRate": 100 }
            },
            
            "ads": {
                "servers": [
                    {
                      "type": "OpenX",
                      "apiAddress": "http://openx.openvideoads.org/openx/www/delivery/fc.php"
                    }
                ],

                "schedule": [
                    {
                      "zone": "30",
                      "position": "center:auto",
                      "startTime": "00:00:02",
                      "duration": 10,
                      "width": 450,
                      "height": 50
                    }
                ]
            },
        }
  }

The "tickRate" option is not mandatory. By default it is set to 100 which equates to 100 milliseconds (1/10th of a second). If you need to change the timer tick rate, use that option and specify the value in milliseconds.

The "streamTimer" option is disabled by default.

24. Hard coding the control bar height

A new config option has been introduced to allow the control bar height to be hard coded.

{
     "ads": {
         "controls": {
              "height": 28
         },
         ...
    }
}

This option is useful when the standard Flowplayer 3.2.6 controls are used as they report 0 in height (for some strange reason). Using this option allows the height to be correctly determined for the control bar and it will override anything that OVA tries to determine using the Flowplayer control bar API.

24. How to use "blockUntilOriginalPlaylistLoaded" with OVA for JW Player 5

Several JW Player playlist configurations require OVA to block initialisation until the playlist has been loaded.

Once example is when "levels" are used in the JW setup code to specify bit-rated playlist files.

For example:

<script type="text/javascript">
	jwplayer("container70").setup({
	autostart: false,
	controlbar: "over",
	levels: [
		{ bitrate: 150, file: "http://mystreamer.com/low.mp4", width: 320 },
		{ bitrate: 400, file: "http://mystreamer.com/medium.mp4", width: 320 }
        ],
	duration: 30,
	provider: "http",
	plugins: {
		"/dist/swf/ova.swf": {}
	}, 
	flashplayer: "/dist/swf/5.4.swf",
	config: "config1.xml",
	volume: 90,
	height: 360,
	width: 480
	});
</script>

When this type of setup is specified, it is important to instruct OVA to block initialisation until the original playlist is loaded.

There are two ways to do that:

  • Within the Javascript JW setup code
  • Within the external config file

24.1 Blocking via the Javascript Embed Code

The following code snippet illustrates how to instruct OVA via the Javascript setup code to block until the playlist is loaded:

<script type="text/javascript">
	jwplayer("container70").setup({
        ....
	plugins: {
		"/dist/swf/ova.swf": { 
                          blockUntilOriginalPlaylistLoaded: true 
                }
	}, 
        ....
</script>

24.1 Blocking via the external config file

Alternatively, the blockUntilOriginalPlaylistLoaded option can be specified in the external JW Player config file as follows:

<config>
   <ova.blockUntilOriginalPlaylistLoaded>
        true
   </ova.blockUntilOriginalPlaylistLoaded>
   <ova.json>
            ....
   </ova.json>
</config>

25. Clearing the Playlist (OVA for JW Player 5 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.

26. Supporting URL Resolvers/Proxies with OVA for Flowplayer

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.

This allows the final ad stream URLs (e.g. the netConnectionURL etc) to be derived at runtime by supporting plugins such as the Akamai plugin.

To enable this feature, configure OVA with the "enableProxies" option as follows:

"ova": {
     "ads": {
           "enableProxies": true,
           ...
     }
}

You can find an example running  here.

27. Timing Out Ad Server Calls

A configuration option has been added to allow a timeout value to be set on ad calls - this stop an ad server blocking the player if they don't return a value while holding the call open.

The option is "timeoutInSeconds" and should be specified within the "servers" configuration block at a general level, of the "server" config block at an ad slot level.

The maximum length of time to wait for an ad server to respond must be specified in seconds (whole numbers only are supported - e.g. 10 not 10.5).

For instance:

{
     ...
        "ads": {
             "servers": [
                   {
                       "type": "Direct",
                       "apiAddress": "http://static.openvideoads.org/tests/delayed-ad-tag-processor.php",
                       "timeoutInSeconds": 10
                   }
             ],
             "schedule": [
                    {
                       "zone": "5",
                       "position": "pre-roll"
                    }
             ]
        }
    ...
}

You can see an example of the timeout in action  here.

Finally, when an ad tag times out (and doesn't fail over to another ad request), a Javascript callback event is generated. The Javascript callback API is:

onVASTLoadTimeout(error:String)

28. Specifying a target window for a click-through

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

29. Hard Coding Player Dimensions (JW5 only)

To get around an issue related to JW5 reporting dimensions of 0x0 when the player is embedded via an iFrame on IE7 running under Windows 7 or Vista, a configuration option has been added to allow the dimensions of the player to be hard-coded.

To set the player dimensions, use the following config:

{
    "player": {
          "width": 450,
          "height": 250
    },

    "ads": {
         ....
   }
}

This option has been implemented for OVA for JW5 only.

30. Changing the Default Ad Title and Description

A config option has been added to allow 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 may end up with:

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

You can see an example of this config option in action [X here].

31. OVA for JW5 Embedded Javascript Configuration with JW 5.6

JW Player 5.6 permits deep, nested JSON configuration using the Javascript based JW Embedder.

With the RC4 release, OVA for JW5 supports this form of configuration bringing the JW OVA configuration approach in line with OVA for Flowplayer.

Below is an example of the nested JSON configuration approach now supported by JW 5.6 and OVA RC4.

<script type="text/javascript">jwplayer("container").setup({
       flashplayer: "../../../dist/swf/jw-5.6.swf", 
       playlist: [
           { file: "http://streaming.openvideoads.org:81/shows/the-black-hole.mp4" }
       ],
       plugins: {
           "../../../dist/swf/ova.swf": { 
              "debug": {
                  "levels": "fatal, config, vast_template, vpaid"
              },

              "ads": {
                 "playOnce": false,
                 "servers": [
                     {
                        "type": "OpenX",
                        "apiAddress": "http://openx.openvideoads.org/openx/www/delivery/fc.php"
                     }
                 ],
                 "schedule": [
                     {
                        "zone": "5",
                        "position": "pre-roll"
                     }
                 ]
              }
           }
       },
       height: 300,
       width: 450
});
</script>

You can find an example running  here.

32. Specifying additional OBJECT/EMBED params for Companion SWFs

An additional Ads config group setting additionalParamsForSWFCompanions has been added to allow additional parameters to be specified when the companion SWF object/embed tags are generated by OVA.

Below is an example of how to use this new config property:

{
     "ads": {
          "companions": [
                { "id":"companion", "width":"300", "height":"250", "index": 1 }
          ],
          "additionalParamsForSWFCompanions": [
                { "name": "wmode", value: "transparent" }
          ],
          "schedule": [
              ...
          ],
          ...
     },
     ...

In this example a single new parameter is to be included in the SWF object/embed tag set - "wmode" with a value of "transparent".

The additionalParamsForSWFCompanions property takes an Array of Objects as an argument with each object representing a single param to add to the object/embed tagset - the fields specify a name and value to use when generating the additional object/embed markup.

An example of this running can be found  here.

33. On-demand loading of ad tags (OVA for JW5 only)

RC4 introduces the notion of "on-demand" loading of ad tags (for linear ads only).

Previous versions of OVA pre-fetch all ads at startup time. The pre-fetching can be slightly delayed with the "delayAdRequestsUntilPlay" option, but with the pre-fetch model they still all happen when the user presses the play button.

This is less than ideal for player setups that have long playlists as it results in many unused ad calls.

From an ad provider perspective, this in turn makes the task of inventory management just that little bit more difficult.

OVA provides a solution via the "loadOnDemand" option.

Individual ad slots within a schedule may be declared as "loadOnDemand" - if OVA sees this config option set to "true", then the ad call will only be made just before the ad is to be played.

Detailed below is an example configuration that illustrates how to use this option to ensure that each pre-roll ad is fetched only as required:

{
    ...
    "ads": {
         "holdingClipUrl": "/path/to/your/holding-clip.mp4",
         "schedule": [
              {
                   "position": "pre-roll",
                   "loadOnDemand": true,
                   "tag": "place-your-ad-tag-here"
              }
         ]
    }
    ...
}

An example of this option in action can be found  here.

Linear "On Demand" ad clips use a blank clip termed a "holding clip" as a placeholder in the player playlist while the ad is being fetched and loaded into the player. If the ad call fails, the blank holding clip plays allowing playback to smoothly continue on.

Whenever you configure an "on demand" linear ad slot, you must ensure that an appropriate "holding clip" is specified in the config.

A default holding clip can be downloaded from the OVA static asset server here -  http://static.openvideoads.org/ads/blank/blank.flv. This clip is a 1 second blank FLV clip.

Please note, never run a production config using holding clips served from the OVA asset server. This is a test server and is up and down constantly. Failure to retrieve a holding clip will impact the playback in your player. Always serve the holding clip from a server that you can rely on.

33.2 Blocking the first "on-demand" ad call until the Play button is pressed

In the case of a pre-roll, although the "loadOnDemand" option is set, the ad call for that pre-roll will still occur when the player is loaded up.

To ensure that this first ad call does not happen until the user hits play, add in the "delayAdRequestUntilPlay" option as follows:

{
    ...
    "delayAdRequestUntilPlay": true,

    "ads": {
         "schedule": [
              {
                   "position": "pre-roll",
                   "loadOnDemand": true,
                   "tag": "place-your-ad-tag-here"
              }
         ]
    }
    ...
}

An example of this option in action can be found  here.

33.3 "On Demand" Ad Slots and Playlists

The "loadOnDemand" option can be used with fully loaded playlists. For example, in JW5, you may configure "onDemandAdSlots" as follows:

'plugins': {
           "../../../dist/swf/ova.swf": { 
               "allowPlaylistControl": true,

               "debug": { 
                   "levels": "fatal, config, vast_template, vpaid, http_calls, tracking_events, playlist, api" 
               },
               
               "ads": {
                   "holdingClipUrl": "http://static.openvideoads.org/ads/blank/blank.flv",
                   "schedule": [
                       {
                          "position": "pre-roll",
                          "loadOnDemand": true,
                          "tag": "http://openx.openvideoads.org/openx/www/delivery/fc.php?
                                  script=bannerTypeHtml:vastInlineBannerTypeHtml:vastInlineHtml&
                                  zones=pre-roll0-0%3D5&nz=1&source=&r=R0.8062691302038729&
                                  block=1&format=vast&charset=UTF-8"
                       }
                   ]
               }
           }
       }
}

"allowPlaylistControl" results in a full playlist be loaded into the player. Holding clips will be placed where ads are expected to be played, and then as the player gets to a point in the playlist where an ad is to be played, the ad call will be triggered and the returned ad will be loaded up in place of the holding clip.

An example can be found  here.

"loadOnDemand" may also be used with the "enforceLinearAdsOnPlaylistSelection" option.

An example can be found running  here.

34. Refreshing ads on replay (OVA for JW5 only)

The "refreshOnReplay" option has been introduced to allow OVA to request a new ad each time the ad slot is played.

This option is only available with the "loadOnDemand" model.

The following code snippet illustrates how to ensure that a new ad call for a pre-roll occurs each time the ad slot is played:

{
    ...
    "ads": {
         "schedule": [
              {
                   "position": "pre-roll",
                   "loadOnDemand": true,
                   "refreshOnReplay": true,
                   "tag": "place-your-ad-tag-here"
              }
         ]
    }
    ...
}

An example of this option in action can be found  here.

35. Hiding a Custom Logo during Linear Ad Playback (Licensed JW5 players only)

If you have a licensed JW5 player you can now instruct OVA to hide a custom logo during linear ad playback.

The new option is "hideLogoOnLinearPlayback" and should be used as follows:

{
    ...
    "ads": {
           "hideLogoOnLinearPlayback": true,
           "schedule": [
               ...
    }
}

An example of this option in action can be found  here.

Minimum version providing this feature is OVA for JW5 0.6.0 RC3 (build 213).

36. VAST1 - Splitting multiple ad units within a single "inline" ad element

Some VAST 1 ad servers return multiple ad units within a single "inline" ad element.

The two units are the "media files" that constitute the linear ad, and a set of non-linear ads that may be related.

OpenX VAST1 responses support the notion of "click-to-play" overlays where the media files may be attached to one of the non-linear ads. As far as we are aware, this is the only ad server that supports that definition of a single "inline" ad element that purposely ties the linear media files to the non-linear ad units.

RC4 has modified it's VAST 1 parsing logic to recognise if a VAST1 response is from an OpenX ad server or not. It uses the adSystem tagset in the VAST response to determine if the ads have originated from an OpenX ad server.

If they have not originated from an OpenX ad server, a VAST1 response that has both the media files and non-linear ads within a single "inline" element will be split into two separate ad units - a linear ad (with the media files allocated) and a set of non-linear ads.

You can override this default behaviour if required and instruct OVA to leave the video ad structure as is. To do so, configure OVA with the "ensureSingleAdUnitRecordedPerInlineAd" option as follows:

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

You can find an example of this option in action  here.

37. Using OVA with HTML Playlists and/or the JW "player.load()" Javascript API

Support for jwplayer.load(playlist|clip) javascript API has been added to OVA for JW5 in build 214.

When the jwplayer.load() javascript API is called on JW Player 5, OVA can now react to that and reschedule the specified ads against the newly loaded playlist/clip.

Amongst other things, this allows HTML playlists to be supported.

37.1 Enabling jwplayer.load() call

To enable OVA to react when the Javascript jwplayer.load() call is made, the supportExternalPlaylistLoading: true config option must be used as follows:

...
       "supportExternalPlaylistLoading": true,

       "ads": {
            "schedule": [
                 {
                     "position": "pre-roll",
                     ...

You can see an example of this option in action  here.

37.2 Enabling "auto start"

By default, when jwplayer.load() is used to load new clips into the JW Player and trigger OVA to schedule ads against those clips, the resulting playlist will not automatically start to play.

There are three different approaches that can be used to force OVA to auto-play newly loaded playlists:

  1. Use the standard "autostart" JW flashvar or "autoPlay" OVA configuration option - however this means that the player will also auto start when the page is loaded which may not be ideal.

You can find an example of this in action  here.

  1. Use a new OVA option called "autoPlayOnExternalLoad". When this option is used, OVA will only auto start playback when the jwplayer.load() javascript call is used to trigger rescheduling. The option should be used as follows:
...
       "supportExternalPlaylistLoading": true,
       "autoPlayOnExternalLoad": true,

       "ads": {
            "schedule": [
                 {
                     "position": "pre-roll",
                     ...

You can find an example of this option in action  here.

  1. Use the new OVA Javascript callback onOVAReadyToPlay(initialisationCounter) to be notified when OVA has completed ad scheduling as a result of the jwplayer.load() trigger. You can then use jwplayer.play() to start playback manually via Javascript. The "initialisationCounter" argument passed in the "onOVAReadyToPlay" callback can be used to identify whether OVA has started up as a result of the player being loaded for the first time or as a result of subsequent jwplayer.load() calls. When OVA first loads and completes scheduling, the value of "initialisationCounter" will be 0, then on each subsequent rescheduling operation, the value will be incremented by 1.

A typical onOVAReadyToPlay() implementation is as follows:

function onOVAReadyToPlay(initialisationCounter) {
   if(initialisationCount > 0) {
      jwPlayer("container").play();
   }
}

This method can be seen in action  here.

38. Turning off VAST Tracking on Ad Replays

A new option "resetTrackingOnReplay" has been added to allow VAST tracking to be turned on/off for ad replays. By default the option is set to "true" which ensures that VAST tracking events are fired each time the ad is replayed.

To turn off tracking on replays, use the option as follows:

{
   ...
   "ads": {
        "resetTrackingOnReplay": false,
        "schedule": [
            ...

You can find an example of this option in action  here.

39. Turning on OVA Variable Substitution in Wrapped Ad Tags

An option has been added to allow OVA variables such as "site-url", "random-number" etc. housed in Wrappers to be dynamically replaced when the ad tag is called.

See section 11 of this release note for the variables that are available.

To turn on wrapped ad tag variable substitution use the "parseWrappedAdTags" option as follows:

{
    ...
    "ads": {
          "parseWrappedAdTags": true,
          ...

You can find an example of that option running  here.

40. New Debug Levels

Two new debug levels were introduced in RC5 - "vpaid" and "api".

Use "vpaid" to print out VPAID related debug information, while "api" will output OVA Javascript related debug data.

41. Supporting Mid-Rolls on Live Streams with OVA for JW5

Because OVA for JW5 attempts to slice up a stream to insert mid-rolls, to support mid-rolls on live streams (where it doesn't make sense to slice them), the "postMidRollSeekPosition" configuration option must be set.

The option is used as follows:

{
    ...
    "ads": {
          "positionMidRollSeekPosition": 0,
          ...

An integer value is set with the "positionMidRollSeekPosition" option - this value tells OVA the start time position for the stream once the mid-roll has played.

Normally this position will be set to the point at which the mid-roll was inserted. For live streams however, the position should be 0 (the start of the stream when it is re-established post the mid-roll playing).

You can see an example of this option running  here.

Finally, it should be noted that OVA for JW5 only supports mid-rolls if a duration is specified for the stream.

42. Automatically spacing the start time for "repeated" ad slots with an "interval"

It is now possible to schedule repeated mid-stream (overlay and mid-roll) ad slots so that the start times are automatically spaced by a specific number of seconds.

A new "interval" ad slot configuration option has been provided to achieve this.

The option should be declared as follows:

{ 
   ...
   "ads": {
        "schedule": [
             {
                 "zone": "5",
                 "position": "mid-roll",
                 "startTime": "00:00:10",
                 "repeat": 3,
                 "interval": 10
             }
        ]
   }
   ...
}

The "interval" value should always be specified as the number of "seconds" that is to be placed between each repeating instance of the ad slot.

You can see an example of this option running  here.