The Situation

You’ve downloaded Advertwhirl from WordPress plugin gallery after reading its quite impressive description and being blown away by its screenshots.  You go to the settings and are at a loss as to where to even begin.

The vast list of what you can do with Advertwhirl also can make getting started a daunting task.  Most of the settings are fairly intuitive but the meat of Advertwhirl is Ad Campaigns which ironically enough is also the part that gives people the most trouble, ok maybe not so ironic.

The Solution

Read this tutorial.  Seriously, thats it.  It also wouldn’t hurt any to make a test campaign and a test post add an ad slot to the test post with a the short code and play around with the rules and allocations until you have a grasp of things.  If you still have any problems or usage questions you can ask them on the Advertwhirl Support Forum.

The Nuts and Bolts

Terms

Below are a few terms you should be familiar with before diving into the different sections.

• Ad Campaign – A collection of ads and rules which are assigned to ad spots.
• Ad Slot – a spot in a blog page or post where an ad is displayed.
• Ad Source – A source of ad units to fill ad slots with.  This could be a static local banner, Adsense ads, Groupon ads etc…
• Ad Unit – The ad that fills an ad slot during a particular view of a page or post
• Allocation – a collection of ad sources paired with weights which determine the ratio of how the ad sources are rotated to fill an ad slot with an ad unit.
• Rules – rules determine which allocation is selected to fill an ad slot
• RuleSets – Rules are grouped together in rule sets to form complex logic for selecting an allocation

Understanding Campaigns

Campaigns are a collection of ad allocations which share an ad slot(or slots) in your blog.   An example would be a campaign for your Blog with allocations setup for your posts and for each of your guest bloggers.

Understanding Allocations

An allocation is composed of two parts, Rules and Ad Sources.

An allocations rules determine whether it matches a particular view of a blog post or page and whether or not that allocation should be used to determine which add will fill an Ad Slot for that view.

If an allocations Rules match and the allocation is used to fill an ad slot the allocations Ad Sources are used to fill the slot.  The Ad sources are rotated based on their weight.  The rules for rotation are fairly straightforward

1. If twenty ads have been filled (across all campaigns) since the last sponsor ad has filled an ad slot the slot is filled with one of the sponsor ads.
2. If the first Ad Source has filled fewer ads then its weight it is used to fill the ad slot.
3. If the first Ad Source has filled its weight in ads check the next Ad Source as in step 2
4. If all the Ad Sources have filled their weight reset their counters to zero and fill the slot with an ad from the first ad source.

See pretty simple.  There are a few notes to be aware of but they don’t really change the process.

• If there is only one Ad Source it will be used to fill every ad slot for that allocation, excepting of course the sponsor ads.
• You can specify the weight for an Ad Source by weight or percent
• If you mix weights and percents in a single Allocation the total of all percent weights must be less then 100% to allow for the Ad Sources with non-percent weights
• If you use only percentage weights in an Allocation then the total of weights must be 100% no more, no less. 100% shall be the total weight, and the number of the weighting shall be 100%. 101% shalt not be the weight, neither 99%, excepting that thou then proceed to 100%.  105% shall be right out.
• MATH WARNING scary I know.  If you mix weights and percentage weights the weight used in the above rotation algorithm is determined by totaling the percentage weights and totaling the straight weights.  The calculated total weight of all the Ad Sources is the total of the straight weights divided by  1 – (the total of the percentage weights divided by 100) .  The calculated weight for any Ad Source with a percentage weight is the calculated total weight multiplied by the Ad Sources percentage weight divided by 100.
  • Example: you have an allocation with 3 Ad Sources.  The first has a weight of 2, the second a weight of 5 and the third a weight of 30%.  The third Ad Source will have its ads rotated using a weight of 3.  MORE MATH 2 + 5 / (1 – .3) = 7 / .7 = 10.  10 * .3 = 3
  • The actual math used is a little come complicated to keep the calculated weights for Ad Sources with percentage weights accurate(odd percents can lead to a weight of 2.7 for instance and how exactly you fill .7 of an Ad Slot is beyond me) by adjusting the order of magnitude for all weights to eliminate non-repeating decimal weights and then factoring the weights so the first Ad Source doesn’t have to fill 1000 slots before the second Ad Source is used.  I won’t go into the exact math though as the Euclidean algorithm for finding the Greatest Common Factor is beyond the scope of this tutorial.

Understanding Rules

Rules are simple and powerful, just not 100% self explanatory.  An Allocation can have zero or more rules grouped together in RuleSets.  An Allocations rules determine whether or not an the Allocation is used to fill an Ad Slot or not.  When an Advertwhirl tries to fill an Ad Slot the Allocations for the campaign assigned to that Ad Slot are checked to see if the Allocation matches.  Starting with the Allocation 1 and working its way down.  Once an Allocation matches it is used to fill the Ad Slot and no further checking is performed.  The method used to determine if an Allocation should fill an Ad Slot or not is below.

