+ All Categories
Home > Documents > OpenX Reference Guide

OpenX Reference Guide

Date post: 24-Oct-2014
Category:
Upload: dclark127
View: 280 times
Download: 3 times
Share this document with a friend
36
OpenX Reference Guide for OpenX 2.8 To download your free copy of this reference guide, please visit www.openxconsultant.com Version: v2.8 Author: Erik Geurts - OpenX Consultant Date: August 2010 Status: Final
Transcript
Page 1: OpenX Reference Guide

OpenX Reference Guide

for OpenX 2.8

To download your free copy of this reference guide, please visit www.openxconsultant.com

Version: v2.8 Author: Erik Geurts - OpenX Consultant

Date: August 2010 Status: Final

Page 2: OpenX Reference Guide

© Copyright 2007 - 2010 Erik Geurts - OpenX Consultant

No part of this document may be duplicated, stored in an automated database or published

in any form or using any method, be it electronic, mechanical, by photo copying, recording

or in any other way, without the explicit prior written permission from the author.

This document was assembled with the greatest possible care. To the best knowledge of the

author, the information in this document is correct, complete and up to date at the time of

writing. It is possible though that after publication new developments occurred or new

insights were found. If you find errors or omissions, it would be highly appreciated if you

inform the author or sender of this document.

Print date of this version: August 7, 2010. Document version: v2.8.

Page 3: OpenX Reference Guide

OpenX Reference Guide OpenX 2.8

August 2010 page iii

Table of contents

Table of contents ............................................................................................iii

Section 1: Getting started ..................................................................................1

1 Introduction to OpenX Ad Server..................................................................2 1.1 What is OpenX Ad Server? 2 1.2 What is an ad server used for? 2 1.3 How does OpenX work? 2

1.3.1 Websites and zones 2 1.3.2 Advertisers, campaigns and ads 2 1.3.3 Targeting: the right ad at the right spot 2 1.3.4 Statistics: to measure is to manage 2

1.4 How to get started with OpenX Ad Server 3

Section 2: Serving your first campaign...................................................................4

2 OpenX Ad Server basic concepts and terminology ............................................5 2.1 Website 5 2.2 Zone 5 2.3 Advertiser 6 2.4 Campaign 6 2.5 Banner (ad) 7 2.6 Linking campaigns, banners and zones 7

3 The ad delivery process in OpenX Ad Server ...................................................9 3.1 Webpage / zone tag invokes OpenX Ad Server 9 3.2 OpenX Ad Server ‘delivery engine’ selects ad 9 3.3 Logging ad impressions 9 3.4 Logging ad clicks 10 3.5 How logged data is recorded and stored 10 3.6 Other types of logged data 10

Section 3: Diving deeper ..................................................................................11

4 A closer look at campaigns........................................................................12 4.1 Campaign types 12

4.1.1 Remnant campaigns 12 4.1.2 Contract campaigns 12 4.1.3 Exclusive campaigns 12

4.2 Campaign start and end date 13 4.3 Pricing model 13

4.3.1 CPM (cost per mille) 13 4.3.2 CPC (cost per click) 14 4.3.3 CPA (cost per action) 14 4.3.4 Monthly tenancy 14

Page 4: OpenX Reference Guide

OpenX Reference Guide OpenX 2.8

August 2010 page iv

4.3.5 Comparing revenues from different pricing models 15 4.4 Priority and weight introduction 15 4.5 Capping 15 4.6 Companion positioning 16

5 Priorities, weights and probabilities............................................................17 5.1 Scenario 1: Remnant campaigns 17

5.1.1 One zone, one campaign with one ad in it 17 5.1.2 Step 2: adding an ad to the existing campaign 18 5.1.3 Step 3: changing the weight of the second ad 18 5.1.4 Step 4: adding another campaign with one ad 19 5.1.5 Step 5: adjusting the weight of the second campaign 19

5.2 Scenario 2: Adding Contract campaigns to the mix 20 5.2.1 Starting point: one zone, one remnant campaign with one ad 20 5.2.2 Step 2: adding Contract campaign 20

5.3 Scenario 3: Topping it off with Exclusive campaigns 21

6 Targeting ads: delivery limitations, channels and capping ................................23 6.1 Capping 23 6.2 Targeting 23

6.2.1 Client (computer and browser) 24 6.2.2 Geographic targeting 24 6.2.3 Site targeting 24 6.2.4 Time targeting 25 6.2.5 Combining delivery limitations 25

6.3 Targeting channels 25

7 Measuring conversions .............................................................................27 7.1 Introducing conversion tracking 27 7.2 How does OpenX Ad Server measure conversions 27

Section 4: OpenX Ad Server for webmasters and IT staff..........................................28

8 Integrating OpenX with your website ..........................................................29 8.1 Every zone has a tag 29 8.2 Single page call 29

8.2.1 How single page call works 29 8.2.2 Advanced use of single page call 30

8.3 Do’s and don’ts 31 8.3.1 Don’t use Direct selection 31 8.3.2 Don’t use keywords 31

Page 5: OpenX Reference Guide

OpenX Reference Guide - Section 1: Getting started OpenX 2.8

Last updated August 2010 page 1 of 32

Section 1: Getting started

Page 6: OpenX Reference Guide

OpenX Reference Guide - Introduction to OpenX Ad Server OpenX 2.8

Last updated August 2010 page 2 of 32

1 Introduction to OpenX Ad Server

1.1 What is OpenX Ad Server?

OpenX Ad Server is an ad server, created and published by the British-American company

OpenX.org. It is a system that can be used to manage and optimize the advertising space on

one or more websites. It is a tool for web site owners (called ‘publishers’ in the online

advertising industry).

1.2 What is an ad server used for?

When managing a website, or perhaps even multiple websites, there can be a lot of work

involved in putting advertisements on the site and removing them again, especially when this

is done by entering the ads directly into the site’s coding. It takes a lot of time and it reduces

flexibility. An advertising server (usually shortened to ad server) like OpenX can provide a real

solution in this scenario.

1.3 How does OpenX work?

1.3.1 Websites and zones

In the OpenX Ad Server, one can define websites, and also one or more zones for each

website. A zone represents a space on the webpages where ads are supposed to be displayed.

For every zone there is a little snippet of HTML code, which must be placed in the site, at the

exact spot where the zone should go. This forms the integration between the site and the

OpenX Ad Server. It is a one time job, that will take little time for an experienced webmaster

or developer. The word ‘zone’ is a term in OpenX, other systems refer to it as ‘location’,

’spot’, ‘placement’ or ‘position’.

1.3.2 Advertisers, campaigns and ads One can also create advertisers, campaigns and ads in the OpenX Ad Server. Those can be

internal campaigns or campaigns from direct advertisers, but also ads from external ad

networks like Google AdSense, from affiliate networks like Commission Junction, or from

advertisers and agencies that use systems like DoubleClick.

1.3.3 Targeting: the right ad at the right spot The final step is to link the right campaigns to the right zones, effectively determining which

ads will appear where. This can be combined with various forms of targeting, matching the

