Especially when it comes to OpenX API – there is almost nothing out there but a few blog posts and outdated code samples. We would really like to share our experiences (both positive and negative) with OpenX API as we strongly believe that the OpenX platform should remain easy accessible and open to the public.

I strongly agree with this and that’s why I wanted to draw some extra attention to these articles.

Here is a run down of the articles in the series:

• The first article is an introduction to the OpenX Source API, with some background information on why it was developed and how to connect with the API.
• In the second article, the examples are mostly about using the OpenX Source API to work with advertisers (creating, modifying, retrieving statistics).
• The third article explains how the eCPM can be calculated for campaigns with different pricing models (like CPM, CPC and CPA), as an introduction for a later article about managing campaigns via the OpenX Source API.

It is highly recommended to install this update as soon as possible, because it contains a number of security fixes.

There is no news about this new release on the OpenX community forums or blog, as of yet. The readme file that comes with the downloaded file does not contain any specific information as to the nature of the security issues that have been fixed. However, a quick comparison of the source code of version 2.8.7 and version 2.8.8 reveals that there are multiple changes in the API, which seems to match reports about the origins of many hacking incidents that occurred these past few months.

You can download OpenX Source version 2.8.8 from the OpenX website.

Update November 8, 2011: Since many people are asking me for tips on how to upgrade their OpenX Source software, I’d like to point to an blog post I published in November, 2010: How to upgrade OpenX Source Ad Server software.

Update December 2nd, 2011: Yesterday, a post has been added to the OpenX official company blog, officially announcing this security fix release. It also specifically mentions that the security fixes relate to issues found in OpenX Source version 2.8.7, which indicates that versions 2.8.6 and earlier are not affected. However, it is always a good idea to upgrade to the most recent version available. Read the post “Security matters” on the OpenX blog for more information.

How can you detect if your OpenX has been hacked?

There may be several ways to first find out about potential problems:

• You might get mails or messages from people visiting your site(s) telling you that their virus scanner or malware protection has alerted them to a problem;
• If the hack happened more than a few days ago, Google may have picked up on it and penalized your site by adding a malware warning to it. Visitors using the Google Toolbar in their browser will see a very clear warning on their screen, and you will receive an alert through the Google Webmaster Tools if you use that service;
• You might find that when you are working in your ad server console you suddenly see a field asking you to enter a password (which you should NOT do!);

First things first: protect your site visitors

If you anticipate that it will take you longer than a few minutes to clean and fix your system, then it might be wise to protect your site visitors from being exposed to the malicious code through your banner ads. One way to do this in a very quick and dirty way is to temporarily rename the folder where your OpenX system is installed. So if your ad server is at www.example.com/openx/ you could rename it to www.example.com/brokenx/. This is not an elegant measure as it will result in ’404 page not found’ errors for every single ad request, but at least your site visitors are now safe.

Next: protect your own computer. Do not log in on your OpenX but read below and find and clean all infections before restoring the ad server to a working state.

How did the hack work?

At a high level, the hack will probably have resulted in the following things that need to be ‘cleaned’:

• one or more new administrator users will have been added to the ox_users table in the database that holds your OpenX data. See below for an example and cleanup instructions.
• probably using these admin usernames, the hacker will then have been able to alter some of the plugins that are part of the core OpenX system;
• one of the altered files will enable the hacker to access the database, completely circumventing the OpenX login process;
• in the database, the hacker will have added code or altered code in the ‘append’ and/or prepend columns of the ox_banners or ox_zones tables (or both).

What needs to be done to clean your OpenX system?

If you do not know how to work with tools like an FTP client, or the database management tool phpMyAdmin, you should find an experienced person to assist you. You may be able to get help from your hosting company or their help desk.

Here’s what you must do:

• Remove the malicious users from the ox_users table (see below)
• Remove the malicious code form the ox_banners and ox_zones tables (more detailed instructions in an update of this article later)
• Search the plugins folder and sub folders, looking for files that have been added or altered recently (more information in an update later)
• Protect your OpenX installation to prevent future hacking attempts
• Upgrade your OpenX Source software to the most recent version

