OpenX Tips

As you may have read in the OpenX 2.8.1 release notes:

Zone probabilities are distributed amongst campaigns, independent of the number of banners. OX-3095

This means that it is now possible to divide a zone’s inventory up between the linked campaigns by campaign weight, without having to re-calculate all of the weightings when a new banner is added.

As a result, Tip #8: Understand the banner delivery process has been updated to describe the different delivery process for OpenX releases before and after version 2.8.1.

Why would you need to know what happens inside the OpenX ad server whenever a zone tag is called? Simple — although it’s a little bit technical, understanding the banner delivery process is essential for really getting to grips with banner delivery in OpenX, and is vital background information for a number of other topics.

Although the process below is specific to OpenX 2.8, the process in earlier versions of OpenX is very similar, although slightly less efficient. However, the general principle is the same.

The banner delivery process

It does not matter which zone tag type you use, the banner delivery process pretty much follows the same process. After some initial setup of the environment, the OpenX ad server uses the following process to determine which banner to deliver.

1. Find all of the active banners¹ that are linked to the zone.
2. Are there any active banners linked to the zone that are from Contract (Exclusive) campaigns? If so:
   1. Do any of the linked Contract (Exclusive) campaign banners “fail” delivery limitations?² If so, discard these banners.
   2. Are any of the linked Contract (Exclusive) campaign banners incompatible with the zone tag type?³ If so, discard these banners.
   3. Are there any banners remaining? If so:
      1. Select one of these banners via the campaign weight/banner weight process (see below).
      2. Log a request, using the selected banner ID and the zone ID.
      3. Display the banner.
      4. Log an impression, using the selected banner ID and the zone ID.
3. If this point is reached, then there were no banners from Contract (Exclusive) campaigns that could be displayed.
4. Are there any active banners linked to the zone that are from Contract campaigns? If so:
   1. Do any of the linked Contract campaign banners “fail” delivery limitations? If so, discard these banners.
   2. Are any of the linked Contract campaign banners incompatible with the zone tag type? If so, discard these banners.
   3. Are there any banners remaining? If so:
      1. Possibly select one of these banners via the Contract campaign banner selection process (see below).
      2. If a banner is selected:
         1. Log a request, using the selected banner ID and the zone ID.
         2. Display the banner.
         3. Log an impression, using the selected banner ID and the zone ID.
5. If this point is reached, then there were no banners from Contract (Exclusive) campaigns that could be displayed, and there were either no banners from Contract campaigns that could be displayed or no banner from a Contract campaign was required to be shown.
   
6. Are there any active banners linked to the zone that are from Remnant campaigns? If so:
   1. Do any of the linked Remnant campaign banners “fail” delivery limitations? If so, discard these banners.
   2. Are any of the linked Contract campaign banners incompatible with the zone tag type? If so, discard these banners.
   3. Are there any banners remaining? If so:
      1. Select one of these banners via the campaign weight/banner weight process (see below).
      2. Log a request, using the selected banner ID and the zone ID.
      3. Display the banner.
      4. Log an impression, using the selected banner ID and the zone ID.
7. If this point is reached, then there were no banners from Contract (Exclusive) campaigns that could be displayed, there were either no banners from Contract campaigns that could be displayed or no banner from a Contract campaign was required to be shown, and there were no banners from Remnant campaigns that could be displayed.
8. Is the zone set up via zone chaining to be linked to another zone? If so, re-start the process from the first step, using the new zone.
9. If this point is reached, then there were no banners from Contract (Exclusive) campaigns that could be displayed, there were either no banners from Contract campaigns that could be displayed or no banner from a Contract campaign was required to be shown, there were no banners from Remnant campaigns that could be displayed, and the zone is not set up via zone chaining to be linked to another zone.
   
10. Is a default banner configured? If so:
    1. Log a request, using the selected banner ID and the zone ID.
    2. Display the banner.
    3. Log an impression, using the selected banner ID and the zone ID.
11. If this point is reached, then no banner can be displayed.
12. Display a “blank” 1×1 .gif pixel.

Campaign weight/banner weight process

In the above process, when testing the active Contract (Exclusive) banners, or when testing the active Remnant banners, if there is more than one banner that can be delivered, one of the following processes is used to determine which banner to deliver, depending on the version of OpenX:

OpenX 2.8.1 or greater

1. For every banner in the zone, find the parent campaigns.
2. Sum all of the campaign weights.
3. Generate a random number between 0 and the sum of the campaign weights, and use this random number to select a campaign.
4. For all of the banners in this campaign that are also in the zone, sum all of the banner weights.
5. Generate a random number between 0 and the sum of the banner weights, and use this random number to select a banner.

OpenX 2.8.0 or less

1. For every banner in the zone, take the banner’s weight and multiply it by the campaign weight, to obtain the overall campaign/banner weight.
2. Sum all of the campaign/banner weights for the banners.
3. Divide each banner’s campaign/banner weight by the sum of all of the campaign/banner weights. (This ensures that the sum of the new campaign/banner weights is 1.)
4. Generate a random number between 0 and 1, and use this random number to select a banner, so that banners are delivered with a distribution based on their relative campaign/banner weights.

Contract campaign banner selection process

In the above process, when testing the active Contract banners, if there is more than one banner that can be delivered, the following process is used to determine which banner to deliver:

1. Look at all of the active banners in Contract campaigns that have a Priority Level of 10 (if any):
   1. For every banner, take the pre-calculated priority value and multiply it by the pre-calculated priority factor value.⁴
   2. Sum all of the calculated priority/priority factor values for the banners.
   3. Divide each banner’s priority/priority factor value by the sum of all of the priority/priority factor values. (This ensures that the sum of the new priority/priority factor values is no greater than 1.⁵ )
   4. Generate a random number between 0 and 1, and use this random number to either select a banner, or select no banner.
2. If no banner is selected, then repeat the above process with all of the active banners in Contract campaigns that have a Priority Level of 9, then 8, then 7, etc. all the way down to the active banners in Contract campaigns that have a Priority Level of 1.

Variations to the impressions logging ordering

Certain zone tag types (Image, No Cookie Image, XML-RPC) do not log the impression after displaying the banner — instead, the impression is actually logged immediately after logging the request; that is, before displaying the banner. This is because with these zone tags, it is not possible to deliver a logging beacon.⁶

Phew!

Okay, saying at the start that it was a little bit technical may have been an understatement. However, if you’ve at least managed to get a vague idea of how the delivery process works, The Guru promises that future articles on the OpenX ad server will make a lot more sense…

1. A banner is active when it is in a campaign that currently running, and the banner has not been disabled. [↩]
2. That is, if the banner was actually attempted to be delivered, would it be unable to be shown as a result of any delivery limitations or delivery capping that has been set up for the banner? [↩]
3. For example, HTML banners cannot be delivered when using the Image or No Cookie Image Tags, which can only deliver image banners. [↩]
4. These values come from the Maintenance Prioritization Engine. [↩]
5. It is possible for the sum of the new priority/priority factor values to be less than one, if the Maintenance Prioritization Engine has determined that the Contract campaigns do not require all of the available impressions to be used in order to meet the campaign targets. [↩]
6. A logging beacon is a 1×1 .gif pixel that is delivered separately from, and after, a banner, so that if the banner is not actually delivered to the user’s web page, the banner impression is not counted. [↩]