display of ads to specific situations. OpenX Ad Server can handle targeting based on date, day

and time, geographic are (country or city, and more), web browser used by the visitor, and

language set by the visitor, to name just a few. There are also advanced targeting options,

using known information about members or customers (like their gender, education or age

range), or from known details about the site’s content and structure (for instance: display the

ad only in the ‘news’ section or anywhere but the ’sports’ pages).

1.3.4 Statistics: to measure is to manage The OpenX Ad Server measures how often ads are displayed and clicked, and has reports for

these numbers plus ad revenue for the publisher, advertiser and webmaster. It also has

functionality to measure conversions, leads or transactions on the advertiser’s website that

occur as a result on a click on a banner that was displayed on the publisher’s site.

Page 7: OpenX Reference Guide

OpenX Reference Guide - Introduction to OpenX Ad Server OpenX 2.8

Last updated August 2010 page 3 of 32

1.4 How to get started with OpenX Ad Server

OpenX Ad Server is a free open source application that can be installed by anyone on their

own server. It is written in the PHP programming language and stores data using the MySQL

database, both of which are also open source software. Except for time and hardware, there

are no additional costs, and no license fees. Another option is to hire a specialized hosting

company to handle the technical aspects.

The OpenX Ad Server can be utilized by small and large website publishers, by ad networks

and by advertisers. The system has been designed to enable installation on a cluster of web

servers, allowing it to grow alongside the growth of the sites. There are companies that

display in excess of 1 billion ads per month using OpenX Ad Server. That does involve quite a

bit of hardware of course.

Nowadays one can also open an account on OpenX Hosted, on offer by the OpenX.org

company. This is free of charge up to a volume of 100 million ads per month. For anything

above that, there are paid enterprise accounts.

OpenX Ad Server is available in two forms:

• As a downloadable software package that can be installed on a web server

• As a hosted service, operated by OpenX.org Ltd, under the name “OpenX Hosted”

OpenX Hosted comes in two flavors:

• A service that’s free for up to 100 million ad impressions per month

• A paid service for enterprise users going over 100 million ad impressions per month or

users having special requirements (e.g. SLA, modifications, support)

Page 8: OpenX Reference Guide

OpenX Reference Guide - Section 2: Serving your first campaign OpenX 2.8

Last updated August 2010 page 4 of 32

Section 2: Serving your first campaign

Page 9: OpenX Reference Guide

OpenX Reference Guide - OpenX Ad Server basic concepts and terminology OpenX 2.8

Last updated August 2010 page 5 of 32

2 OpenX Ad Server basic concepts and terminology

This chapter describes the basic concepts that every user needs to understand before starting

to use OpenX Ad Server.

The main concepts of OpenX Ad Server are as follows:

• Website – Zone

• Advertiser – Campaign – Ad

• Linked zones – Linked campaigns

All of these together are called ‘inventory’ in the OpenX Ad Server user interface (UI). These

concepts will be discussed in more detail in the paragraphs below.

The discussion in this chapter is for using OpenX from the perspective of a publisher, but the

same concepts and terminology apply to use cases for ad networks and advertisers.

2.1 Website

In OpenX Ad Server, a website is a representation of an actual site on the internet. It could

also be a section of a larger site. Site properties include the URL, the site’s name, contact

and contact’s e-mail address.

As mentioned earlier, OpenX Ad Server was designed to be able to manage the advertising

inventory for multiple websites at once. This gives the ability to have one campaign running

on a group of sites. In the advertising business, people sometimes call this a ‘network of

sites’.

In itself, websites don’t do very much in OpenX Ad Server, other than being a way of

organizing zones into groups of zones and to summarize statistics.

2.2 Zone

In OpenX Ad Server, a zone is the representation of a place on a web page where ads are

supposed to be displayed. It’s a place holder. In the online advertising business, people also

use words like ‘ad spot’, ‘ad location’, ‘ad position’ for this concept.

A zone in OpenX Ad Server has a few properties: name, description and size (width and

height). And after creation, every zone gets a unique ID.

There are 4 types of zones:

• Banner – for displaying ads on a web page

• Interstitial / floating DHTML – for displaying an ad in a ‘layer’ that’s floating in front of

the actual web page

• Text ad – for displaying ads in a paragraph of text on a web page, looking identical to any

other links

• Email/newsletter – a special version of the ‘banner’ type for use in e-mail newsletters

Page 10: OpenX Reference Guide

OpenX Reference Guide - OpenX Ad Server basic concepts and terminology OpenX 2.8

Last updated August 2010 page 6 of 32

In almost all cases, zones are part of the overall site layout that’s being implemented through

some kind of page template. Many sites also have different templates for different sections,

like the home page, the news pages and the forum pages. Whatever the case, the zones are

part of the template, and as a result will automatically appear on all the site’s pages using

that template.

OpenX Ad Server generates snippets of html or JavaScript code, called ‘invocation code’ in

OpenX. These snippets of code, also referred to as ‘tags’, are pasted into the template,

which enables the pages that use these templates to show zones and the campaigns and ads

linked to those zones. The next chapter has a detailed description of how ad delivery works.

2.3 Advertiser

An Advertiser is an individual or organization that runs ad campaigns on websites owned by

publishers.

One can think of many different types of institutions that can all be entered into OpenX Ad

Server under the heading of ‘advertiser’:

• a direct advertiser

• an agency representing one or more advertisers and/or running their campaigns with

multiple publishers

• an ad network (like Adbrite),

• an affiliate network (like Commission Junction),

• an affiliate program (like Amazon Associates), or

• a contextual ad system (like Google AdSense or Yahoo sponsored search)

In OpenX Ad Server, an advertiser has a name, a contact and their e-mail address. There are a

few advanced settings and features too, to be discussed in later chapters.

2.4 Campaign

Any advertiser can have one or more campaigns. A campaign is a collection of ads that have

several properties in common.

In OpenX Ad Server, a campaign has:

• a name

• a type: ‘remnant’, ‘contract’ or ‘contract exclusive’ (more on these types in a later

chapter)

• a start and end date (optional)

• pricing information based on a selected pricing model (more on pricing in a later

chapter)

• a priority or weight (remnant and exclusive campaigns have weights, contract campaigns

have priorities, more on this subject in a later chapter)

• capping (a way to limit the number of ad views per site visitor, more on this in a later

chapter)

• companion positioning (optional)

Page 11: OpenX Reference Guide

OpenX Reference Guide - OpenX Ad Server basic concepts and terminology OpenX 2.8

Last updated August 2010 page 7 of 32

New users often find the user interface for entering and managing campaigns complicated,

because campaign type, start and end date, pricing model, priority and weight all influence

one another in all directions.

A campaign can be linked to a zone (or to multiple zones). Zones are discussed in one of the

earlier paragraphs of this chapter. A zone will automatically only show the ads that are part

of the campaign and that have the exact same dimensions (width and height) as the zone.

2.5 Banner (ad)

An ad is a creative that is part of one campaign. In OpenX Ad Server these are called

‘banners’ which shows the age of the software because back when phpAdsnew was develop

