OpenX: OVA Configuration Guide

This guide walks through how to deliver IAB compliant Video Advertising using Open Video Ads with the OpenX ad server.

OpenX is one of the leading Open Source ad servers available on the market.

OpenX supports the IAB VAST 1.0 standard.

1. Recommended Reading

The following reading is recommended to accompany this tutorial:

The OVA Configuration Guide
Configuring OVA to work with a VAST Ad Server
OpenX User Guide
The OpenX OVA for Flowplayer and OVA for JW 5x, 4x examples

2. Operational Requirements

To deliver video advertising with OVA and OpenX, the following must be available:

OpenX 2.8.4 or later - either in hosted or self hosted (community download) form
Open Video Ads:
- Flowplayer - use the OVA for Flowplayer plugin
- JW Player 4.x - use OVA for JW 4.x
- JW Player 5.x - use OVA for JW 5.x
- Flash/AS3 Custom Player - Use OVA for AS3

3. Configuring OpenX to Deliver Video Advertising

To deliver video advertising from OpenX, one or more video advertising "banners" need to be setup within the OpenX instance. A video banner can either be a linear (pre, mid or post-roll stream) or an overlay (non-linear ad). Both linear and non-linear ads can have a companion attached.

OpenX provide documentation on their site to guide you through the video banner setup process. You can find that documentation here.

OpenX also provides a reporting console where the performance of the video ads can be assessed. For more information on OpenX video ad reporting, refer to the OpenX Video Statistics documentation on the OpenX website.

4. Configuring OVA to Request and Playback OpenX Video Advertising

Assuming that OpenX is ready to serve one or more video ads, OVA can now be configured to request and playback the ads in question.

4.1 Security and the "crossdomain.xml" File

If you are serving your ads from a different domain name than the flash player, you need to install a crossdomain.xml file in the docroot on your openX ad server to allow flash to communicate to it.

Please take care installing this file. The example below allows "all" domains to talk to your server within Flash - you may want to restrict this.

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
<allow-access-from domain="*"/>
</cross-domain-policy>

If you configure OVA to play an ad and you don't see the ad appear in the player, there is a simple way to determine if the problem relates to the "crossdomain.xml" file. Open a "Firebug" console - if there is a "crossdomain.xml issue", you will a security violation message as follows:

18:41:26 GMT+0100: Loading VAST data from OAS - request is http://ads.forbes.com/
      RealMedia/ads/adstream_sx.ads/investopedia.com/video/194022537@x5?
18:41:26 GMT+0100: OVA initialisation complete.
18:41:26 GMT+0100: VideoAdServingTemplate: HTTP ERROR: [SecurityErrorEvent type="securityError" 
      bubbles=false cancelable=false eventPhase=2 text="Error #2048"]

4.2 Making an OpenX Ad Request

Before you can configure OVA to start calling your OpenX instance, you must first determine the VAST ad call address for your OpenX instance.

OpenX provide an FAQ to help you determine this. Read this page and follow the steps outlined to identify your OpenX VAST address.

A typical OpenX API address takes the following form (replace <host> with your OpenX host address - for example: d1.openx.org for the hosted instance, or openx.openvideoads.org/openx for the OVA demonstration instance):

<host>/www/delivery/fc.php

Following this convention, a resulting OpenX ad call appears as follows (you can see the VAST response returned from that call here):

http://openx.openvideoads.org/openx/www/delivery/fc.php?
     script=bannerTypeHtml:vastInlineBannerTypeHtml:
     vastInlineHtml&zones=pre-roll0-0%3D5&nz=1&
     source=&r=R0.0644801901653409&block=1&format=vast&charset=UTF-8

4.3 Configuring the OpenX Ad Server Instance

OVA provides advanced support for dynamic OpenX ad calls "out-of-the-box". This means that OVA provides a specific ad server "type" for OpenX and the ad call URLs are constructed on the fly using the information provided in the "servers" and "schedule" elements of the OVA configuration.

The following configuration illustrates a relatively complex OVA configuration using OpenX:

...
  "ads": {
      "servers": [
          {
             "type": "OpenX",
             "apiAddress": "http://openx.openvideoads.org/
                            openx/www/delivery/fc.php",
             "allowAdRepetition": true
             "customProperties": {
                  "target": [ "category=food", "gender=male" ]
             }
          }
      ],
      "schedule": [
          {
             "zone": "5",
             "position": "pre-roll"
          }
      ]
  },
...

In this example a call will be made to the OpenX instance addressable via "openx.openvideoads.org/openx". By default, the VAST API on an OpenX instance can be found on "www.delivery/fc.php".

A request is made for a pre-roll on zone "5" and an overlay on zone "12".

Targeted matching criteria is provided - ads are to match the flags - category=food and gender=male.

Ads are allowed to be repeated (allowAdRepetition: true)

4.4 Constructing the Request to OpenX

A VAST request to an ad server will vary according to the ad server brand. Each ad server supported by the OVA framework has a "default ad server call template" from which the final ad request is formed.

4.4.1 Using the OpenX Default Ad Call Template

Typically an OVA configuration entrt for an OpenX call is quite straight forward. In most cases, the only configuration parameters that need to be defined are the "type" (OpenX) and the "apiAddress" (the address of the OpenX server).

These parameters are applied to the default ad call template for OpenX that is defined as follows:

__api-address__?
    script=__script__&
    zones=__zones__&
    nz=__nz__&
    source=__source__&
    r=__r__&
    block=__block__&
    format=__format__&
    charset=__charset__&
    __target__

The default properties defined for this template are as follows:

