wiki:OvaReleaseNote-1.0.0-RC7

What's New? (1.0.0 Release Candidate 7)

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

  • OVA for AS3 v1.0.0 RC7
  • OVA for JW Player 4 v1.0.0 RC7
  • OVA for JW Player 5 v1.0.0 RC7 (requires JW 5.6 or higher to run)
  • OVA for Flowplayer v1.0.0 RC7

RC7 includes a number of key changes over RC6:

  • There have been some filename changes in the package (see section 1 below for details)
  • The configuration structure has been refined. Various options have moved around and been renamed (consult section 2 for details)
  • Various APIs in the OVA Framework have changed (see section 3)
  • A new player display definition model has been introduced into OVA to allow margins etc. to be more effectively specified for various playback types (described further in section 4)
  • Non-linear ads can now be displayed using HTML5, this allows OVA to support iFrame and Javascript non-linear ad types in overlay and non-overlay format (consult section 6 for further information)
  • Improved Google Analytics support (see section 5 for details)

RC7 follows RC6 - please refer to the RC6 release note for a full account of all changes made up to and including RC6.

1. SWF and Javascript File Name Changes

The following SWF and Javascript file name changes have occurred in this release:

  • In preparation for the V1.0 production release, the OVA for JW5 and OVA for JW4 SWFs have been renamed to "ova-jw.swf" - in addition the OVA for JW5 Javascript plugin has been renamed to "ova-jw.js". These will be the official names of the OVA for JW V1.0 plugins (renaming them allows the pre V1.0 plugins/setups to continue operating untouched on the Longtail plugin repository). It is also worth noting that existing OVA configurations will work with the new names (e.g. your JW5 external config files do not require change as the <ova.XXXX> tagset will work with the "ova-jw" SWF naming)
  • The previously named OVA jQuery companion support Javascript file ova-jquery-companions.js has been renamed to ova-jquery.js to better reflect the new "non-companion" functionality that it now includes

2. Depreciated Configuration Options

While OVA will attempt to remain backward compatible, a number of configuration options have been moved around in the RC7 release as part of a general clean up to the configuration structure. These include:

Regions and Overlay configuration changes

  • "overlays:{}" config block has become "regions:{}"
  • "overlays.controlButton" has become "regions.controlButton"
  • "overlays.regions[]" has become "regions.declarations[]"
  • "ads.replayNonLinearAds" has become "overlays.replay"
  • "ads.acceptedNonLinearAdMimeTypes" has become "overlays.acceptedMimeTypes"
  • "ads.enableOverlayScaling" has become "overlays.enableScaling"
  • "ads.enforceOverlayRecommendedSizing" has become "ads.overlays.enableScaling"

Companion configuration changes

  • "ads.companions[]" has become "ads.companions.regions"
  • "ads.processCompanionsExternally" has become "ads.companions.html5"
  • "ads.millisecondDelayOnCompanionInjection" has become "ads.companions.millisecondDelayOnInjection"
  • "ads.displayCompanions" has become "ads.companions.enable"
  • "ads.restoreCompanions" has become "ads.companions.restore"
  • "ads.additionalParamsForSWFCompanions" has become "ads.companions.additionalParamsForSWFCompanions"

Skip Ads and Control Bar configuration changes

  • "ads.controls.skipAd" has become "ads.skipAd"
  • "ads.controls{}" has become "player.modes.linear.controls"
  • "ads.disableControls" has become "player.modes.linear.controls.manage"

VPAID configuration changes

  • "ads.vpaid.controls.hideOnLinearPlayback" has become "player.modes.linear.controls.vpaid.visible"

Ad scheduling configuration changes

  • "ads.schedule[].position" for non-linear ads has become "ads.schedule[].region"

If you use any of these options you are advised to move to the new configuration structure/options as soon as possible.

For an illustration of the configuration option changes, please consult the  OVA RC7 Examples.

3. API Changes

The following API changes have occurred in this release:

  • TheStageDimensions class has been removed and replaced with a new Player display model (a number of classes) - see "Section 5: Configuring the Player Display" for further information.
  • _vastController.hasStageDimensions() has been removed and is no longer required
  • The ControlsConfig class has been removed and replaced with the new Player display model - see Section 5 below for details. As a result
  • _vastController.config.adsConfig.controlsConfig is no longer available
  • _vastController.enableNonLinearAdDisplay(DisplayProperties) has been replaced with _vastController.enableDisplayRegions(DisplayProperties)
  • Config.adsConfig.vpaidConfig.linearBarHeight has been removed - this value can be found in the new player display model
  • _vastController.disableControls has been removed and replaced with vastController.config.playerConfig.shouldDisableControlsDuringLinearAds(isVPAID)
  • _vastController.shouldShowControlsDuringLinearAds() has been removed and replaced with _vastController.config.playerConfig.shouldHideControlsOnLinearPlayback(isVPAID)
  • _vastController.getControlConfig() has been replaced with _vastController.controlEnabledStateForLinearAdType(controlName:String, isVPAID:Boolean):Boolean
  • OverlayAdDisplayEvent.adSlotKey has been removed and has been replaced with OverlayAdDisplayEvent.adSlot.key
  • OverlayAdDisplayEvent.ad has been removed and has been replaced with OverlayAdDisplayEvent.nonLinearVideoAd
  • CompanionAdDisplayEvent.ad has been removed and has been replaced with CompanionAdDisplayEvent.companionAd
  • The region constant RESERVED_FULLSCREEN_TRANSPARENT_WITH_CB_HEIGHT has become RESERVED_FULLSCREEN_TRANSPARENT_BOTTOM_MARGIN_ADJUSTED
  • The structure of the DisplayProperties class has been modified. Previously the constructor was:
public function DisplayProperties(
            displayObjectContainer:DisplayObjectContainer=null, 
            displayWidth:int=0, 
            displayHeight:int=0, 
            bottomMargin:int=0, 
            originalWidth:int=-1, 
            originalHeight:int=-1, 
            linearControlbarHeight:int=-1, 
            nonLinearControlbarHeight:int=-1, 
            displayMode:String=DISPLAY_NORMAL, 
            controlBarY:int=-1);

now the constructor is:

public function DisplayProperties(
           displayObjectContainer:DisplayObjectContainer, 
           displayWidth:int, 
           displayHeight:int, 
           displayMode:String, 
           displaySpecification:DisplaySpecification, 
           controlsVisibleAtBottom:Boolean, 
           controlsHeight:Number, 
           controlsYPos:Number);

For more information on the DisplaySpecification class, please refer to "section 4: The New Player Display Configuration Model".

4. The New OVA Player Display Configuration Model

In RC7, the way the player display is configured and programmed within the framework completely changed. The change was required to add support for the display of non-linear ads via HTML5.

The characteristics of the player display are now configured via the "player" configuration block. For example, to hard code the height of a control bar, the following configuration is now used:

{
     "player": {
            "controls": { "height": 35 }
     },
     "ads": {
            ....
     }
}

Or to set the bottom margins for the display, the following configuration can be used:

    "player": {
          "margins": {
                "withControls": 50,
                "withControlsOverride": 50,
                "withoutControls": 30,
                "withoutControlsOverride": 30
          }
    },
    "ads": {
          ...
    }
}

To hide the JW Player custom logo during linear ad playback, the following configuration can be used:

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

5. Using OVA with Google Analytics

RC7 includes dramatically improved support for the use of Google Analytics with OVA.

The following VAST/VPAID events can be tracked via Google Analytics:

  • Linear, Non-Linear and Companion Impressions
  • Ad calls - succeed, failed, timed out, deferred
  • Template loads - succeeded, failed, timed out, deferred
  • Ad slot loads - succeeded, deferred, timed out, failed
  • Linear Ad progress tracking - first quartile, midpoint, third-quartile, complete
  • Player pause, resume, mute, fullscreen during Linear ad playback
  • Linear and non-linear click throughs
  • VPAID events - ad loaded, ad started, ad stopped, ad linear change, ad expanded change, ad remaining time change, ad volume change, ad video start, ad video first quartile, ad video midpoint, ad video third quartile, ad video complete, ad user accept invitation, ad user close, ad paused, ad playing, error

5.1 Using a Custom Account

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

In the example above, a custom GA account with an id of "US-10158120-1" is used and the linear, non-linear and companion impressions are tracked to that account using the URLs specified.

5.2 Specifying Additional Tracking Parameters

It is possible to declare additional parameters to be added to the GA calls ad runtime.

The following code snippet illustrates how this can be achieved:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                        "enable": true,
                        "accountId": "UA-10158120-1",
                        "additionalParams": {
                              param1: "value1",
                              param2: "value2"
                        }

The config above results in both param1=value1 and param2=value2 being appended to all of the custom GA calls that OVA makes.

5.3 Tracking Impressions

Linear, non-linear and companion impressions can be tracked via Google Analytics.

To activate impression tracking to your GA account, use the following configuration structure:

{
     ...
     "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 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/custom/linear"
  • non-linear - "/ova/impression-counter/custom/nonLinear"
  • companion - "/ova/impression-counter/custom/companion"

A different set of tracking URLs can be specified at any time using the declaring the required URL against the appropriate configuration option. For example, if a path of /ova/impression-counter/ova-test/XXX is to be used, you can configure this as follows:

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

For linear ads, these parameters include:

  • ova_slot_id - the unique ID for this ad slot
  • ova_slot_type - linear, linear interactive
  • ova_slot_position - pre, mid or post-roll
  • ova_ad_id - the ad ID taken from the VAST response
  • ova_ad_system - the ad system take from the VAST response
  • ova_ad_title - the ad title taken from the VAST response
  • ova_ad_description - the ad description taken from the VAST response
  • ova_media_url - the url of the media displayed
  • ova_media_bitrate - the bitrate of the media displayed
  • ova_ad_provider - the ad provider delivering the ad tag
  • Any additional tracking parameters configured via OVA

For non-linear ads, the parameters added to the tracking URL include:

  • ova_slot_id - the unique ID for this ad slot
  • ova_slot_type - linear, linear interactive
  • ova_slot_position - the region used to display the overlay
  • ova_slot_start_time - the start time for this overlay
  • ova_slot_duration - the display duration of the overlay
  • ova_ad_id - the ad ID taken from the VAST response
  • ova_ad_system - the ad system take from the VAST response
  • ova_ad_title - the ad title taken from the VAST response
  • ova_ad_description - the ad description taken from the VAST response
  • ova_creative_type - the creative type of the media being displayed
  • ova_creative_width - the width of the creative
  • ova_creative_height - the height of the creative
  • ova_ad_provider - the ad provider delivering the ad tag
  • Any additional tracking parameters configured via OVA

For companion ads, the following parameters are added to the tracking URL:

  • ova_slot_id - the unique ID for this ad slot
  • ova_companion_width - the width of the companion
  • ova_companion_height - the height of the companion
  • ova_companion_type - the companion media type
  • ova_ad_id - the ad ID taken from the VAST response
  • ova_ad_system - the ad system take from the VAST response
  • ova_ad_title - the ad title taken from the VAST response
  • ova_ad_description - the ad description taken from the VAST response
  • ova_ad_provider - the ad provider delivering the ad tag
  • Any additional tracking parameters configured via OVA

5.4 Tracking Ad Calls

Ad calls may be tracked via Google Analytics. If an ad call returns a VAST wrapper, the subsequent ad call will be tracked with a parameter identifying the ad call as wrapped.

A number of ad call states may be tracked:

  • Fired - logged when the ad call is fired off to the ad server
  • Complete - recorded when the ad call successfully completes
  • Timed out - logged if the ad call times out
  • Error - logged if an error is recorded as the ad call is made
  • Failed Over - will be tracked if the ad call fails over because no ads are returned
  • Deferred - logged if the ad call is deferred because the ad slot is "load on demand"

By default, the following URL structure is applied across these states:

  • Fired - /ova/ad-calls/custom/fired
  • Complete - /ova/ad-calls/custom/complete
  • Timed out - /ova/ad-calls/custom/timed-out
  • Error - /ova/ad-calls/custom/error
  • Failed Over - /ova/ad-calls/custom/failed over
  • Deferred - /ova/ad-calls/custom/deferred

The following code snippet illustrates how to enable ad call tracking using the custom GA account setting:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                        "accountId": "UA-10158122-2",
                        "adCalls": {
                              "enable": true
                        }
                 }
          }
     },
     "ads": {
           ....
     }
}

The default URLs for each ad call state can be overridden via the "adCalls" config option as follows:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                        "accountId": "UA-10158122-2",
                        "adCalls": {
                              "enable": true,
                              "fired": "/ova/ad-calls/action=fired",
                              "complete": "/ova/ad-calls/action=complete",
                              "timeout": "/ova/ad-calls/action=timed-out",
                              "error": "/ova/ad-calls/action=error",
                              "failover": "/ova/ad-calls/action=fired",
                              "deferred": "/ova/ad-calls/action=fired"
                        }
                 }
          }
     },
     "ads": {
           ....
     }
}

Tracking of ad calls is turned off within OVA by default.

A number of additional parameters are recorded with each ad call tracking URL. These include:

  • ova_slot_id - the unique ID for this ad slot
  • ova_slot_position - the region used to display the overlay
  • ova_slot_start_time - overlays only - the start time for the overlay
  • ova_slot_duration - overlays only - the display duration of the overlay
  • ova_ad_server_type - the ad server type configured in OVA for the ad call
  • ova_ad_tag - the ad tag used to make the ad call to get this ad
  • ova_wrapped_ad_tag - true if the ad tag has been specified in a VAST wrapper
  • Any additional tracking parameters configured via OVA

5.5. Tracking Template Loads

It is possible to track the load status of VAST templates as they result from ad calls made by OVA.

The following template load events can be tracked:

  • loaded - successfully loaded after an ad call
  • error - an error resulted during the ad call
  • deferred - deferred because there are on-demand ad slots in the schedule
  • timeout - the ad call timed out

The following code snippet illustrates how to enable template tracking:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                        "accountId": "UA-10158122-2",
                        "templates": {
                              "enable": true,
                              "loaded": "/ova-example/templates/loaded",
                              "error": "/ova-example/templates/error",
                              "timeout": "/ova-example/templates/timeout",
                              "deferred": "/ova-example/templates/deferred"
                        }
	         }
          }
     },
     "ads": {
           ....
     }
}

Each GA call has the following fields added to the URL:

  • ova_ad_count - the number of ads recorded in the parsed template
  • Any additional tracking parameters configured via OVA

5.6 Tracking Ad Slot Loads

The status of on-demand ad slot loading can be tracked via Google Analytics.

The following on-demand ad slot load events can be tracked:

  • loaded - successfully loaded after an ad call
  • error - an error resulted during the ad call
  • deferred - deferred because there are on-demand ad slots in the schedule
  • timeout - the ad call timed out