that was what online adverting was all about. In this book we will use the term ‘ad’ mostly.

There are 5 different types of ads:

• Local banner (stored in the web server’s file system)

• Local banner (stored in the ad server’s database)

• External banner (hosted by the advertiser, agency or ad network)

• Generic HTML banner (an ad that’s actually a snippet of HTML code that, when delivered

to the visitor’s web browser, will be rendered to show the ad)

• Generic Text banner

All ads have in common that they contain an element that will be visible on the website and a

destination URL. The website visitor will be taken to that URL when he/she clicks the ad. In

the online advertising business, this destination URL is also referred to as the landing page.

Ads generally also have a specific size (width and height). In OpenX Ad Server they also have a

weight. More information about weights can be found in one of the later chapters.

The delivery of ads can be limited by various settings, which allows the user to target the ad

to a specific location, audience, or condition. In one of the later chapters this targeting

mechanism will be described in more detail.

In addition to linking campaigns to zones, one can also link an individual ad to a zone.

Consequently, it is also possible to unlink one ad from a zone even thought the campaign that

the ad is part of is linked to that zone. The ability to link individual ads rather than whole

campaigns provides extra flexibility, but it comes at the price of requiring more work to set

everything up.

2.6 Linking campaigns, banners and zones

Once you have created some advertisers, campaigns and ads, and also some websites and

zones, the final step is to create the links between the campaigns and the zones. That way,

one can determine that the ads of a campaign should be shown in certain zones.

Page 12: OpenX Reference Guide

OpenX Reference Guide - OpenX Ad Server basic concepts and terminology OpenX 2.8

Last updated August 2010 page 8 of 32

When multiple campaigns are linked to a single zone, OpenX Ad Server assigns a probability

percentage to each of the banners in those campaigns, but only for those banners that have

the exact same dimensions as the zone. The probability percentage determines how likely it

is that an ad is delivered when the zone is called. More information about the probability

calculation mechanism can be found in a later chapter.

Page 13: OpenX Reference Guide

OpenX Reference Guide - The ad delivery process in OpenX Ad Server OpenX 2.8

Last updated August 2010 page 9 of 32

3 The ad delivery process in OpenX Ad Server

This chapter describes how OpenX Ad Server delivers ads and how data is collected during

delivery.

3.1 Webpage / zone tag invokes OpenX Ad Server

When a visitor opens a web page in their browser, the browser finds the invocation code1 for

one or more zones in the page’s source code. The invocation code is executed by the

browser, and this creates a request to the ad server. OpenX Ad Server has the ability to log

these requests, but that feature is switched off by default. Not many people enable it,

because it doesn’t add a lot of value to the reporting.

The request to the ad server contains one element that’s always present: the zone ID. The

request can also contain extra information that can be used by the ad server to facilitate

targeting2.

3.2 OpenX Ad Server ‘delivery engine’ selects ad

When the browser of the visitor executes the invocation code, OpenX Ad Server receives a

request, basically just saying: “please deliver an ad for zone X”. This request is processed by

the section of the OpenX Ad Server called the ‘delivery engine’.

After verifying that the zone ID actually exists, the delivery engine will perform the following

steps:

• Retrieve information about the ads that are linked to the zone, and their probability

percentages.

• Select one of the linked ads using the probability percentages

• Process the delivery limitations for the ad it has selected, to ensure that any and all

conditions from targeting settings and the capping for that ad are met. If the ad that was

selected initially should not be delivered because of delivery limitations, the delivery

engine will select one of the other ads. This continues until it finds an ad that can be

delivered.

• Retrieve the details of the ad and return that to the browser.

The browser received the ad content that is stored in OpenX Ad Server for the ad that was

selected in the steps described.

3.3 Logging ad impressions

In addition, the browser also retrieves a little extra HTML snippet. This snippet, when

rendered by the browser, produces a small (1x1 pixel) transparent image. The parameters of

the image’s URL contain information like the zone ID and the ad ID. The person visiting the

site doesn’t see it, but the fact that it is displayed is logged by OpenX. This is the way OpenX

Ad Server counts ad impressions, which is compliant with the guidelines issued by the IAB

(Interactive Advertising Bureau). This technique is sometimes called ‘logging pixel’, ‘logging

beacon’ or ‘beacon image’ in the online advertising industry.

1 See the previous chapter for information about zones and invocation codes 2 More about targeting in a later chapter.

Page 14: OpenX Reference Guide

OpenX Reference Guide - The ad delivery process in OpenX Ad Server OpenX 2.8

Last updated August 2010 page 10 of 32

Every ad impression is logged in the OpenX Ad Server database, with information about the ID

of the ad that was delivered, the ID of the zone it was delivered in, date and time, IP address

of the visitor, and so on.

3.4 Logging ad clicks

In almost all cases the purpose of displaying ads on a site is to enable the visitors to click on

the ad. The ad therefore has a link associated with it that leads to what OpenX Ad Server

calls the ‘destination URL’.

That link has an OpenX Ad Server link in front of it, so that OpenX Ad Server can record clicks

on the link. When the person viewing the ad clicks on it, the browser will first send a request

to OpenX, containing parameters telling the system what the ID is of the ad that was clicked,

and what the ID is of the zone it was in. This information is logged, together with the exact

date and time and the IP address of the computer where the click occurred.

Then OpenX Ad Server sends a redirect command to the browser, instructing it to display the

destination URL that is associated with the ad. This whole process of recording the click and

redirecting the browser to the destination URL takes so little time that in almost all cases the

visitor doesn’t notice it at all.

3.5 How logged data is recorded and stored

As described in the previous paragraphs, OpenX Ad Server continuously records every single

ad impression and ad click. The data it collects is kept in back end of the database, and is not

visible through the OpenX Ad Server user interface. The OpenX developers refer to this data

as ‘raw data’, because it hasn’t been summarized into the on-screen statistics.

In most cases, there is more than one zone on any single web site, so viewing a web page will

cause multiple ad impressions being logged.

The logging of raw data is called ‘bucket logging’. Raw data is being recorded for every

combination of an ad and a zone, and the software keeps a running total. The first impression

of an ad in a zone creates a record with an impression count of 1. The second impression

increases that count to 2, and so on.

The raw data is logged in buckets for every hour, per ad / zone combination. At the top of

the new hour, OpenX Ad Server starts with new buckets. In addition to being able to have

buckets by ad/zone, the system can also have additional buckets with more levels of detail.

This can be achieved by developing a new plug-in.

3.6 Other types of logged data

In addition to the most common types of raw data, impressions and clicks, OpenX can also

record raw data about ad requests (that’s even before an ad is actually delivered) and on

‘conversions’.

Page 15: OpenX Reference Guide

OpenX Reference Guide - Section 3: Diving deeper OpenX 2.8

Last updated August 2010 page 11 of 32

Section 3: Diving deeper

Page 16: OpenX Reference Guide

OpenX Reference Guide - A closer look at campaigns OpenX 2.8

Last updated August 2010 page 12 of 32

4 A closer look at campaigns

This chapter describes campaigns, and how their properties affect the delivery of the ads in