{
   "script": "bannerTypeHtml:vastInlineBannerTypeHtml:vastInlineHtml",
   "nz": "1",
   "source": "",
   "r": "__random-number__",
   "block": "__allow-duplicates-as-binary__",
   "format": "vast",
   "charset": "UTF-8"
}

The default settings for the template can be overridden at any time using the OVA ad server "customProperties" configuration parameter.

With these settings and the settings provided in the OVA configuration, a standard call to OpenX is formed:

http://openx.openvideoads.com/openx/www/delivery/fc.php
    ?script=bannerTypeHtml:vastInlineBannerTypeHtml:vastInlineHtml
    &zones=pre-roll0-0%3D5%7Cbottom1-0%3D12&nz=1
    &source=
    &r=3189404.425211251
    &block=1
    &format=vast
    &charset=UTF_8
    &key1=value1...&keyN=valueN

There are several key parameters in that call:

"zones" - identifies the number and type of ads requested (e.g. linear, non-linear)
"block" - identifies whether or not ads can be repeated in the resulting set. By default repeats are not allowed - block=1 is the default setting
"key1=value1...&keyN=valueN" - identifies any specific key/value pair matching criteria to be used by OpenX to identify the ads to serve

The "zones" parameter is the more complex of the parameters. It has to effectively identify:

The number of ads requested
The type of each ad requested
A unique identifier for each ad requested

In our example the "zones" parameter value is zones=pre-roll0-0%3D5%7Cbottom1-0%3D12. Breaking this example down into it's parts:

There are two ads to be identified
The first ad is of OpenX zone type "5" (as defined by our first Ad Slot)
The second ad is of OpenX zone type "12" (as defined by our second Ad Slot)
The first ad has a unique identifier "pre-roll0-0"
The second ad has a unique identifier "bottom1-0"

While the unique identifies for each ad zone are irrelevant for the OpenX server, they are very important for the internal processing algorithms of the OVA framework because multiple ads are being requested in a single call, the framework needs to be able to uniquely identify which ad maps back to which Ad Slot when the VAST response from the Ad Server is parsed by the framework. When the framework makes a request to an ad server, it generates a unique identifier for each ad slot and requires that the identifier is passed back in the VAST response unchanged so that this mapping can be completed. Below is a cut-down example VAST response for our OpenX ad call - you can see how the unique identifiers are provided in the response:

<VideoAdServingTemplate>
    <Ad id="pre-roll0-0">        
        <InLine>            
            <AdSystem>openx</AdSystem>                
            <AdTitle>
            </AdTitle> 
              .....             
         </InLine>
     </Ad>
    <Ad id="bottom1-0">        
         <InLine>            
             <AdSystem>openx</AdSystem>                
             <AdTitle>                    
             </AdTitle>       
              .....             
        </InLine>
    </Ad>
</VideoAdServingTemplate>

It is possible to override any of the pre-defined settings for the default OpenX ad call using the "customProperties" configuration parameter.

The following configuration snippet illustrates how to achieve this:

...
  "ads": {
      "servers": [
          {
             "type": "OpenX",
             "apiAddress": "http://openx.openvideoads.org/
                            openx/www/delivery/fc.php",
             "allowAdRepetition": true
             "customProperties": {
                  "script": "new-value1",
                  "nz": "new-value2",
                  "source": "new-value3",
                  "format": "new-value4"
             }
          }
      ],
      "schedule": [
          {
             "zone": "5",
             "position": "pre-roll"
          }
      ]
  },
...

4.4.2 Overriding the Default Ad Call Template

If for any reason, the entire ad call template for OpenX has to change, it is possible to specify a new template via the OVA configuration.

The following configuration snippet illustrates how to override the default template:

...
  "ads": {
      "servers": [
          "type": "OpenX",
          "apiAddress": "my-openx-address",
          "requestTemplate" "specify-the-new-template-here"
      ],
      ...
  }
...

4.4.3 Enabling Ad Repetition

By default, if a request is received by OpenX for more ad positions than it can fill, it won't allow repetition of ads in the response to cover the full requirement.

The "allowAdRepetition" configuration option should be used to instruct OpenX to support ad repetition in the matching. When set to "true", the "block" element of the OpenX call will be set to "0" (block=0). By default, block=1 (no repetition allowed).

4.4.4 Delivering Targeted Advertising

It is possible to add targeting information to an OpenX call. By specifying "target" key value pairs via the "customProperties" element of the OVA ad server configuration block, a number of key value pairs can be added to the end of the standard OpenX call.

For example, consider the following configuration snippet:

  "ads": {
      "servers": [
          {
             "type": "OpenX",
             "apiAddress": "http://openx.openvideoads.org/
                            openx/www/delivery/fc.php",
             "allowAdRepetition": true
             "customProperties": {
                  "target": [ "category=food", "gender=male" ]
             }
          }
      ],
      "schedule": [
          {
             "zone": "5",
             "position": "pre-roll"
          }
      ]
  },
...

In this example, &category=food&gender=male will be added to the end of the OpenX call.

OpenX: OVA Configuration Guide

1. Recommended Reading

2. Operational Requirements

3. Configuring OpenX to Deliver Video Advertising

4. Configuring OVA to Request and Playback OpenX Video Advertising

4.1 Security and the "crossdomain.xml" File

4.2 Making an OpenX Ad Request

4.3 Configuring the OpenX Ad Server Instance

4.4 Constructing the Request to OpenX

4.4.1 Using the OpenX Default Ad Call Template

4.4.2 Overriding the Default Ad Call Template

4.4.3 Enabling Ad Repetition

4.4.4 Delivering Targeted Advertising

JW Player

AddOns

AdSolution

Bits on the Run

Open Video Ads

Company