The following code snippet illustrates how to enable template tracking:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                        "accountId": "UA-10158122-2",
                        "templates": {
                              "enable": true,
                              "loaded": "/ova-example/adslot/loaded",
                              "error": "/ova-example/adslot/error",
                              "timeout": "/ova-example/adslot/timeout",
                              "deferred": "/ova-example/adslot/deferred"
                        }
                 }
          }
     },
     "ads": {
           ....
     }
}

Each GA call has the following fields added to the URL:

  • ova_slot_id - the unique ID for this ad slot
  • ova_slot_position - the region used to display the overlay
  • ova_slot_start_time - overlays only - the start time for the overlay
  • ova_slot_duration - overlays only - the display duration of the overlay
  • ova_ad_server_type - the ad server type configured in OVA for the ad call
  • ova_ad_provider - the ad provider delivering the ad tag
  • ova_wrapped_ad_tag - true if the ad tag has been specified in a VAST wrapper
  • Any additional tracking parameters configured via OVA

5.7 Tracking Playback Events

As OVA ads are played, a number of events can be tracked using Google Analytics. These events include:

  • Linear Ad progress tracking - first quartile, midpoint, third-quartile, complete
  • Player pause, resume, mute, fullscreen during Linear ad playback
  • Linear and non-linear click throughs

5.7.1 Tracking Linear Ad Progress Events

The following non-interactive linear ad playback progress events can be tracked via Google Analytics:

  • first quartile complete
  • midpoint complete
  • third-quartile complete
  • playback complete
  • player events such as going fullscreen, pause, resume, mute, close etc.

The following code snippet illustrates how to enable these events to be tracked:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                       "accountId": "UA-10158122-2",
                       "progress": {
                            "enable": true,
                            "start": "/ova-example/progress/start",
                            "firstQuartile": "/ova-example/progress/firstQuartile",
                            "midpoint": "/ova-example/progress/midpoint",
                            "thirdQuartile": "/ova-example/progress/thirdQuartile",
                            "complete": "/ova-example/progress/complete",
                            "pause": "/ova-example/progress/pause",
                            "resume": "/ova-example/progress/resume",
                            "fullscreen": "/ova-example/progress/fullscreen",
                            "mute": "/ova-example/progress/mute",
                            "unmute": "/ova-example/progress/unmute",
                            "expand": "/ova-example/progress/expand",
                            "collapse": "/ova-example/progress/collapse",
                            "acceptInvitation": "/ova-example/progress/acceptInvitation",
                            "close": "/ova-example/progress/close"
                       }
                 }
          }
     },
     "ads": {
           ....
     }
}

Each GA call has the following fields added to the URL:

  • ova_slot_id - the unique ID for this ad slot
  • ova_slot_type - linear, linear interactive
  • ova_slot_position - pre, mid or post-roll
  • ova_ad_id - the ad ID taken from the VAST response
  • ova_ad_system - the ad system take from the VAST response
  • ova_ad_title - the ad title taken from the VAST response
  • ova_ad_description - the ad description taken from the VAST response
  • ova_media_url - the url of the media displayed
  • ova_media_bitrate - the bitrate of the media displayed
  • ova_ad_provider - the ad provider delivering the ad tag
  • Any additional tracking parameters configured via OVA

5.7.2 Tracking Click Events

Ad click through events can be tracked via Google Analytics.

The following code snippet illustrates how to enable this:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                       "accountId": "UA-10158122-2",
                       "clicks": {
                            "enable": true,
                            "linear": "/ova-example/clicks/linear",
                            "nonLinear": "/ova-example/clicks/linear", 
                            "VPAID": "/ova-example/clicks/linear"
                       }
                 }
          }
     },
     "ads": {
           ....
     }
}

For linear ads, these parameters include:

  • ova_slot_id - the unique ID for this ad slot
  • ova_slot_type - linear, linear interactive
  • ova_slot_position - pre, mid or post-roll
  • ova_ad_id - the ad ID taken from the VAST response
  • ova_ad_system - the ad system take from the VAST response
  • ova_ad_title - the ad title taken from the VAST response
  • ova_ad_description - the ad description taken from the VAST response
  • ova_media_url - the url of the media displayed
  • ova_media_bitrate - the bitrate of the media displayed
  • ova_ad_provider - the ad provider delivering the ad tag
  • Any additional tracking parameters configured via OVA

For non-linear ads, the parameters added to the tracking URL include:

  • ova_slot_id - the unique ID for this ad slot
  • ova_slot_type - linear, linear interactive
  • ova_slot_position - the region used to display the overlay
  • ova_slot_start_time - the start time for this overlay
  • ova_slot_duration - the display duration of the overlay
  • ova_ad_id - the ad ID taken from the VAST response
  • ova_ad_system - the ad system take from the VAST response
  • ova_ad_title - the ad title taken from the VAST response
  • ova_ad_description - the ad description taken from the VAST response
  • ova_creative_type - the creative type of the media being displayed
  • ova_creative_width - the width of the creative
  • ova_creative_height - the height of the creative
  • ova_ad_provider - the ad provider delivering the ad tag
  • Any additional tracking parameters configured via OVA