Removing malicious users

The hacks usually start in a way that’s easy to spot, but only if you’re specifically looking for it. It is not yet exactly known how, but hackers have found a way to add administrator users to the ‘ox_users’ table. Many cases have been seen where the administrator users were created weeks or months before the hackers actually come back to use them and inject malicious code into the banners and/or zones, or make alterations to existing plugins.

Using a tool like phpMyAdmin or with the help of a system administrator or your hosting company, closely examine the ox_users table and look for records that look like this:

Malicious entries in the ox_users table indicate a hacker has gained access to your system at system administrator level

In this screen shot, I’ve masked the legitimate users and all encrypted passwords. What you’ll notice is that in this particular case, four records have been added that all have contact name “Administrator” (just like the real administrator), and the user name is a variation on the admin user name. Also, you’ll notice that there is no e-mail address for these four rogue users, even though normally you can not add a user through the OpenX user interface without providing an e-mail address. The hackers will have added encrypted passwords that they know, and as a result of that, they will have full administrator access to your system at any given time.

Obviously, you should delete any of these malicious users as soon as you find them.

Some preventative measures if you haven’t been hacked

• Secure your OpenX admin panels by adding an .htaccess to the www/admin folder that blocks access to anyone except known IP address (an example to follow later).
• Change all passwords for all OpenX users and change the password you use for FTP access.
• Use a good virus scanner and update it regularly, because even when working in the OpenX admin, you might be confronted with the malicious code added to banners or zones.
• Run a full malware scan on your computer(s) that you use to work in OpenX, because the malicious code may have installed a key logger or trojan.

More information

There is some information and cleanup instructions in an article here, but this article is more than a year old and the hacks have become more sophisticated since that time. The article suggest to upgrade to the latest version and then to clean the malicious code. I strongly recommend to clean everything first and only then to start planning an upgrade. Unfortunately, we’ve found this week that even the latest release v2.8.7 of OpenX Source seems to be vulnerable to this new round of attacks.

Share!

Please feel free to share this article with others, and please post comments, tips and suggestions below.

What is DoubleClick DART?

Most often you will encounter tags from a system called DoubleClick DART for Advertisers. DART is a special type of ad server that’s used by advertisers. Another system is DoubleClick for Publishers, but it is less likely that you’ll receive those tags. DoubleClick is a company that specializes in ad server technology, owned by Google. It is a commercial (and paid) competitor for OpenX Source, but at the technical level these products all work together very well.

Create a new banner

Just like always, you will first have to create the new banner by clicking the “Add new banner” link at the top of the list of banners of your campaign. This will bring up the “Add new banner” screen.

Select OpenX Generic HTML banner

The first thing you need to do is to select the correct type of banner. OpenX Source offers you a choice of multiple banner types. They include:

• Upload a local banner to the webserver
• Upload a local banner to the database
• Link to an external banner
• OpenX Generic HTML Banner
• OpenX Generic Text Banner

Not all of these options may be available in your installation. We will need “OpenX Generic HTML Banner“. If this is not available, you should contact your OpenX system administrator.

As soon as you’ve selected OpenX Generic HTML Banner, the layout of the new banner screen changes to present the relevant fields and options.

Enter banner details and paste the tag

Now all you need to do is to enter the relevant banner details:

• Give the banner a name, and make sure the name is a short but accurate description of the banner
• Paste the DART tag into the big box called ‘banner code‘. More information about which of the various tag types provided you should use is in the next paragraph.
• In the selection list below the banner code, next to “Alter HTML to enable click tracking for:“, make sure you select the option “Rich Media – DoubleClick”. This will enable OpenX to correctly interpret the tag, including the ability to count clicks on the banner in OpenX. The wording is a bit misleading, OpenX will not actually alter the HTML code of the tag, but it will ad tiny bit of extra code during delivery to enable click counting. This is perfectly normal, all ad servers do this.
• The fields for Destination URL and Target can be left blank, all the required information for that is embedded in the DART tag.
• You will have to enter the width and height of the ad, so that OpenX understands what the dimensions are and display it only in zones of the same size.