the campaign.

4.1 Campaign types

When creating a new campaign in OpenX Ad Server, there are three types of campaigns

available. They are:

• Remnant

• Contract

• Contract (Exclusive)

Before any other property of the campaign can be specified, a campaign type has to be set.

Having an understanding of the different types and their uses could avoid a lot of confusion

and frustration.

4.1.1 Remnant campaigns The word ‘remnant’ means “leftover, a small part or portion that remains”. Despite that

name, it is actually a campaign type that will be used very often. The most common scenario

is that a site owner has one or more remnant campaigns that can be displayed at any time.

Google AdSense ads are a good example. It’s a kind of ‘if all else fails, show these ads’ setup.

For many people, the reason to start using an ad server is to get away from having their ads

hard coded in their website’s pages. Instead, they place the invocation code for the

equivalent zones on the pages, put the Google AdSense ad codes into OpenX Ad Server and

link it to these zones. The effect is of course that there are still ‘just’ AdSense ads on the

pages, but now it is very easy to run another set of ads or start showing a paid advertising

campaign.

Another great use of remnant campaigns is displaying internal promotions. When a new

section is added to a website, it might be useful to promote it to people visiting other parts

of the site.

Remnant campaigns are also called ‘house campaigns’, presumably because there is no paying

advertiser, they are ‘on the house’ in a manner of speaking.

With one or more remnant campaigns running through the OpenX Ad Server and displaying on

the website, everything is set and ready when a paying advertiser comes along.

4.1.2 Contract campaigns Contract campaigns can be used for many scenarios, but most often it is a paid campaign

from what is generally referred to as a ‘direct advertiser’.

4.1.3 Exclusive campaigns In situations where there are multiple contract campaigns, possible even with more

impressions booked than there are available through the site(s) a Contract (exclusive)

campaign gets an even higher priority than the regular Contract campaign.

Page 17: OpenX Reference Guide

OpenX Reference Guide - A closer look at campaigns OpenX 2.8

Last updated August 2010 page 13 of 32

Exclusive campaigns are useful in scenarios where multiple Contract campaigns are fighting

for the available traffic, possibly even exhausting it. Then an Exclusive campaign is going to

be displayed with preference to all other campaigns.

Even though the word ‘exclusive’ suggests that it will get exclusivity, OpenX Ad Server can

run two or even more exclusive campaigns at the same time.

4.2 Campaign start and end date

By default, campaigns have no start and end date. They will start delivering (when linked to

zones) straight away after they’ve been created, and they will not expire.

When a campaign has a start date in the future, OpenX Ad Server will automatically activate

that campaign at midnight of that date.

When a campaign has an end date, the campaign will continue to run until midnight of the

that date.

So both the start date and the end date are inclusive.

4.3 Pricing model

OpenX Ad Server can report on ad revenues based on several different pricing models. The

pricing models available are:

• CPM (cost per mille)

• CPC (cost per click)

• CPA (cost per action)

• Monthly tenancy

In all of the ‘cost per …’ types, the word ‘cost’ refers to what it costs the advertiser to be

running the ads on the sites. These are standard terms from the online advertising industry.

4.3.1 CPM (cost per mille) A CPM campaign has a pricing model that pays an amount of money for every thousand ad

impressions. The word ‘mille’ comes from Latin and means ‘thousand’. Advertisers, ad

agencies and site owners often negotiate advertising deals based on CPM. When everyone uses

this term in the same way, it’s easy to compare and agree on deals.

In OpenX Ad Server, selecting a CPM pricing model allows for specifying:

• The rate/price (for every thousand ad impressions).

• The number of impressions booked, with the default being ‘unlimited’.

If a CPM rate and an overall budget have been agreed with the advertiser, this information

will be used to calculate the number of impressions. A budget of 100 and a CPM rate of 1

equals 100,000 impressions booked. As soon as OpenX Ad Server has completed delivering

these 100,000 impressions, the campaign will be deactivated automatically.

Page 18: OpenX Reference Guide

OpenX Reference Guide - A closer look at campaigns OpenX 2.8

Last updated August 2010 page 14 of 32

When OpenX Ad Server is used to display ads from an ad network like Google AdSense, it

might be useful to put the average ECPM (see below) that AdSense reports into the ‘Rate /

Price’ box, so that you can get an impression of the AdSense revenue from the statistics

reported by OpenX Ad Server.

4.3.2 CPC (cost per click) A CPC campaign has a pricing model that pays an amount of money for every single click on

an ad from the campaign. When a site visitor clicks and ad, the destination URL (the landing

page) associated with that ad will be displayed, and that is what the advertiser is willing to

pay for.

In OpenX Ad Server, selecting a CPC pricing model allows for specifying:

• The rate / price (for every single ad click)

• The number of clicks booked, with the default being ‘unlimited’.

• The number of impressions booked, again with the default being ‘unlimited’.

If a CPC rate and an overall budget have been agreed with the advertiser, this information

will be used to calculate the number of clicks. A budget of 100 and a CPC rate of 1 equals 100

clicks booked. Leaving the number of impressions booked at unlimited will mean that the

campaign will automatically be deactivated as soon as these 100 clicks have occurred.

It is also possible to enter a maximum for both number of clicks and number of impressions.

As soon as OpenX Ad Server reaches either of these limits, the campaign will be deactivated

immediately.

4.3.3 CPA (cost per action) A CPA campaign has a pricing model that pays the website owner based on the actions of

visitors on the advertiser’s website. The advertiser might be looking for sales, leads, or even

simply people signup up for a forum, member list or newsletter, and is willing to pay for that

desired end result. In the online advertising industry, this end result the advertiser is aiming

for is often called a ‘conversion’. It refers to a scenario where a passer-by is turned into a

customer or member, converted so to speak.

In OpenX Ad Server, selecting a CPA pricing model allows for specifying:

• The rate / price (for every single ad click)

• The number of conversions booked, with the default being ‘unlimited’.

• The number of clicks booked, with the default being ‘unlimited’.

• The number of impressions booked, again with the default being ‘unlimited’.

4.3.4 Monthly tenancy A Monthly tenancy campaign has a pricing model where the advertising is paying a fixed

amount of money per month, regardless of the number of ad impressions, clicks or

conversions. This type of pricing is perfect for sponsorship deals.

In OpenX Ad Server, selecting a Monthly tenancy pricing model allows for specifying:

• The rate / price per month.

Page 19: OpenX Reference Guide

OpenX Reference Guide - A closer look at campaigns OpenX 2.8

Last updated August 2010 page 15 of 32

4.3.5 Comparing revenues from different pricing models Comparing campaigns with different pricing models is difficult in advance. For example, the

click-through ratio (the number of times an ad is clicked as a percentage of the number of

times it is displayed) is hard to predict up front. However, when looking at past statistics, it is

very easy to see how a CPC campaign is doing, because OpenX Ad Server will report the

revenues from the clicks as an amount expresses per 1,000 ad impressions. The same can be

said for CPA campaigns or Monthly tenancy campaigns.

The amount of money earned by the site owner from running a campaign can be expressed in