For companion ads, the following parameters are added to the tracking URL:

  • ova_slot_id - the unique ID for this ad slot
  • ova_companion_width - the width of the companion
  • ova_companion_height - the height of the companion
  • ova_companion_type - the companion media type
  • ova_ad_id - the ad ID taken from the VAST response
  • ova_ad_system - the ad system take from the VAST response
  • ova_ad_title - the ad title taken from the VAST response
  • ova_ad_description - the ad description taken from the VAST response
  • ova_ad_provider - the ad provider delivering the ad tag
  • Any additional tracking parameters configured via OVA

5.7.3 Tracking VPAID Events

The full set of VPAID events can be tracked via Google Analytics. These events include:

  • loaded, started, stopped
  • linear changed
  • expanded changed
  • remaining time change
  • volume changed
  • video started, video first quartile complete, video midpoint complete, video third quartile complete, video complete
  • user accepted invitation
  • user closed the ad
  • playback paused, resumed
  • error conditions

The following code snippet illustrates how to setup tracking for VPAID linear and non-linear (overlay) ads:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                       "accountId": "UA-10158122-2",
                       "vpaid": {
                            "enable": true,
                            "loaded": "/ova-example/vpaid/loaded",
                            "started": "/ova-example/vpaid/started",
                            "stopped": "/ova-example/vpaid/stopped",
                            "linearChange": "/ova-example/vpaid/linearChange",
                            "expandedChange": "/ova-example/vpaid/expandedChange",
                            "remainingTimeChange": "/ova-example/vpaid/remainingTime",
                            "volumeChange": "/ova-example/vpaid/volumeChange",
                            "videoStart": "/ova-example/vpaid/videoStart",
                            "videoFirstQuartile": "/ova-example/vpaid/videoFirstQuartile",
                            "videoMidpoint": "/ova-example/vpaid/videoMidpoint",
                            "videoThirdQuartile": "/ova-example/vpaid/videoThirdQuartile",
                            "videoComplete": "/ova-example/vpaid/videoComplete",
                            "userAcceptInvitation": "/ova-example/vpaid/userAccept",
                            "userClose": "/ova-example/vpaid/userClose",
                            "paused": "/ova-example/vpaid/paused",
                            "playing": "/ova-example/vpaid/playing",
                            "error": "/ova-example/vpaid/error"
                       }
                 }
          }
     },
     "ads": {
           ....
     }
}

For each VPAID tracking event fired, the following attributes are appended to the GA tracking URL:

  • ova_ad_id - the ad ID taken from the VAST response
  • ova_ad_system - the ad system take from the VAST response
  • ova_ad_title - the ad title taken from the VAST response
  • ova_ad_description - the ad description taken from the VAST response
  • ova_creative_type - the creative type of the media being displayed
  • ova_creative_width - the width of the creative
  • ova_creative_height - the height of the creative

5.8 Turning on Ad Tag Information

By default, OVA will not add the "ad tag" used to the tracking URLs. When the ad tag is added, it has the consequence of potentially creating a new tracking URL for each tracking item as ad tags typically have unique items within them such as cache-busting random number.

You can turn on "ad tag tracking" so that the ad tag is added to each Tracking URL. To do so, apply the following config:

{
     ...
     "analytics": {
          "google": {
                 "custom": {
                       "accountId": "UA-xxxxxx-x",
                       "trackAdTags": true,
                       ....
}

5.9 The OVA Master Account

OVA uses Google Analytics to collect cursory operational data as it runs to help with support, testing and backward compatibility decisions made during the ongoing development of the OVA for Flowplayer and JW5 plugins. This data is sent to a master OVA GA account "UA-4011032-6".

6. Displaying Non-Linear Ads with HTML5

OVA can be used to deliver non-linear video advertising. Non-linear video ads are banner style ads that appear either within or around the player display. While similar in appearance, non-linear ads should not be confused with Companion Ads that appear in conjunction with either Linear or Non-Linear ads. Unlike Companion Ads, Non-linear ad may be VPAID ads that support interaction with the underlying player.

Non-linear video ads that appear within the player display are known as Overlays. Those that appear around the player display are termed Non-Overlay.

The IAB has defined a "minimum" set of standard sizes for Non-Linear ad formats - 300x50 and 450x50 for overlays and 300x50, 300x60, 234x60 and 400x20 for non-overlays. Publishers may offer more formats than these, however overlays should not exceed 1/5 of the player height. For more detailed guidance on non-linear ad formats, please refer to the IAB Video Ad Format Standards guide available on the IAB website.

6.1. Examples

HTML5 examples can be found -  OVA for JW5,  OVA for Flowplayer.

6.2. Configuring Non-Linear Ad Slots

Non-linear ads are configured within an OVA ad schedule as illustrated by the following code snippet:

{
    ...
    "ads": {
       "schedule": [
            {
                 "startTime": "00:00:05",
                 "duration": "recommended:10",
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            },
            {
                 "startTime": "00:00:45",
                 "duration": "recommended:10",
                 "tag": "http://my-ad-server.com/ad-tag2.xml"
            }
        ]
    },
    ...
}

In this example, 2 non-linear ads are served - the first after 5 seconds into the show clip for a duration of 10 seconds, the second after 45 seconds into the show clip for 10 seconds. Each non-linear ad is obtained using separate ad tags.

Non-linear ad slots always have a "startTime" specified. OVA uses this to identify the ad slot as "non-linear".

An optional "duration" value may be specified to detail how long an overlay should be shown (in seconds). Ad slots without a "duration" specified will run indefinately. VAST 2 supports the notion of a "minSuggestedDuration" attribute on a non-linear creative. To instruct OVA to use the VAST "minSuggestedDuration" value, the Ad Slot definition should take the form of "recommended:X" where X is the duration to apply if no "minSuggestedDuration" is provided in the VAST response

Each ad slot may be displayed using either the default Flash display mode or HTML5, or both concurrently. A number of additional configuration options (such as "region" and sizing information) may be specified with non-linear ad slots depending upon the display mode being used.

OVA will only display non-linear ads if it can:

  • Successfully find a matching non-linear creative type in the VAST response based on the configured OVA Display Rules and
  • Apply a non-linear Content Template to derive the markup/code to form the ad creative and
  • Successfully display the ad creative markup/code using the Display Mode declared in the OVA configuration

6.3. Selection Rules

A VAST response will often include a number of non-linear ad creatives - different sizes and potentially creative types.

OVA implements a number of rules to govern how it selects the most appropriate creative to display for a given ad slot. These rules include:

  • Matching based on size
  • Matching based on ad type
  • Matching based on size and ad type
  • Always matching

6.3.1 Declaring Selection Rules

By default, OVA will match as follows:

  • If sizing information is specified in the ad slot, this takes priority and an exact match based on size is required, unless the "alwaysMatch" option is specified
  • If no sizing information is provided, the player size will be used for guidance and the best fit will be matched
  • If ad types are specified for matching, then those will be used to reduce the number of creatives that can be matched to the corresponding set. If size information is provided in the ad slot along with permitted ad types, then the size rules will be applied to the matched set of creatives.
  • If "alwaysMatch" is specified, then a match will always be made, regardless of the selection rules specified. The match will always be the first creative in the set available in the VAST response.
  • The default matching rules can be overridden with custom settings. Matching rules can be specified at either the general level or within a specific ad slot.
6.3.1.1 Specifying Selection Rules at the General Level

The following code snippet illustrates how to declare matching rules at a general level to ensure that these rules are applied across all non-linear ad slots. General rules are declared within an "ads.overlays" config block:

{
    ...
    "ads": {
       "overlays": {
             "width": 400,
             "height": 50
       },
       "schedule": [
            {
                 "startTime": "00:00:05",
                 "duration": "recommended:10",
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            },
            {
                 "startTime": "00:00:45",
                 "duration": "recommended:10",
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            }
        ]
    },
    ...
}
6.3.1.2 Specifying Selection Rules at the Ad Slot Level

Specific selection rules to apply per ad slot can be declared at the ad slot level as follows.

{
    ...
    "ads": {
       "schedule": [
            {
                 "startTime": "00:00:05",
                 "duration": "recommended:10",
                 "acceptedAdTypes": [ "image" ],
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            },
            {
                 "startTime": "00:00:45",
                 "duration": "recommended:10",
                 "acceptedAdTypes": [ "iframe" ],
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            }
        ]
    },
    ...
}

The code snippet above illustrates how to limit creative selection to "image" ad types for the first ad slot and "iframe" ad types for the second ad slot.

6.3.2 Selection by Size

If an ad slot has a width and height specified, those values are used to match to VAST creative.

{
    ...
    "ads": {
       "schedule": [
            {
                 "startTime": "00:00:05",
                 "duration": "recommended:10",
                 "width": 400,
                 "height": 50,
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            }
        ]
    },
    ...
}

For example, an ad slot declared as illustrated above will result in OVA searching the VAST response for a creative ad unit that is 400 width by 50 high.

6.3.3 Selection by Ad Type

Alternatively an ad slot can declare a set of ad types that are applicable.

{
    ...
    "ads": {
       "schedule": [
            {
                 "startTime": "00:00:05",
                 "duration": "recommended:10",
                 "acceptedAdTypes": [ "image" ],
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            }
        ]
    },
    ...
}

When a set of mime types are declared, only those creatives matching the ad type set will be available for selection. For example. the code snippet above ensures that only non-linear image ads are displayed.

The list of possible ad types includes:

  • image
  • html
  • text
  • swf
  • vpaid
  • iframe
  • javascript

6.3.4 Selection by Size and Ad Type

It is possible to limit creative selection based on both ad type and size. The list of possible creatives that can match will be restricted first by ad type, and then by size.

The following code snippet illustrates how to specify a size and type selection criteria for an ad slot. In this example, only 400x50 image based non-linear ads will be displayed:

{
    ...
    "ads": {
       "schedule": [
            {
                 "startTime": "00:00:05",
                 "duration": "recommended:10",
                 "width": 400,
                 "height": 50,
                 "acceptedAdTypes": [ "image" ],
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            }
        ]
    },
    ...
}
6.3.5 Always Match

While matching rules are great in theory, generally an ad should always be selected for display, particularly if it is a creative type that can be scaled such as SWF non-linear ads.

The "alwaysMatch" option exists to ensure that if all else fails, a creative will be selected from the VAST response. The creative matched will always be the first one in the non-linear ad block.

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

{
    ...
    "ads": {
       "schedule": [
            {
                 "startTime": "00:00:05",
                 "duration": "recommended:10",
                 "width": 400,
                 "height": 50,
                 "acceptedAdTypes": [ "image" ],
                 "alwaysMatch": true,
                 "tag": "http://my-ad-server.com/ad-tag1.xml"
            }
        ]
    },
    ...
}

6.4 Creative Templates

Non-linear ads can be of different creative types:

  • Image
  • Javascript
  • VPAID SWF
  • Non-VPAID SWF
  • HTML
  • Text
  • iFrame

A VAST response that specifies a non-linear creative can declare that creative using either a URL or an embedded markup (HTML or Javascript) code snippet.

OVA forms the final code segment used to display a non-linear creative using a Creative Template that governs how to read the VAST response and transform it accordingly into the required HTML5 or Flash display instructions.

It is possible to override the default template for each overlay type to customise the code used to display non-linear ads. For example, the following code snippet illustrates how to override the template applied for HTML overlay types:

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

6.5. Non-Linear Display Modes

OVA supports two different modes of operation to display non-linear ads:

  • via Flash (the default mode)
  • via HTML5

Flash display mode uses the facilities of AS3 to obtain and display the non-linear ad on the player stage. Only overlays can be displayed using Flash mode and the type of overlay creative that can be displayed is restricted to:

  • Image
  • Restricted HTML
  • Text
  • Non-VPAID Flash
  • VPAID SWF

Alternatively, non-linear ads displayed in HTML5 mode can be placed as either overlay or non-overlays and a broader set of non-linear creative types are supported by HTML5 display mode:

  • Image
  • Full HTML
  • Text
  • Non-VPAID Flash
  • iFrame
  • Javascript
  • VPAID non-linear ads can only be displayed using Flash display mode. This means that it is not possible to display non-linear, non-overlay VPAID ads.

6.5.1 Overlays and Flash Mode

By default, OVA attempts to display non-linear ads in Flash mode. In Flash mode, only overlays can be displayed. When overlays are displayed in Flash mode, OVA attempts to display the creative using the in-built features of Flash. Generally this means placing the creative on a Sprite based region on the player, however for HTML and Text non-linear ad types, the ad content is displayed using the restricted HTML facilities of the TextField in AS3. This means that a subset of HTML is supported. For details on the HTML tags that Flash supports, please consult the Adobe TextField reference guide.

OVA uses the "region" configuration within an ad slot declaration to identify where on the non-linear ad is to be placed on the player display.

Regions can either be:

  • Manually declared via the "regions" config block
  • Automatically created by OVA based on a range of keywords
6.5.1.1 Using Automatic Overlay Regions

The sizing of automatic regions is determined at runtime based on the sizing information provided in the VAST response.

The following configuration snippet illustrates how to declare a requirement for overlay advertising that is to be displayed using "automatic" regions.

...
   "ads": {
       "schedule": [
            {
                 "zone": "28",
                 "startTime": "00:00:05",
                 "position": "auto:center",
                 "duration": "recommended:10"
            }
        ]
   }
...

A position that has "auto" specified as the position name instructs OVA to create a region on the screen that matches the dimensions of the overlay ad specified in the VAST response. A "placement" identifier must alway be specified along with the "auto" keyword.

Valid placements are:

  • auto:top - centered at the top of the screen
  • auto:bottom - centered at the bottom of the screen
  • auto:center - placed in the center of the screen
  • auto:left - placed to the left center of the screen
  • auto:right - placed to the right center of the screen
6.5.1.2 Manually Specifying Overlay Regions

In addition to automatic region creation, it is possible to specify a "region" that is to be used to display an overlay manually by specifying either:

The name of a pre-defined OVA region, or The name of a custom region declared within the OVA configuration block OVA has 14 general purpose overlays declared. These range from invisible full screen regions, to top, middle, bottom, left and right definitions that are either invisible, opaque or black.

The following code snippet illustrates how to tie an overlay to a pre-defined region - in this case the region is a transparent region, 450x50 pixels placed at the bottom center of the screen (labeled reserved-bottom-w450px-h50px-transparent).

...
   "ads": {
       "servers": [
            {
                ...
            }
       ],
       "showOverlayCloseButton": false,
       "schedule": [
            {
                 "zone": "28",
                 "startTime": "00:00:05",
                 "region": "reserved-bottom-w450px-h50px-transparent",
                 "duration": "recommended:10"
            }
        ]
   }
...

Custom regions can be declared within the OVA configuration block. The following configuration snippet illustrates how a custom region with an ID of "top-center" is declared. It has a black background, no padding and a border 15 pixels wide. The dimensions of the overlay are 450 x 50 pixels.

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

6.5.2 Non-Linear Ads and HTML5 Mode

Non-linear ads can be displayed by OVA using the OVA HTML5 library "ova-jquery.js". The "ova-jquery.js" file can be found in the OVA for JW5 or OVA for Flowplayer distribution pages (in the /dist/js directory), or it can be downloaded from the OVA Developer Site here or within subversion here.

HTML5 display mode requires the "ova-jquery.js" library to be included on the web page before the player is setup.

Once the library has been included, to enable HTML5 display mode, use the "html5" regions option at either general or ad slot specific levels. The following code snippet illustrates how to enable HTML5 display mode for all ad slots:

...
   "ads": {
       "overlays": {
           "regions": {
               "html5": true
           }
       },
       "schedule: [
           {
               ...
           }
       ]
   }
...

The config above results in HTML5 display mode being enabled to run concurrently with Flash display mode. To turn off Flash display mode, and enable HTML5, use the following config:

...
   "ads": {
       "overlays": {
           "regions": {
               "html5": true,
               "flash": false
           }
       },
       "schedule: [
           {
               ...
           }
       ]
   }
...

The following code snippet illustrates how to enable HTML5 display mode for a specific ad slot. In this example, the first ad slot is displayed using HTML5, while the second ad slot is displayed using the default Flash display mode. The first non-linear ad will be placed into a DIV region with an ID of "bottom" while the second ad slot will be positioned in the "auto:bottom" region on the player display.

...
   "ads": {
       "schedule: [
           {
               "startTime": "00:00:05",
               "duration": 10,
               "tag": "http://my-ad-server.com/ad-tag.xml",
               "regions": {
    	           "html5": true,
        	       "flash": false
               }
           },
           {
               "startTime": "00:00:45",
               "duration": 10,
               "tag": "http://my-ad-server.com/ad-tag.xml"
           }
       ]
   }