Which DART tag to use: JavaScript

Advertisers often send a text file containing various types of DART tags. These text files are automatically generated by the DART software. The types provides often include:

• Iframe/JavaScript Tag
• Internal Redirect Tags (for use in the DFP – DoubleClick for Publishers ad server only)
• Javascript Tag

For use in an OpenX Source ad server, the version to select is “JavaScript“.

Just copy and paste the code provided by the advertiser, it’s usually the very last of the various types of tags provided.

Save and preview the banner

Once you’ve pasted in the tag and made sure all the other settings and fields have been entered correctly, save the banner by clicking the “Save changes” button. You will be returned to the list of banners of the campaign.

By clicking the name of the new banner, the banner properties screen will be displayed. At the top of this screen there should be a preview of the newly created banner: the ad that is displayed when the DART tag is executed.

We have a client that has asked if they can place an ad in our network and include a 1×1 tracking pixel for third party verification of delivery.

Is this something that can be done in OpenX? If not, is there a way to utilize third party ad server tags in OpenX, so that you would load the ad tags in the system rather than the ad itself?

I replied to Randall: Yes, this is possible. OpenX Source v2.8 has a nice feature that allows you to send additional HTML code along with the ad itself. This can be used to include a third-party pixel for ad delivery verification, but that’s just one of the scenarios.

Managing banners in OpenX

After a banner has been created and saved in OpenX, a set of tabs will appear that provide access to various features.

OpenX - tabs for a banner give access to various features

• Banner Properties is a page where you can view and adjust the banner itself, like uploading a new banner image or changing the destination page’s URL.
• Delivery Options is the page where you can define various ‘rules’ to determine where, how and when the banner can be displayed. This is often referred to as “setting the targeting of the banner”.
• Linked Zones is the page where you can determine in which zone(s) the banner is supposed to be displayed on your website(s).
• Advanced is a page for entering code snippets that will be delivered alongside the banner itself.

Adding code to banners in OpenX

OpenX advanced banner feature: adding prepend and append code (click to enlarge)

To add any kind of code, including third-party delivery verification pixels, just click the Advanced tab for any banner you need to modify. Just beneath the preview of the ad, you will see two large boxes, initially completely empty, grouped together under the heading ‘Append and prepend settings‘.

The first box enables you to enter code that should be sent to the visitor’s browser before the actual ad (the software calls this prepend), the second box is for code that needs to be sent along after the ad (this is called append).

Don’t forget to save the changes after you’ve pasted in the extra code.

Use cases for prepend and append code

One common scenario for the ability to prepend and append code to a banner is to include a third-party measurement pixel that allows the advertiser to count how often the ad has been displayed. They might want to do that in a situation where they don’t have access to your ad server as a user, but also in situations where they’ve got their ad displaying on a variety of sites and publisher properties, and want to have one comprehensive impression count in their own ad server.

Another use case is when the ad requires some additional code for it to work, for example loading a JavaScript library.

In case of third-party ad delivery verification code, it is recommended by IAB guide lines to append that code, so that it is displayed after the actual banner, allowing for a more reliable measurement of the ad’s delivery onto a web page.

Extra tip: Adding code to zones

OpenX Source v2.8 not only allows the user to add code to banners but also to zones. For any zone there is also an ‘Advanced’ tab, also with a box for prepend and append code. If you use this on a zone, please take note of the fact that this code will be added to any banner displayed through the zone.

Setting up a list of zones

The biggest disadvantage of the Single Page Call code that the OpenX software generates is that it automatically creates ad requests for every single zone that is defined for a given website. So if you have 15 zones (5 for your homepage, 5 for your article pages and 5 more for your forum), there is a waste of 10 zone request for every page loading in the browser. Fortunately, it’s simple to avoid this, by creating a list of zones that you need. Here’s the basic syntax:

<script type='text/javascript'><!--// <![CDATA[
var OA_zones = {
'zone_name_1' : X,
'zone_name_2' : Y,
'zone_name_3' : Z
}
// ]]> --></script>

Javascript programmers call this an “array”. It consists of a few lines (perhaps even as many as 10), and each line has a name and an associated zone ID.

• The names have to be unique in the list, and they don’t have to match the names of the zones inside OpenX. I always try to select names that describe where the zone will be displayed on the page. Keep in mind that these names are case sensitive. To avoid confusion, I always use lower case, and underscore (_) characters instead of spaces.
• The zone IDs X, Y and Z will have to match the IDs that OpenX has assigned to the zones when you created them.
• Each line ends with a comma, separating it from the next line. Of course, there should not be a comma after the zone ID of the last line.

Here is a code sample for the case I described in the first article, with a leaderboard zone at the top of the pages next to the logo, 3 medium rectangle zones in the sidebar and 1 full banner zone at the bottom of the page:

<script type='text/javascript'><!--// <![CDATA[
var OA_zones = {
'masthead_leaderboard' : 1,
'sidebar_medium_rectangle_1' : 2,
'sidebar_medium_rectangle_2' : 3,
'sidebar_medium_rectangle_3' : 4,
'bottom_full_banner' : 5
}
// ]]> --></script>

These lines of code don’t “do” by themselves, they are just preparation for the next step. An array called “OA_zones” has been created, and this will trigger the single page call to process only these zones and ignore all the other zones.

Advanced Single Page Call request code

The ad request connects that connects to the OpenX Ad Server is very similar to the basic implementation. Since the zones we need have already been listed, we can even leave out the site ID. Let’s have a look at the differences. The basic code looks like this:

<!-- Generated by OpenX 2.8 -->
<script type='text/javascript'
src='http://www.example.com/openx/www/delivery/spcjs.php?id=x'></script>

For the advanced implementation, we don’t need the id=x parameter, so we end up with:

<script type='text/javascript'
src='http://www.example.com/openx/www/delivery/spcjs.php'></script>

As you can see, almost identical, in fact even a bit less code.

Single page call code for <body> of web page

The code that goes into the body section of the web pages is very similar to the basic variety, the only difference is that you’ll no longer be referencing the zones by ID but instead by the name you assigned to it earlier. Here is the basic syntax for the code:

<script type='text/javascript'><!--// <![CDATA[
OA_show('zone_name_1');
// ]]> --></script>

Make sure you use the exact same zone names as used in the list of zones, and enclose the zone names with two ‘ (quote) characters.

The <noscript>…</noscript>component of the code can be left out, in my opinion, since most websites nowadays display rich media advertising that won’t work in ‘noscript’ anyway.

For our example, the code snippet for the masthead_leaderboard zone would look like:

<script type='text/javascript'><!--// <![CDATA[
OA_show('masthead_leaderboard');
// ]]> --></script>

One additional benefit of this approach of naming zones is that you will find it much easier to understand the web page code in the future when you need to work on it again, because the zone names tell you exactly what they are.

Named zones single page call: how it works

When the browser loads a page with this advanced variety of single page call, this is what happens in sequence:

• The browser finds and executes the named zones code in the <head>, and as a result it creates an array called “OA_zones” in browser memory, with information for the zones needed.
• The browser then finds and executes the single page call code, also in the <head>. OpenX recognizes that there is an “OA_zones” array and processes the ad requests for each of the zones listed in the array. For each of the zones, the ad that is selected by the ad server is stored in browser memory. If enabled, OpenX counts these ad requests for the statistics.
• When the browser encounters the “OA_show()” code with a pre-defined zone name in the <body>, it outputs the ad that was selected in the <head> during the single page call. This is repeated for each occurrence of the “OA_show()” code. The ad comes with the code for recording the impression of the ad through a small and invisible beacon image.

Next article: using one zone multiple times on a page

In the next article in this series, I will discuss how you can use a variation of the named zones array to display multiple instances of the same zone, but still with a different ad in each instance.

I would like to know if there is any possibility to serve two floaters with different sizes (250×250 and 500×500) in the same zone?