a factor called ‘ECPM’. This means ‘Earned Cost per Mille’. It expresses how much money on

average the site owner has earned for every thousand ad impressions. Calculating all different

pricing models to ECPM enables site owners to compare them, even if different pricing models

are set for the various campaigns.

4.4 Priority and weight introduction

The three campaign types (Remnant, Contract and Exclusive) have their own characteristics

when it comes to interacting with other campaigns. These interactions are based on campaign

weight and priority. This table shows what is available in OpenX Ad Server:

Campaign type Weight Priority

Remnant �

Contract �

Contract (exclusive) �

Weight is entered as a number between 0 and 127. The specific value is not important. It is

the value in comparison to the weight of other campaigns that is significant. Setting a

campaign’s weight at 0 (zero) will halt that campaign immediately, a very effective way of

(temporarily) disabling a campaign.

Priority is selected from a list ranging from 1 to 10. Like with weight, it is not the value itself

that is important. Priority of a campaign works in relation to the priorities of other

campaigns.

Priority and weight are an important but complicated subject. One of the later chapters has

much more detail.

4.5 Capping

Delivery capping is a way of limiting how often the ads from a campaign can be displayed for

every single visitor of the site(s). It is possible to specify a maximum number of campaign

views per visitor for the life time of the campaign, or just for the length of a single session.

Capping works by recording a count of the campaign’s impressions in a cookie on the user’s

computer. If OpenX Ad Server finds that the browser does not accept cookies, then campaigns

with capping will not be delivered at all, to be on the safe side.

Page 20: OpenX Reference Guide

OpenX Reference Guide - A closer look at campaigns OpenX 2.8

Last updated August 2010 page 16 of 32

Capping can also be specified at the banner level, and every banner can even have its own

capping specified. When capping is set for a campaign, entering capping for the banner

overrules it.

Example: campaign capping set to 5 but banner capping set to 3 means that the specific

banner can only be delivered three times, even if the campaign’s capping hasn’t been

exhausted yet.

4.6 Companion positioning

One of the settings for a campaign is called ‘companion positioning’. It is a switch that can be

ON or OFF.

It is easiest to understand what companion positioning does, by giving an example:

• Let’s assume there is a website defined in OpenX, and this website has two zones. The

first zone is a leader board (728x90), at the top of the page. The second zone is a wide

sky scraper (160x600), which is at the right hand side of the page next to the page’s

content.

• There is also a campaign defined in OpenX. The ‘companion mode’ checkbox for the

campaign is set to ON. The campaign contains a leader board size ad, and also a sky

scraper size ad. The campaign is linked to both zones mentioned above.

• There are also various other campaigns, all linked to both zones. Some have leader board

ads, some have sky scraper ads, and some have both.

When the page is loaded in the browser and OpenX processes the request for the first zone, in

some cases it will pick the leader board size ad from the campaign with ‘companion

positioning’ enabled. When this happens, it will always select the sky scraper size ad from

that campaign when it processes the sky scraper zone.

In the online advertising business, this effect is also called ‘page take over’, ‘hockey stick’ or

‘wall papering’.

Companion positioning does not work when the invocation code for the zones is of the iframe

type. It does work with JavaScript tags and also with single page call.

Page 21: OpenX Reference Guide

OpenX Reference Guide - Priorities, weights and probabilities OpenX 2.8

Last updated August 2010 page 17 of 32

5 Priorities, weights and probabilities

OpenX is capable of delivering multiple campaigns at the same time on multiple sites and

zones. The user can determine how often each ad is displayed by assigning priorities and

weights to each campaign and ad. And when there are settings in a campaign that instruct the

ad server to display an ad a specific number of times, this will also be taken into account.

OpenX will then automatically adjust the distribution parameters of the ads to reach the

desired volumes.

This chapter contains an introduction to the way priorities and weights drive the probability

of an ad being shown through a zone. It is a rather complicated aspect of OpenX, and the

examples below are just the basics.

Important note: the information in this chapter is based on the algorithms in OpenX version

2.8.2 and higher. In earlier versions of OpenX 2.8, the algorithm has significant differences to

the current versions.

5.1 Scenario 1: Remnant campaigns

5.1.1 One zone, one campaign with one ad in it Let’s start with this very simple scenario:

• There is just one website, which has one zone associated with it.

• There is also just one advertiser, who has one campaign with one ad in it.

• The campaign is set as ‘remnant’, with no start or end date, unlimited impressions and

the weight of the campaign is set to 103.

• The ad in the campaign has a weight of 104 and it is of exactly the same size as the zone

in the inventory.

• The campaign is linked to the zone.

• There are no frequency caps or delivery limitations.

OpenX has an algorithm that calculates how often an ad should be delivered when the zone

that the ad’s campaign is linked to is requested. Since there is just one ad in the only

campaign linked to the zone, OpenX assigns the ad in this simple scenario a 100% probability

of being delivered.

The probability calculation is performed for each zone in the system. Here’s how the

calculation works in this scenario:

• OpenX first retrieves the list of campaigns linked to the zone (in this case just one) and

then all the ads in it that have the same size as the zone (also just one)

• OpenX then checks if there are any exclusive or contract campaigns, because these get a

special treatment that’s described later in the chapter. But in this case, the only

campaign it finds is a remnant campaign.

• OpenX multiplies the campaign’s weight (set at 10) and the ad’s weight (also set at 10),

resulting in a product of 100.

3 The default weight of a new campaign in OpenX is 1, but any value between 0 and 127 can

be entered 4 Again, the default weight of an ad is 1, but it can be anything between 0 and 127

Page 22: OpenX Reference Guide

OpenX Reference Guide - Priorities, weights and probabilities OpenX 2.8

Last updated August 2010 page 18 of 32

• OpenX then sums the multiplied weights of all the ads linked to the zone (again, just one

ad), and then expresses the probability for each ad as the percentage of the ad’s

multiplied weight in the summed overall weight. The table below shows this:

Campaign Weight Ad Weight Multiplied Probability

Campaign A 10 Ad A1 10 100 100%

Sum 100

The end result is, not surprisingly, that OpenX will deliver ad A1 100% of the times Zone 1 is

requested.

5.1.2 Step 2: adding an ad to the existing campaign Now we add a second add to the same campaign. This ad is defined with the exact same

settings as the first ad, so the weight of the ad is also 10.

There are now two ads linked to the zone, and here’s how the probability for each of these

ads is calculated for the zone:

Campaign Weight Ad Weight Multiplied Probability

Campaign A 10 Ad A1 10 100 50%

Campaign A 10 Ad A2 10 100 50%

Sum 200

5.1.3 Step 3: changing the weight of the second ad Let’s assume the advertiser has asked us to show the second less often than the first ad. We

now adjust that ad’s weight from 10 to 5. Here’s how OpenX recalculates the probabilities for

the zone:

Campaign Weight Ad Weight Multiplied Probability

Campaign A 10 Ad A1 10 100 66,667%

Campaign A 10 Ad A2 5 50 33,333%

Sum 150