1. If the Allocation has no RuleSets it matches.  (To insure that a campaign always fills its Ad Slots ad an Allocation at the end of all the others with no rules.  If nothing else matches it will)
2. If the Allocation has 1 or more RuleSets check each RuleSet to see if the RuleSet matches.
3. A RuleSet matches if all if its Rules match
4. If any RuleSet matches the Allocation matches and no further checking is performed.
5. If no RuleSets match the Allocation doesn’t match and Advertwhirl moves on to checking the next Allocation
6. If no Allocations match Advertwhirl checks to see if you have “fill empty ad slots” checked in settings and fills the slot with your default ad source
7. if “fill empty ad slots” isn’t enabled or you don’t have a default ad source defined the Ad Slot remains empty (in other words no Ad Unit is displayed there for that view)

The simplified version

1. An Allocation matches if ANY of its RuleSets match
2. A RuleSet matches if ALL of its rules match

For those of you with programming experience or math logic experience the RuleSets are compared with the equivalent of an OR and the rules in each as with an AND.

Here are the Rules

Author Rule

The author rule lets you select an allocation based on the author of post or page.  If the post or page containing the Ad Slot needing to be filled was written by the selected author the rule matches.  If not, well it doesn’t.

 

Post Type Rule

The post type rule lets you select an allocation based on the type of the post/page containing the Ad Slot.  If you want an Allocation to only be displayed on posts add a Post Type rule set to Post.  Want to only display the Allocation to be fill slots on page set the rule to Page.

Category Rule

The category rule matches post/page categories in a little more advanced way than the author and post type rules.  The Allocation will fill the ad slot if the post “is a” or “is not a” category.  If you select “is a” the Allocation matches if the post has the selected category set or child, grandchild category set.  The drop down to select category shows the relationship between categories.  Child categories are below and indent from their parent.  In other words the indented categories are considered to be “is a” of their parent/grandparent categories.  If you select “is not a” it works the same only the Allocation will fill a post if it doesn’t have the category or any of its descendants set.

Tag Rule

The tag rule works just like the category rule, only since tags don’t have parent/child hierarchies “is a” matches if the post has the tag set and “is not a” matches if the post does not have the tag set.

Location Rule

The location rule matches the visitors location.  To use the location rule you need a free api key from the IP Info Database. You can request your key here it is a simple form and they will email the key in a few minutes time.  Once you have the key enter it in the “IP Info Database Key” field in General Settings.

Location rules have 3 settings.  The first sets which part of the visitor’s location you are trying to match.  It is possible to match the visitor’s Country, State/Region, City or Postal Code.

The next setting is the type of match you want to perform.  The types of matches are “is”, “is not”, “matches regular expression”, “does not match regular expression”.

The third field is the value you are trying to match.

If you made the following location rule “Country” “is” “United States” the rule would match if the visitor is located in the United States otherwise it would not match.

If you made the following location rule “City” “is not” “Denver” the rule would match if the visitor is not located in the Denver otherwise it would not match.

Regular expressions are an advanced way of matching a pattern, such as “802[0-9][0-9]“ is a regular expression that would match a 5 digit number(looks like a postal code, doesn’t it?) that begins with 802 and ends with any two digits.

Regular expressions are a complex and advanced subject the surface of which can’t even be scratched here.  There are a ton of source that our good friend Mr Google can point you to.  Or if there is a particular pattern you want to match for one of your rules you can ask on the Advertwhirl support forum.

Link Argument Rule

The link argument rule matches get arguments encoded in a URL.  It is used mainly for external ads to allow you to differentiate external ad slots.  Get arguments are the part of the link that follow the page.  The page and get arguments are separated by a question mark.  The following example link has 2 get arguments

http://www.yourdomain.com/advertwhirl/your_campaign?argument1=some_value&argument2=another_value

the two arguments are “argument1″ and “argument2″ and have the values “some_value” and “another_value”.

Like the location rule the link argument rule has three parts.  The name of the get argument you want to test, the type of test and the value you want to test against.

the test types are “is equal to”, “is not equal to”, “is greater than”, “is less than”, “is greater than or equal to”, “is less than or equal to”,  “matches regular expression”, “doesn’t match regular expression”

All of the equality tests (everything but the 2 regular expression tests) do a normal numerical compare if the link argument contains a numeric value.  ie.. 1 is less than 5, 4 is greater than 3 etc…

If the link argument does not contain a numeric value the equality tests do an alphabetic test.  Greater than means the value comes the argument value comes alphabetically after the test value.  “apple” “is less than” “banana”, “dog” “is greater than” “cat” (and not just because dogs are awesome and cats are snobby little creeps).

Virtual Path Rule

The virtual path rule is only enabled if you have the Virtual Theme plugin installed.  The virtual path rule has 2 settings, the test type and the test value.  The test types are “is”, “is not”, “matches regular expression”, “does not match regular expression”.

Custom Variable Rule

The custom variable rule is only enabled if you have the Virtual Theme plugin installed and works exactly like the link argument rule but instead of matching get arguments it matches Virtual Theme custom variables.

Download Advertwhirl

Download Advertwhirl

References

Mobile Sentience Advertwhirl page
Advertwhirl in the WordPress gallery
Tutorial with instructions for installing Advertwhirl Plugin

Campaigns, Allocations and Rules oh my!, 1.3 out of 10 based on 3 ratings