Place Ads Precisely with OpenAds

OpenAds, formerly known as PhpAds, is an ad management server that many people are using to display and control ad blocks on their web sites. My site Ask Leo! used OpenAds to serve up ads, including both Google's Adsense as well as direct purchase advertising.

The "problem" is that OpenAds doesn't natively support the level of ad placement that I'm looking for. However things like that don't always stop me. This article describes the approach I've taken using OpenAds to place ads in my MovableType generated pages:

• in specific articles
• on specific pre-defined positions on a page
• any combination of those two
• in any specific category
• site wide

All while maintaining most of OpenAds other features including weighted distribution of ad content.

Now, I do have to throw out a few caveats:

• As I write this I'm running OpenAds 2.0.11. Naturally later versions might add features and functionality that make my efforts redundant.
• I'm going to assume you have at least a basic understanding of OpenAds. It's non trivial, and documenting it is well beyond the scope of this site, and for that matter, my abilities.
• My approach might be stupid. Someone more familiar with OpenAds might well say "you should do it this way" and define something much more elegant. Fair enough. My approach works, though.

With all that butt-covering out of the way, let's dive in.

I don't use Zones.

As I understand it, Zones are OpenAds way of defining areas that ads can appear in. You might define the "above the fold" area of a page is a particular zone, and then later assign ads to run in particular zones.

I couldn't figure out zones.

As far as I could tell, defining a new zone, for say, each individual article or class of article or position on a page, or more importantly, arbitrary combinations of those was beyond me. I couldn't see it as being possible.

So I did it my way.

•

I've defined several conceptual ad block positions. For example what I refer to as "adblock #1" is my prime position, on the left "above the fold" block on every individual entry archive page. "adblock #3" is the newsletter subscribe box you see further down the page, also on every individual archive page. There are others, but I'll focus on those for purposes of example.

And as you know, in MovableType, each entry is given it's own ID number, and can be assigned one or more categories, each with its own label.

Given all that information we have enough to define every ad block on every page or within every category uniquely. The problem is getting that information to OpenAds in a way that will allow it to select ads based on somehow using those as criteria.

Buried deep in the OpenAds documentation is the concept of selection strings, advanced selection strings, and keywords.

The concept is simple: using the ad blocks I've defined plus the entry and category IDs MovableType generates, we define a set of keywords and use them in selection strings that are automatically generated when the pages are built by MovableType. Then by assigning the appropriate keywords to the ad inventory itself we can control with precision exactly what ad gets placed where.

This is best explained with examples.

•

Here's the line from the individual entry archive template on Ask Leo! (it's actually all on one line, but formatted here for readability):

<!--#include VIRTUAL="adblock.php?
  block=1&
  entryid=<$MTEntryID$>&
  catid=<MTEntryCategories glue="|">
          <MTParentCategories glue="|">
            <$MTCategoryLabel dirify="1" $>
          </MTParentCategories>
        </MTEntryCategories>
  " -->      

Adblock.php is a small php script I'll discuss in a moment. What's of interest first are the parameters that it's being passed:

• block is the adblock id number I dreamed up. As I mentioned earlier, ad block #1 is the upper left above-the-fold ad block, and that is where this line is positioned in the individual entry template.

• entryid is exactly that: the entry ID number assigned to the current entry as defined by MovableType.

• catid is a list of the dirified labels for all the categories and subcategories that the current article might be assigned to.

Using the article Who is Leo? as an example, that line is expanded when the page is built into this:

<!--#include VIRTUAL="adblock.php?block=1&entryid=484&catid=administration" -->

In English, that means this line is referring to ad block #1 on the page for entry ID #484 in the category "administration".

However if you view source on that page, that's not at all what you'll see. Adblock.php's job is to generate the Javascript used by OpenAds to place an HTML ad. In the current example, what you'll adblock.php generate is this:

<div class="adblock1">
<script language='JavaScript' type='text/javascript' src='http://ads.pugetsoundsoftware.com/adx.js'></script>
<script language='JavaScript' type='text/javascript'>
<!--
   if (!document.phpAds_used) document.phpAds_used = ',';
   phpAds_random = new String (Math.random()); phpAds_random = phpAds_random.substring(2,11);
   
   document.write ("<" + "script language='JavaScript' type='text/javascript' src='");
   document.write ("http://ads.pugetsoundsoftware.com/adjs.php?n=" + phpAds_random + "&amp;what=");
   document.write ("adblock1,_entryid484|adblock1,_administration|adblock1def");
   document.write ("&amp;exclude=" + document.phpAds_used);
   if (document.referrer)
      document.write ("&amp;referer=" + escape(document.referrer));
   document.write ("'><" + "/script>");
//-->
</script>
</div>

You'll notice that, aside from the <div> I've placed around it for my own CSS needs, this is very similar to the JavaScript code that OpenAds offers you to copy/paste if you use their standard ad placement mechanisms. If you look closely, though, you'll see that the parameters passed to adblock.php have made it into the JavaScript in what is probably an unfamiliar fragment:

   "adblock1,_entryid484|adblock1,_administration|adblock1def"

This is an advanced selection string.

Again, I won't go into the details of selection strings, but to translate this one into English, it says, effectively:

• select ads with both keywords adblock1 and entryid484

• if there aren't any of those, then select ads with both keywords adblock1 and administration

• if there aren't any of those, then select ads with the keyword adblock1def

Now, go have a look at the page in OpenAds where you define or modify an HTML banner ad. You'll notice a little field labeled "Keywords".

This is the point at which you should be excited.

If I want an ad to appear on only in this position and only on this page, then in the ad inventory I assign it the keywords "adblock1" and "entryid484". (Multiple keywords are space separated in OpenAds, so what I'd enter would be "adblock1 entryid484".)

If I want an add to appear in this position and on every page in the category "administration", I assign it the keywords "adblock1" and "administration".

If I want an add to appear site-wide in this ad block position I assign it only the keyword "adblock1".

And finally, I make sure to define an adblock that's to be used if all else fails, and assign that the keyword "adblock1def" for "ad block 1, default". If no other ads are configured to be in this particular spot on this particular page, then it's adblock1def that is show. In my case, adblock1def contains my Google Adsense code.

That's really all there is too it.

•

Summary

1. Come up with a numbering scheme that identifies your ad block positions.

2. Download and modify adblock.php to reference your own installation of the OpenAds ad server.

3. Upload adblock.php to your site

4. Modify your MovableType templates to reference adblock.php where you want adblocks to be placed. Make sure to pass the appropriate block ID that you defined in step 1.

5. Create default HTML ads in OpenAds referencing "adblockXdef" for each adblock that you've defined.

6. Start creating HTML ads to override those defaults using keywords as appropriate.

And finally, download adblock.php (in zip form). Caveat/disclaimer: this code is presented for your use without warranty or guarantee of any sort. For all I know it'll reformat your server, crash your car, give your cat fleas and eat your homework. I don't think it'll do anything of the sort, but I don't guarantee that it won't. By using it, you're assuming all responsibility for whatever it might do.

Oh, and you're free to use it wherever you like. A link back to either http://www.MTTips.com or http://Ask-Leo.com would be appreciated.

Posted September 29, 2007