As this example shows, the weight of each ad, relative to the weight of every ad linked to the

zone determines how often that ad will be delivered. Even if we had assigned the ads

different weights in the same relative way, the end result would have been the same:

Campaign Weight Ad Weight Multiplied Probability

Campaign A 10 Ad A1 20 200 66,667%

Campaign A 10 Ad A2 10 100 33,333%

Sum 300

Page 23: OpenX Reference Guide

OpenX Reference Guide - Priorities, weights and probabilities OpenX 2.8

Last updated August 2010 page 19 of 32

5.1.4 Step 4: adding another campaign with one ad Now let’s assume the advertiser asked us to add another campaign. This campaign is almost

identical to the first one:

• It is also a remnant campaign with no start or end date, and a weight of 10.

• There is just one ad in this, this ad has a weight of 10.

• Then the new campaign is linked to the existing zone.

Here’s what the probability calculation will result in:

Campaign Weight Ad Weight Multiplied Probability

Campaign A 10 Ad A1 10 100 33,33%

Campaign A 10 Ad A2 5 50 15,67%

Sum 150

Campaign B 10 Ad B1 10 100 50%

Sum 100

The available 100% of ad impressions is first spread across the 2 available campaigns, and

since they have equal weights, each one gets 50% of that.

Campaign B has just one banner in it, so that banner gets 50%.

However, campaign A has 2 banners in it, and these banners will get a portion of the 50% of

that campaign relative to their weight.

5.1.5 Step 5: adjusting the weight of the second campaign Now let’s investigate what the effect is of changing the weight of the new campaign, leaving

the weight of the individual ads intact. In this example, the second campaign gets a weight of

20. The table below shows how OpenX recalculates the probabilities:

Campaign Weight Ad Weight Multiplied Probability

Campaign A 10 Ad A1 10 100 22,22%

Campaign A 10 Ad A2 5 50 11,11%

Sum 150

Campaign B 20 Ad B1 50 200 66,67%

Sum 200

The available 100% of ad impressions is first spread across the 2 available campaigns, where

Campaign A gets 10/30 or 33,33% of the total. Campaign B gets 20/30 or 66,67%.

The two banners in campaign A then each get their share of the 33,33% available to that

campaign, so banner A1 gets 100/150 or 2/3 of the 33,33%, resulting in 22,22%. The other

banner A2 likewise gets 50/150 or 1/3 of 33,33%, equaling 11,11%.

Page 24: OpenX Reference Guide

OpenX Reference Guide - Priorities, weights and probabilities OpenX 2.8

Last updated August 2010 page 20 of 32

5.2 Scenario 2: Adding Contract campaigns to the mix

This second scenario illustrates how OpenX handles Contract campaigns relative to Remnant

campaigns5.

5.2.1 Starting point: one zone, one remnant campaign with one ad In this new scenario, we start with the following:

• There is just one website, which has one zone associated with it.

• There is also just one advertiser, who has one campaign with one ad in it.

• The campaign is set as ‘remnant’6, with no start or end date, unlimited impressions and

the weight of the campaign is set to 107.

• The ad in the campaign has a weight of 108 and it is of exactly the same size as the zone

in the inventory.

• The campaign is linked to the zone.

• There are no cappings or delivery limitations.

Campaign Weight Ad Weight Multiplied Probability

Campaign A 10 Ad A1 10 100 100%

Sum 100

We also know that the zone in this scenario is receiving exactly 10,000 impressions per day.

This is of course not very realistic, but for the sake of the examples below, it’s easiest to use

some round numbers.

5.2.2 Step 2: adding Contract campaign The same advertiser now asks us to run another campaign, but this time it is not a remnant

campaign but rather it is a Contract campaign, with the following characteristics:

• The campaign has a duration of 10 days (it starts on day 1 of next month, and it ends on

day 10 of next month).

• It has a CPM pricing model, with a price of $1 per 1,000 impressions, and the budget for

the campaign is $ 10.

• Given the budget and CPM pricing, there are 10,000 impressions booked.

• The campaign has a priority of 5.

There is just one ad in this campaign, and it has a weight of 10.

5 In OpenX 2.6 and earlier, the term ‘high priority campaign’ was used, this was changed to

‘Contract’ campaign starting with version 2.8. 6 In OpenX 2.6 and earlier, a remnant campaign was called ‘low priority’ 7 The default weight of a new campaign in OpenX is 1, but any value between 0 and 127 can

be entered 8 Again, the default weight of an ad is 1, but it can be anything between 0 and 127

Page 25: OpenX Reference Guide

OpenX Reference Guide - Priorities, weights and probabilities OpenX 2.8

Last updated August 2010 page 21 of 32

It is important to note at this point that there is a fundamental difference between remnant

campaigns and contract campaigns:

• A remnant campaign has a weight, which is used to determine how often ads from that

campaign are displayed relative to other remnant campaigns;

• A contract campaign has a priority, which is used by OpenX to decide what ads from

contract campaigns should be shown, in cases where there are multiple contract

campaigns.

When the first day of the campaign arrives, this is how OpenX will work:

• The system knows that the zone is being displayed 10,000 times per day, and it even

knows the average distribution of those 10,000 zone impressions over the course of a 24

hour period (fewer during the night and more during the day and evening).

• Since the ad from the Contract campaign is supposed to be displayed 10,000 in a 10 day

period, it comes down to 1,000 impressions per day.

• The remaining 9,000 impressions per day will be assigned to the remnant campaign.

During the day, when the maintenance script runs, OpenX will monitor the delivery of the ad

from the contract campaign and compare the actual delivery statistics with what it was

expecting based on the recent history of the zone. If it finds that the ad from the contract

campaign is under or over delivering, it will adjust the probability for the ad for a few hours,

in an effort to reach the target of 1,000 impressions for the day. The overall goal is to get as

close as possible to the 10,000 booked impressions at the end of the 10 day campaign.

When several Contract campaigns are competing for the available traffic from the website(s),

a situation might occur where the summed number of impressions exceeds the overall website

traffic. OpenX Ad Server will then give every contract campaign a share of the available

impressions generated, using priorities as the guide. The higher a campaign’s priority, the

more likely it is to have it’s required number of impressions filled.

5.3 Scenario 3: Topping it off with Exclusive campaigns

In the situation described at the end of the last paragraph (several contract campaigns

competing with each other for overall impressions too low to deliver all), the third type of

campaign will come into play. Setting a campaign to Exclusive will mean that this campaign

will have its impressions delivered, overpowering regular contract campaigns.

Here is an example where Exclusive campaigns come in handy:

• Let’s assume there is a site with just a single zone, a leaderboard across the top of all

pages. The site is receiving 1,000,000 page views per day, and therefore it is generating

1,000,000 zone impressions per day.

• There are four contract campaigns that have all been linked to this zone, and each of

them has a targeted number of impressions set to 500,000 per day. All four contract

campaigns have their priority set at 5.

• As a result, these four contract campaigns are aiming to deliver 2,000,000 impressions

per day, which is double the volume that is available from the site.

• OpenX Ad Server will give each of these four campaigns a fair share of the available

