| Version 55 (modified by paul, 2 years ago) (diff) |
|---|
TracNav
Project
Dev Corner (restricted)
- Register for Access
- Download Latest Releases
- Browse Source Code
- Accessing Subversion
- Release Archive
- Report an Issue
Support
Other Resources
What's New? (Release Candidate 3 - February X 2011)
The following versions have been issued as "release candidates".
- OVA for AS3 v0.6.0 (build X)
- OVA for JW Player 4 v0.5.0 (build X)
- OVA for JW Player 5 v0.5.0 (build X)
- OVA for Flowplayer v0.6.0 (build X)
The following changes are in this release:
- VAST 2 wrapper support
- VPAID 1.1 Linear Ad support (JW only. Flowplayer support will be in the next RC along with non-linear VPAID 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 default OVA impression tracking)
- 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
- Implemented overlay ad support on live streams - OVA for JW5 and OVA for Flowplayer only
1. Download the Release Candidates
You can download the full release candidate package via the following links:
- ova.as3-rc.tar.gz (0.6.0)
- ova.flowplayer-rc.tar.gz (0.6.0)
- ova.jwplayer.4x-rc.tar.gz (0.5.0)
- ova.jwplayer.5x-rc.tar.gz (0.5.0)
If you just want the OVA.swf or AS3 framework library file, download via these links:
- OVA for AS3 (SWC)
- OVA for JW Player 4 (SWF)
- OVA for JW Player 5 (SWF)
- OVA for Flowplayer (SWF)
Finally, the latest release candidate code can be found in the SVN "packages" directory, or the "tags" directory.
2. RC2 Examples
You can find the full set of RC2 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. At this time the support has been added to the AS3 framework, OVA for JW4 and OVA for JW5 plugins.
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 JW Player 5
VPAID ads will be played by default by OVA for JW Player 5. No specific configuration is required.
To see an example VPAID linear ad in action (JW5), click here.
The default behaviour for OVA is to hide the control bar during VPAID Linear Ad playback. This behaviour can be overridden (see below).
4.2 Enabling VPAID for OVA for JW Player 4
For VPAID Linear Ads to work with OVA for JW Player 4, a "holding" clip must be placed in the position of the linear ad within the playlist. A holding clip is a "minimal" image - a single black pixel image file.
OVA automatically places this "holding" clip when it schedules the ads to play.
The holding clip must be hosted on a server of your choice.
The following configuration structure is used to instruct OVA for JW4 as to the location of the holding clip:
{
"ads": {
"vpaid": {
"holdingClipUrl": "http://static.openvideoads.org/ads/blank/blank-pixel.jpg"
},
"schedule": [
.....
]
}
}
To see an example JW4 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.
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:
- Register the VPAID event handlers
- Implement the VPAID event handlers
- 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 in this release.
When configuring OVA, all that is required now for the minimal pre-roll setup is the ad tag itself.
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"
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"
}
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
- media-title
- media-description
- media-categories
- media-keywords
- media-url
- page-stream-url
- partner-id
- domain
- allow-vpaid
EXPLAIN EACH HERE
12. Fine Grained Control Over Control Bar Enabling/Disabling
EXPLAIN HERE
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 RC3 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
EXPLAIN HERE
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 Callback API
A number of Javascript callback methods have changed in this release.
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 Interactive (e.g. "VPAID" linear) ads have the following callbacks declared:
onVPAIDAdStart(ad:Object) onVPAIDAdComplete(ad:Object) onVPAIDAdError(ad:Object) onVPAIDAdExpandedChange(ad:Object) onVPAIDAdLinearChange(ad:Object) onVPAIDAdRemainingTimeChange(ad: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,
companions:Array
extensions:Array
};
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
}
"companions" 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" }
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
RC3 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.
RC3 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:
- netConnectionAddress: rtmp://ne7c0nwbit.rtmphost.com/videoplayer
- filename: mp4:ads/30secs/country_life_butter.mp4
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:
- netConnectionAddress: rtmp://ne7c0nwbit.rtmphost.com/videoplayer
- filename: mp4:ads/30secs/country_life_butter.mp4
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
"allowPlaylistControl" - describe the implementation
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.