Here is what I wrote back to Milan:

I think what you need is the fact that you can specify a custom size of * and * for a zone, making any ad size fit in it.

Specifying a custom zone height and witdh

If you go to a zone’s Properties page in the OpenX interface, you see that can specify the size of the zone. Initially, the system shows you the standard sizes as defined by the IAB, but the very last entry in the list enables you to enter a custom size by hand.

Once you’ve done that, you can enter a set of numbers by hand, but you can even enter * and * wildcards for the size:

Once you’ve saved the changes, you can link any size banner to this zone, they will always fit.

One think to keep in mind though, is that if you use such a flexible zone in a web page, it could produce odd results. Just imagine what would happen if you attempt to display a 160×600 wide sky scraper banner in space on the page that was designed for a 728×90 leaderboard!

I’m also going to discuss some of the disadvantages of this default implementation. This is not because I want to discourage you from using single page call, but because I want to encourage you to also read the next article in this series that explain how the masters do it.

Where to find OpenX Single Page Call code?

Just like with the better known types of invocation code (JavaScript for example), OpenX will generate the basic code setup for you. Here’s how to get started:

• Log in on your OpenX system like you normally would and go to the “Inventory” tab.
• Next, click the “Websites” link in the left menu column.
• You’ll see your list of existing websites (there might be just one in your case).
• Click the name of the site you need to generate the code for.
• The properties of the site will be displayed, but there is also an often overlooked tab labeled “Invocation Code”, and that’s the one you should click.
• OpenX will now display a screen with various settings and parameters (I will discuss them later), and a “Generate” button.

The position of the “Invocation Code” tab, next to the website properties, is probably the main reason why so few people know about Single Page Call. Traditionally, we all taught ourselves to go to the Zones link, find the zone we were dealing with and go to that zone’s invocation code generation screen. The location in the navigation for the Single Page Call code generation is logical, but unexpected for most people. If only the designers of OpenX v2.8 had thought of putting a reminder in the old place to at least alert people about the new feature!

Now that you’ve found where to find the Single Page Call code, let’s explore what it looks like.

Structure of OpenX Single Page Call Code

When you press the “Generate” button (leaving all the settings at their default values), OpenX will open a new window and display the single page call code there. You will notice that it consists of two distinct components:

• A few lines of code that are supposed to be placed in the ‘head’ section of the webpage
• A few lines of code, repeated for every zone you have, that are supposed to be placed in the ‘body’ section of the webpage.

Single page call code for <head> of web page

The first piece of code, called the “Header Script” by OpenX, actually consists of just one line of active code, and one comment line:

<!-- Generated by OpenX 2.8 -->
<script type='text/javascript'
src='http://www.example.com/openx/www/delivery/spcjs.php?id=x'></script>

It is recommended to paste the code, without making any changes to it for the time being, just before the closing tag of the ‘head’ section.

Single page call code for <body> of web page

For every zone that you’ve created for the site being worked on here, you will also get a few lines of code, looking like this:

<script type='text/javascript'><!--// <![CDATA[
    /* [idy] OpenX zone */
    OA_show(y);
// ]]> --></script><noscript><a target='_blank'
href='http://www.example.com/openx/www/delivery/ck.php?n=a2ad772'><img border='0' alt=''
src='http://www.example.com/openx/www/delivery/avw.php?zoneid=y&amp;n=a2ad772'
/></a></noscript>

I’ve had to edit this code slightly by inserting a few line breaks to make it fit in the page width of my blog, but in general it is recommended to leave the generated code completely unaltered.

This snippet of code needs to go at the exact position in the ‘body’ section of your web page where the ad is supposed to show up.

How OpenX Single Page Call works

When a web browser receives the code and executes it, it will do a call to a program called ‘spc.php’ (sps is short for Single Page Call). The parameter id=x will have a value for x representing the ID of the site that you’ve selected in the earlier step. OpenX will return an ad for every zone that it knows about for the site referenced by x.