...
6.5.2.1 Placing Non-Linear ads on the page

HTML5 displayed non-linear ads use jQuery and DIV regions to place the non-linear ad on the web page.

By default, OVA will attempt to place the non-linear ad in a DIV region with an ID "bottom".

Typically, the HTML markup for a DIV region will appear in the web page as follows:

<div>
	<div>
	    <div id="container" style="width:450px;height:300px;">
	        Loading the player ...
	    </div>
	</div>
	<div id="bottom" style="background:#FF6600;width:450px;height:50px;">
	   <!--- A 450x50 non-linear ad will appear in here -->
	</div>
</div>

This markup results in a DIV region that is immediately visible the moment the page is loaded. As such, it is suitable for a non-linear, non-overlay ad. Non-linear overlays require a DIV region that is hidden by default and is then shown/hidden by OVA as the non-linear overlay creative is displayed by OVA.

6.5.2.2 Turning on HTML5 Non-Linear Overlay Mode

OVA will assume HTML5 displayed non-linear ads are "non-overlay" in nature. This means that before the non-linear ad is displayed, the content of the DIV region will first be captured and then restored once the non-linear ad is complete.

Non-linear overlays displayed using HTML5 result in the DIV region being shown at the start of the ad and then hidden once again once the ad duration is complete.