impression, so 250,000 each.

Page 26: OpenX Reference Guide

OpenX Reference Guide - Priorities, weights and probabilities OpenX 2.8

Last updated August 2010 page 22 of 32

Now if one of these four contract campaigns is set to Contract (Exclusive), with all other

settings left as they were, the scenario will change:

• The Exclusive campaign will deliver 500,000 ad impressions.

• The remaining 500,000 zone impressions will be shared by the three Contract campaigns,

given each 500,000 divided by 3 equals 166,667 impressions approximately.

Page 27: OpenX Reference Guide

OpenX Reference Guide - Targeting ads: delivery limitations, channels and capping OpenX 2.8

Last updated August 2010 page 23 of 32

6 Targeting ads: delivery limitations, channels and capping

Every ad (OpenX Ad Server calls them banners) can have a number of settings and options

that determine how, where and when the ad will be allowed to display. This chapter

describes these so called delivery options and limitations.

Everything related to capping and delivery limitations is presented on a single tab called

“Delivery Options”, right next to the “Banner Properties” tab.

6.1 Capping

Capping means limiting the number of ad views for an ad to a specific value:

• The number of banner views can be limited for the lifetime of the campaign;

• The number of banner views can also be limited per session (visit);

Both of these view counters can also be reset after a period of time expressed in hours,

minutes and seconds.

6.2 Targeting

In the online advertising industry, targeting refers to the practice where an ad is not just

displayed anywhere and everywhere, but only when specific conditions occur. Since this limits

the situation when the ad can be delivered, OpenX Ad Server calls this ‘delivery limitations’.

OpenX Ad Server presents the available types of delivery limitations in a list:

Page 28: OpenX Reference Guide

OpenX Reference Guide - Targeting ads: delivery limitations, channels and capping OpenX 2.8

Last updated August 2010 page 24 of 32

There are four different sets of targeting mechanisms:

• Client

• Geo

• Site

• Time

6.2.1 Client (computer and browser) The word ‘Client’ is a technical term from internet technology that refers to everything that

has to do with the computer and the web browser that a person is using when visiting a site.

• Client – Domain: using this option the ad can be delivered to just those users browsing

the internet from a specific domain (for instance: only when the visitor uses a computer

that is connected through the example.com domain name). Note: this is not the same as

the domain name of the website!

• Client – IP Address: enables the advertising manager to show ads only to specific IP

addresses.

• Client – Language: every browser sends the preferred language as part of the request for

a page. Ads can be targeted to the language preferred language set in the browser.

• Client – User agent: a browser used to visit a website identifies itself, by make and

version. Common user agents are: MSIE for Microsoft Internet Explorer , Safari for Apple’s

Safari browser and Mozilla for Firefox.

6.2.2 Geographic targeting The world ‘Geo’ refers to the type of delivery limitations where the geographic location of

the person visiting the site is used for targeting. Depending on the geo-targeting features

available and enabled in the OpenX Ad Server, targeting by country, by city, by continent,

region, province, state or DMA can be available.

6.2.3 Site targeting The set of delivery limitations grouped as ‘Site’ are used to respond to specific information

coming from or about the website where the ads are displaying.

• Site – Channel: see the next paragraph for a description of channels, also known as

‘targeting channels’.

• Site – Page URL: this delivery limitation can be used to restrict ad delivery to a page or

page that has a specific word in its URL, or perhaps matches an exact URL like the

website’s homepage.

• Site – Source and Site – Variable are delivery limitations that respond to information

available in the invocation code on the website. This is an advanced topic that will be

addressed in a separate chapter.

Page 29: OpenX Reference Guide

OpenX Reference Guide - Targeting ads: delivery limitations, channels and capping OpenX 2.8

Last updated August 2010 page 25 of 32

6.2.4 Time targeting The delivery limitations grouped as ‘Time’ can be used to restrict ad delivery based on time

and date settings.

• Time – Date: an ad will only be delivered is a date condition is mate.

• Time – Day of week: the ad will only be delivered on specific days of the week

• Time – Hour of day: ad delivery is restricted based on the hour of the day, with each of

the 24 hours available separately.

6.2.5 Combining delivery limitations Each ad can have multiple delivery limitations, and they can be combined using the AND and

OR operators. Using two delivery limitations with the ‘AND’ operator means that both

conditions will have to be met for the ad to be delivered. The ‘OR’ parameter, on the other

hand, means that just one of the two conditions has to be met.

6.3 Targeting channels

Targeting channels are an efficient way of defining named sets of delivery limitations that

can be used on a banner. Instead of having to define common delivery limitations for every

ad, the ad server can have a targeting channel that can be applied to the ad.

Once a targeting channel has been applied to several ads, making a change to the targeting

channel automatically applies to all of these ads.

Targeting channels can be created at two levels:

• For the system as a whole: these can be found by going to the “Inventory” tab and then

clicking the “Targeting Channels” link in the left hand column.

These targeting channels, once defined, can be used on any ad in the system.

• For a specific website: These can be found by clicking the ‘Targeting channels’ link on

any line in the overview of Websites shown in the “Inventory” tab.

Site-specific targeting channels can only be used for a banner when the campaign that

the banner belongs to has been linked to any of the zones of that website.

For targeting channels, the targeting options available are:

• Client

• Geo

• Site

Page 30: OpenX Reference Guide

OpenX Reference Guide - Targeting ads: delivery limitations, channels and capping OpenX 2.8

Last updated August 2010 page 26 of 32

Unfortunately, time and day targeting are not available when working with targeting

channels.

Once targeting channels have been defined, they can be applied to a banner by selecting the

‘Site- Channel’ option. Then a list of available targeting channels will be displayed. Checking

the checkbox in front of a channel and saving the changes will mean the targeting channel is

active for that ad.

Page 31: OpenX Reference Guide

OpenX Reference Guide - Measuring conversions OpenX 2.8

Last updated August 2010 page 27 of 32

7 Measuring conversions

This chapter provides a short description of the way OpenX Ad Server can measure

conversions. A more detailed version of this chapter will be written at a later stage.

7.1 Introducing conversion tracking

Conversions are events that take place on a website owned by an advertiser, after the person

visiting the site has clicked an ad and was sent to the advertiser’s site. A conversion could be

a signup for a newsletter subscription, application for membership, requesting a lead or

making a purchase.

7.2 How does OpenX Ad Server measure conversions

The occurrence of a conversion can be tracked and reported in OpenX Ad Server statistics.

This tracking is performed by a technique called ‘trackers’.

Here is a short workflow of conversion measurement using trackers:

• A visitor of the site sees an ad on a page, and is interested in the product or service

offered through the ad. The fact that the ad was displayed is recorded by OpenX Ad

Server and reported as an impression.

• The visitor clicks the ad and OpenX Ad Server sends the visitor to the destination URL

specified with the ad (most people call this the landing page). The fact that the ad was

clicked is also recorded by OpenX Ad Server and is reported as a click.

• After arriving on the landing page, the visitor studies the offer and makes a decision to

act (or not). Acting in this case usually means filling out a form to sign up for a