This is where the name ‘single page call’ comes from. Instead of doing a separate call for each zone, this code will do a single call for each page, and retrieve all the ads it needs. These ads are stored in the browsers memory for the time being.

When it’s time to display the ad, in the ‘body’ section of your page, the ad is already available in memory of the browser, and will be displayed almost instantly.

Disadvantages of the ‘out of the box’ code

While the standard code that OpenX generates for you will work just fine, there are a few things to keep in mind:

• When you have several zones defined for a site in your OpenX installation, but you’re not using all of those zones on a given page, there is an inefficiency in the default code generated. OpenX will retrieve the ads for all zones and store them in browser memory, even if you don’t really need them.
• The code being generated has a lot of comments and superfluous elements in it. While informative for a web developer, you don’t actually need to paste it all into the web page. The smaller the code of the site, the faster the site as a whole will be.

Next article: how to make Single Page Call even smarter

In the next article in this series, I will discuss several ways to get even more benefit from the Single Page Call technique, by cleverly calling not even all zones but just the zones that are actually needed for the page being created.

In this article, I will explain the benefits of using the Single Page Call tags in your site, leading up to more articles that will have detailed instructions on how to switch from traditional invocation code to the advanced single page call technique.

Traditional Javascript invocation code from OpenX

Let’s assume you have a templated website that has 5 ad zones on every page: a 728×90 leaderboard zone at the top next to the logo, three 300×250 medium rectangle zones in the right side bar and a 468×60 full banner zone at the bottom of the page. For each of these zones, there is a snippet of javascript code that OpenX generates for you automatically.

When a visitor loads the web page, the browser receives the HTML code for that page, and the browser subsequently executes the 5 javascript snippets, one for each of the zones. As a consequence, loading one page triggers 5 calls to your ad server, and possibly another 5 calls to retrieve the banner images and 5 calls to the impression logging pixel, resulting in a significant amount of time waiting for those ads to appear and the page to complete rendering.

What is OpenX Single Page Call?

When you implement the Single Page Call technique that OpenX offers, you replace the 5 javascript snippets mentioned above with just one call to the ad server to retrieve all 5 ad zone. The output of the ad server is stored in memory and then displayed in the web page at the right positions.

Obviously, if you serve image or Flash ads, there will still be 5 requests for banner image files, and there will also be the 5 impression logging pixel calls. But the most time consuming part, the actual ad requests, has been reduced from 5 calls to just 1 call.

Advantages of OpenX Single Page Call

Tests have shown that there are multiple technical advantages to Single Page Call:

• The time needed to load the web page will be reduced significantly, because there is only one ad request that needs to be processed by OpenX. This takes slightly longer than a traditional javascript code snippet, but after that all ads are already available in memory. In the 5 zone example described above, the total time that the browser spends waiting for the ad server will be reduced by about 75%.
• Since the OpenX Ad Server is no longer being hit by multiple requests for each page loading, but just one very efficient ad request per page, the stress on the ad server will also be reduced significantly, which means you’ll be able to process more ad requests and impressions with your existing hardware or hosting plan.

Benefits of OpenX Single Page Call

Site visitors will enjoy the improved loading speed of the web pages, which is a bonus in the ongoing battle for visitors and page views. A faster site means happy users that often turn into frequent, loyal visitors.

Site owners will also like the speed improvements of their sites, because of the focus that search engines like Google put on speed nowadays. Having a faster site means getting a higher ranking in the search engine results pages.

System administrators love the side effects of the single page call, because their hardware or virtual servers will be used more efficiently, resulting in cost savings

Additional benefits

In addition to these technical benefits, there are also several functional benefits, which include the ability to incorporate advanced targeting parameters into the single page call code, and the ability to request mutliple instances of the same zone on a given page.

Next article: how to implement OpenX Single Page Call

In the next article, I will describe the basics of implementing the Single Page Call code on a web site.

Note: Single Page Call is a technique available in version 2.8 of the OpenX Ad Server software, although it has been introduced in earlier versions. The new OpenX Enterprise v3.0 software has a similar feature but it goes by a different name.