To display HTML5 non-linear overlays, the DIV region created on the page must have the CSS property "visibility:hidden;" set by default. For example, the following HTML code snippet illustrates how to declare a HTML DIV region that is 400x50, is positioned at the bottom of the player above the controls and is hidden by default:

<div style="position:relative;width:450px;height:300px;">
  <div id="container" style="top:0px;left:0px;width:450px;height:300px;position:absolute;">
     Loading the player ...
  </div>
  <div id="bottom" style="top:223px;left:0px;width:450px;height:50px;background:transparent;position:absolute;visibility:hidden;">
	 <!--- A 450x50 overlay ad will appear in here -->
  </div>
</div>

When OVA shows the non-linear overlay, the CSS "visibility" property will be changed to "visible" and then back to "hidden" when the overlay is to be closed.

Once the DIV region has been specified in the web page, OVA needs to be instructed via the config to display non-linear ads as overlays. This is accomplished via the "overlays.overlay" config option as follows:

...
   "ads": {
       "overlays": {
           "overlay": { "html5": true },
           "regions": {
               "html5": true,
               "flash": false
           }
       },
       "schedule: [
           {
               "startTime": "00:00:05",
               "duration": 10,
               "tag": "http://my-ad-server.com/ad-tag.xml",
           }
       ]
   }
...

It is also possible to instruct OVA to display an ad slot specifically as an "overlay" by specifying "overlay": true at the ad slot level as follows:

...
   "ads": {
       "schedule: [
           {
               "startTime": "00:00:05",
               "duration": 10,
               "overlay": true,
               "regions": {
                   "html5": true,
                   "flash": false
               },
               "tag": "http://my-ad-server.com/ad-tag.xml",
           }
       ]
   }
...

6.5.3 Preferred Display Mode

By default, OVA will attempt to display non-linear ads using Flash mode. This means that non-linear overlays centered at the bottom of the player display are the default for OVA.

7. Scaling Non-Linear Ads

Being written