newsletter, or to request a quote, or to purchase a product or service.

• After the visitor has completed the action, a final page (usually called the ‘thank-you

page’) is displayed.

• The tracker that was created in OpenX Ad Server has a little snippet of HTML code

associated with it. This snippet of code is executed as part of the thank you page on the

advertiser’s website. It results in the display of a small invisible tracking pixel. The fact

that this tracking pixel is displayed is recorded by OpenX Ad Server.

The use of trackers from OpenX Ad Server requires the cooperation of the advertiser, because

they have to place the tracking pixel on their thank you page. In some cases advertisers don’t

have the technical skills or the man power to do the work, in other cases advertiser have

change management procedures that take ages. There are also situations where it is just

impossible, for instance it will never be possible to insert a tracking pixel from a small site

owner on the thank-you page for Amazon.com or iTunes.

Tracking pixels can send back more data than just the fact that a conversion occurred. They

can also report on:

• The number of items in a sale

• The total sale amount (called ‘basket value’ on OpenX Ad Server).

A tracker, once created, can be linked to one or more campaigns. So a single tracking pixel,

inserted into an advertiser’s website, can be used to track the performance of more than one

campaign.

Page 32: OpenX Reference Guide

OpenX Reference Guide - Section 4: OpenX Ad Server for webmasters and IT staff OpenX 2.8

Last updated August 2010 page 28 of 32

Section 4: OpenX Ad Server for webmasters and IT staff

Page 33: OpenX Reference Guide

OpenX Reference Guide - Integrating OpenX with your website OpenX 2.8

Last updated August 2010 page 29 of 32

8 Integrating OpenX with your website

The integration of OpenX in a website is done by placing what OpenX calls ‘invocation code’

into that website. Nowadays, most websites have a template that determines what all the

pages of the site look like. Templates also define elements that are present on all pages, like

a logo, menu, and the various ad locations.

The term Invocation code can be compared to what other systems call ‘tags’.

8.1 Every zone has a tag

In OpenX 2.4 and earlier, a web master would have to create a piece of invocation code for

every single zone and place it in the template at the appropriate location. OpenX used to

offer various types of invocation code including javascript code and iframe code.

One of the disadvantages of having multiple bits of invocation code on a page was that it

could affect the rendering speed of the webpage. This was especially true when javascript

code was used. Because of the way a browser works, the javascript code only begins to be

executed after all of the page’s source code completed loading. And then the browser would

executed each bit of code individually and in sequence. The result was that visitors would see

the ads appearing one by one. With many zones on the page, it could even mean that the last

ad had not appeared yet, when the visitor had already clicked a link and leave the page.

Another disadvantage of this setup was that the ad server would receive multiple request per

page, one for each zone, in short sequence. It had to start up the complete processing login

of the delivery engine each and every time. This could seriously affect the ad server’s

performance.

8.2 Single page call

Starting with OpenX version 2.6, an new concept was introduced, named ‘singe page call’.

8.2.1 How single page call works It works like this:

• In the <head></head> section of the web page, there is a single line of code that does a

call to the ad server. The call includes a website ID from a known website in the OpenX

Inventory.

• In response, OpenX returns the ads for all of the zones that are associated with that

website ID. The ad content is kept in memory by the browser for later use.

• At the correct locations in the <body></body> section of the web page, there is a little

snippet of code. The code snippet uses the zone ID to identify what zone it is. This code

outputs the ad content that was retrieved at the start of the page and waiting in the

browser’s memory. As a result, the ad content is sent to the visitor’s browser without

there being a need to push a zone request to the ad server.

The OpenX developers have named this ‘single page call’, because every page loading on the

site produces just one call to the ad server.

Page 34: OpenX Reference Guide

OpenX Reference Guide - Integrating OpenX with your website OpenX 2.8

Last updated August 2010 page 30 of 32

The advantages of single page call are:

• The web page will load faster because it doesn’t have to contact the ad server and wait

for the response for every single zone. Instead, there is just one call to the ad server and

then all the ads can but outputted from memory.

• The load on the ad server is reduced because there is only a single call for every web

page loaded by a visitor. The single page call itself is slightly heavier than the traditional

from one zone, but after that there are no more calls. So even with just two zones on a

page, it is beneficial to start using single page call.

8.2.2 Advanced use of single page call As described above, single page call code contains a website ID, which means OpenX

automatically returns the ads for all the zones that belong to that website. However, it is also

possible to have a list of the zones required for a page just before the line of code that

contacts the ad server. When this is the case, OpenX will ignore the website ID and return

only those zones that are listed by the programmer.

This usage of single page call even gives the programmer the ability to name the zones and

then in the body section of the page refer to the zones by name instead of by ID. This makes

it much easier to prevent mistakes from using the wrong ID in the wrong spot on the page.

OpenX calls this ‘named zones’. It is not supported directly from the user interface but it is

documented on the OpenX website.

Finally, when using named zones, the list of zones can actually created several instances of

the zone, each with their own name. This could be used, for example, to process 10 instances

of the same ‘sponsor button’ zone. In OpenX, just one ‘sponsor button’ zone is created, and

all sponsors are linked to that zone. At one point, there could be 25 sponsors. The single page

call code then sets up 10 named instances of that zone, for instance SponsorButton01,

SponsorButton02, and so on. By using the setting “don’t show the same ad again on the same

page”, OpenX will return 10 unique ads from the set of 25 it can choose from.

Page 35: OpenX Reference Guide

OpenX Reference Guide - Integrating OpenX with your website OpenX 2.8

Last updated August 2010 page 31 of 32

8.3 Do’s and don’ts

8.3.1 Don’t use Direct selection The very first version of OpenX was actually called ‘phpAds’ and was released at around the

year 1999. At the time, the only concepts were ‘advertisers’ and ‘banners’. To place the ads

on the pages of a website, a type of invocation code was used called ‘direct selection’. This

type of code is still available, even in version 2.8, for reasons of backward compatibility.

However, the introduction of the concepts of ‘websites’ and ‘zones’ and later with single

page call, a more flexible and much more powerful type of invocation code is now available.

The OpenX developers might even remove Direct selection from the feature list in the future.

8.3.2 Don’t use keywords Direct selection code (see above) had a method for selecting the correct ad, called

‘keywords’. It allowed administrators to assign various keywords to an ad, and then they

could use the keywords in the direct selection code to retrieve the correct ads.

Since it is recommended not to use direct selection, the use of keywords no longer has any

meaning. And the selection mechanism has been replaced by a more powerful feature in the

invocation code from zones, with the introduction of the ‘source’ parameter and the ‘site

variable’ targeting technique (this is described in one of the other chapters).

Page 36: OpenX Reference Guide

OpenX Reference Guide - About the author OpenX 2.8

Last updated August 2010 page 32 of 32

9 About the author

This guide was designed and written by Erik Geurts, an experienced OpenX consultant who

has been helping clients around the world with their OpenX projects since 2003.

More information about his services can be found at www.openxconsultant.com, where a copy

of this guide can be downloaded free of charge.


Recommended