Manual

vB Ad Management - Version 5.02

Features

vB Ad Management is a free and flexible advertising management system for vBulletin software.

Display advertisements forum-wide and beyond. Any advertisement can be displayed at any point on your forum, with each advertisement independently managed as a separate "adcode block". By default some of the most common locations for advertisements are included with pre-set options, such as displaying an advertisement after the first post in a thread.
Easy to use. All settings include additional notes and demonstrations and couldn't be simpler. You can insert complex content into your forum in seconds and can instantly preview your advertisement before publishing.
Modular format. If your vBulletin is more than just a forum, you can easily expand its features by plugging your own custom ad modules into the vBam engine. Available by default are forum and blog modules.
Preset ad formats. In addition to common settings, some common advertisement setups are included by default. These include forum sponsors, page columns and full-page advertisements.
Take your ads offsite. adcode blocks for feeds and emails take your advertisements straight to third parties.
Advertisement sharing and advertisement revenue sharing. Any parts of your advertisement code can be set aside for ad sharing and ad revenue sharing (not the same thing!) with your members and staff.
AJAX advertisement refreshing. Increase your impressions and revenue by setting your advertisements to periodically refresh without a user loading a new page.
Ad rotations. An adcode block may contain single advertisements or a random rotation of any number of multiple advertisements.
Affiliate link manager. If less traditional advertisements are a source of income, vBam ensures you never miss revenue by altering any relevant link to include your affiliate IDs.
Quick settings. As well as individual customisation, a variety of settings allow you to set conditions across all your advertisements, including ad sharing restrictions and exclusion of page type for advertisement service agreement compliance.
Time-limited advertisements. Set your adcode blocks to appear between set dates or certain times of the day.
Fully templated. Each adcode block is displaying using a standard vBulletin template and is fully editable.
vBulletin conditionals and phrases. As well as standard template functions, conditionals and phrases can also be used within adcode block themselves, allowing you to customise the advertisement according to your forum users and settings.
Integrates with external modifications.. If you are using vB Advanced CMS, Photopost Photo Sharing Gallery or any similar modification which extends the functionality of your forum, you should be able to integrate vB Ad Management advertisements.
Chameleon advertisements. You may optionally blend the appearance of ads with the forum, for instance allowing them to appear as a post.
Works with external advertisement managers. If all the above is not enough or you already use an external ad manager like OpenAds, you should have no trouble using it in tandem with vB Ad Management.
Fast and efficient. vB Ad Management is already used by some very sizable forums without issue and now it's even faster.
Free to download and use, and free support. Support is only available via the vBulletin.org to registered vBulletin users. You must be registered with RedTyger to download archive/pre-release versions or report a bug. This free software is supported by a copyright link placed in your forum's footer.
Unlimited customisation! The greatest strength of this modification is that there is no limit to what you can do with it. You do not even have to use it for advertisements, you can use it to manage the display of any content you want. Let's say you wanted to display a random set of 5 advertisements to just 2 specific users in 8 different forums with 3 different parts of each individual advertisement shared with the users in 3 different ways for two weeks of the year, provided the users had a post count of over 500, were in usergroup 10 and were not using Internet Explorer. You can do that, plus much more, in any combination!

Thousands of forums use vB Ad Management, including (as of the time of writing): Unix.com, Bimmerforums.com, Mambers.com, Majorgeeks.com and many more.

Changelog: Differences between version 5.01 Beta and 5.02

Important vB Ad Management now requires vBulletin 3.6 to function. It is also now modular, which means one plugin for the central functionality, plus optional additional plugins for product-specific functionality. To replicate all the old functionality now requires two plugins, however you may still only need one.

Added brand-free licensing.
Changed release status, vB Ad Management is no longer in beta.
Fixed Incorrect calculation of sponsor cells when one was left empty.

Files changed from previous version

products/vbam.xml
uploads/includes/vbam_functions.php

View all vB Ad Management changelogs

Download

vB Ad Management 5.02 is available to all registered RedTyger users from the vB Ad Management downloads section or from the vBulletin.org release thread for all vBulletin users with a confirmed license.

Requirements: vBulletin software 3.6 or later.

Installing/Uninstalling

New installation

Extract the contents of the download file to your computer.
Upload the file in the product folder via the Product Manager at AdminCP > Plugins & Products > Manage Products > [Add/Import Product].
Upload the contents of the uploads folder to the equivalent location in your forum on your server. The directory structure within the download file is the same as your forum. So includes/vbam_functions goes in your forum's includes directory, etc.
Reload your AdminCP page so that the new vB Ad Management menu appears at the bottom of your menus.
If you are the owner of a brand-free vBulletin license or the vB Ad Management branding is not appearing in the place you want it to, please read this FAQ entry.
Done!

Upgrading from a previous version

Version 4.00 Beta and later only:
Do not remove your existing vB Ad Management installation first. Back up your forum before you begin. Follow the instructions for a new installation. You will now have two vB Ad Management menus, the old one near the top and the new one near the bottom. In the new Global Settings will be an option to import your old settings. If you have forum advertisements settings you want to keep, install the forum module and then run the import option in Global Settings there as well. Check that your settings have been restored correctly and if all looks well follow the uninstallation instructions for the old version. Don't forget to check the version number of the product you are removing. They both have the same name.

Version 3.14 and earlier only:
Because of the substantial code and functional changes such as the merging of static and random advertisements, upgrading is unfortunately not possible. Please follow the steps below, then the instructions for a new installation. Be sure to make a note of important settings.

Uninstall the modification via the Product Manager at AdminCP > Plugins & Products > Manage Products > vB Ad Management (Dropdown menu).

Version 3.10 and later only:
Delete the includes/vb_ad_management folder from your server.

Removing the modification

Uninstall the modification via the Product Manager at AdminCP > Plugins & Products > Manage Products > vB Ad Management (Dropdown menu).
Delete all installation files from your server.

Setup and usage

The settings are thoroughly explained with accompanying examples and notes when configuring the modification. They are easy to follow but I would suggest going through the options in the order in which they are presented in the main menu. A couple of specifics are described below.

Creating an advertisement

Each section of code is assigned a "block" both in your vBulletin software and in the settings, and each block has settings which apply to that block only. Setting up an advertisement block is very easy, an example of an adcode block is shown below. At its most basic, all you have to do is turn the advertisement block on and paste your advertisement code into the large text box. It will then appear at whichever position you have selected from the insertion menu. It's as simple as that! Some blocks may have more, fewer or different options than shown. It depends on where the advertisement will display and what functionality is permitted by the location (not your specified position).

Implementing ad sharing

Advertisement sharing and advertisement revenue sharing is a system whereby the administrator of a website allows members to input their own ad management details, usually according to certain restrictions. Upon certain conditions being fulfilled, the member's ad management details will be temporarily used instead of the admininstrators, so substituting any admin revenue/exposure for that of the member.

In practise there are two ways that this may be done, both possible using vB Ad Management. The first is ad revenue sharing. This is where the ad provider is set by the administrator, allowing only the publisher/owner details to be variable. The other is ad sharing, where an entire advertisement may be variable, such as a link/banner comination which a member can set themselves.

Use of ad sharing is based on user profile fields, which are the user-input sections both custom and default which are found in various sections of a user's UserCP. You can view existing user profile fields and add a wide variety yourself via AdminCP > User Profile Fields > User Profile Field Manager. I'm going to demonstrate how to integrate ad revenue sharing using Google's Adsense. ( ) Here's a typical Adsense code.

<script type="text/javascript">  </script> <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>

The google_ad_client part is what I'm interested in. The letter/number sequence there is the ID of the publisher to whom the royalties are paid. If I change that ID, I change where the payments for that advertisement go. So, what I want to do is replace that part of the code with someone's publisher ID depending on circumstance. I've created a User Profile Field, which will appear in every ad sharing enabled user's UserCP. I need to make a note of the field number that vBulletin has assigned that field, which can by found by viewing AdminCP > User Profile Fields > User Profile Field Manager. In this case it is field6.

So, in the Adsense code I'm going to replace the section I want to be variable with the appropriate field number, with a # either side of it to indicate that this is the removable section.

<script type="text/javascript">  </script> <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>

That can now be pasted into an adcode block and saved. However, ad sharing may not always be triggered. So I need to set what will appear in field6's place by default when it is not making use of a user's shared adcode. If you go to AdminCP > vB Ad Management > Ad Sharing, at the bottom of the page is a list of all your forum's user fields. Here you should enter the code which should appear when an advertisement is displayed as normal, in this case it should by my publisher ID which I replaced in the original Adsense code.

Now your adcode is ready to be displayed on the forum. If a member of your forum has an Adsense publisher ID, they can enter it into their Profile and if ad sharing is triggered, their publisher ID will be used instead of yours.

So to summarise. Create a user profile field for each adcode section you want saved, replace the appropriate part in the code with #fieldx# where fieldx is the field ID and enter a default value for that section of the adcode. You can use as many shared fields in as many adcodes as you like and there is no restriction to what you can do with them.

Secure ad sharing

As you are allowing users to directly insert content into your forum, you'll want to be very sure that they can only add what you want them to add. There are three ways you can do this.

Firstly, share only what you have to. In the above ad sharing example, I only shared the publisher ID, a small part of the overall advertisement code. What I could have done is made the entire adcode block a shared item and allowed the user to insert their own Adsense code in its entirety, much less securely. If I wanted to share more than just the publisher ID, say allowing the user to specify their own channel as well, I would have replaced that with another custom field. Even if I needed a dozen different parts of the adcode shared, I would have split it into different fields.

Secondly, do not enable the "Allow HTML" shared option unless your users absolutely must be able to use HTML. When HTML is disabled a sizable range of potential abuses are not possible (inserting unwanted images, for example).

Thirdly, make use of the "Regular Expression" field which is provided by vBulletin when creating a custom field. This allows you to very precisely limit what can be used in the user's shared code, right down to individual characters and their number. For instance, for the above example I used the regular expression ^ca-pub-[0-9]{4}$. This allows the letters ca, then a hypen, then the letters pub, then another hyphen, then any of the numbers 0 to 9 exactly four times in a row. Anything else will be denied. Regular expressions can be very complex and are an acquired expertise as well limited in that you must generally know what will be submitted in order to check it, but are extremely secure if they can be used.

Conditionals

You can make use of vBulletin's template conditionals in your adcode. They are reasonably easy to use once you understand how they work. Broadly speaking, they mean "if this condition is true, display this" and generally work by comparing one value with another to establish a condition to evaluate. You are likely to only want to use a handful of conditionals, such as deciding conditions based on forum ID, user ID, usergroup, and possibly some further ones such as THIS_SCRIPT definition and threadid.

To use a conditional, you use two tags with your chosen condition in between the condition="condition goes here" part. What is between the tags will be displayed if the condition is true. Lets say I want to display "Hello" if the current page is within forum ID 2. I would use this in/as my code.

<if condition="in_array($forum, array(2))">Hello</if>

That compares the value of the current forum ID (held as $forum in vBulletin's code) with the number 2, which I want it to match. I can add an unlimited number of extra forum IDs by separating them with commas.

<if condition="in_array($forum, array(2,3,4,5))">Hello</if>

I can instead say if this condition is NOT true - display "Hello" if the page is not forum ID 2, 3, 4, or 5 - by beginning the condition with !, like this.

<if condition="!in_array($forum, array(2,3,4,5))">Hello</if>

So, if I wanted to display "Yes" if the current page being viewed were in forum ID 2 or 3, and "No" if the current page were in neither of those fora, I could do this:

<if condition="in_array($forum, array(2,3))">Hello</if> <if condition="!in_array($forum, array(2,3))">Goodbye</if>

That will work fine, but vBulletin also allow you to specify what to do if a conditional is not true, in other words if this condition is true display this, else display this. So the above conditional could be rewritten a little more clearly as this, which does exactly the same thing:

<if condition="in_array($forum, array(2,3))">Hello<else />Goodbye</if>

What if you wanted to do something a little more complicated? Lets say I want to display "Hello" if the current page is in forum ID 2 or 3, but "Hello and welcome to my forum" if the current page is in forum ID 2 only? Conditionals can be used inside each other (including inside <else />s), known as nested conditionals, allowing further specifications. The code for what I want to do looks like this:

<if condition="in_array($forum, array(2,3))"> Hello <if condition="in_array($forum, array(2))"> and welcome to my forum </if> </if>

Note that each opening <if condition tag must also have a closing </if>tag each. Comparing to the forum ID is not the only condition you can evaluate, you can also make use of other values:

$bbuserinfo[usergroupid], which is the current user's usergroup.
Various other subdivisions of $bbuserinfo such as $bbuserinfo[userid], which is the current user's ID.
$threadinfo[threadid], the current thread ID.
THIS_SCRIPT, the current definition of THIS_SCRIPT.

There are many many more, but you can evaluate any value of any kind against any other. If a value is not set such as when evaluating $threadinfo[threadid] when outside a thread or when spelling a value incorrectly, it will default to being defined as 0. Lets see some examples.

<if condition="in_array(THIS_SCRIPT, array(register,login))"> This is a registration or login page. </if>

<if condition="in_array(THIS_SCRIPT, array(register,login))"> This is a registration or login page. <else /> <if condition="in_array($bbuserinfo[usergroupid], array(1,3,4))"> This is not a registration or login page and this person is not a fully registered forum member. </if> </if>

Finally, there is a more advanced AND/OR syntax which you can use within conditionals. This does exactly what it sounds like. If condition 1 is true AND condition 2 is true, display this. Or, if condition 1 is true OR condition 2 is true, display this. You can use as many as you like in a row and can combine AND and OR in a single condional, but be wary of how the logic pans out.

<if condition="in_array($forumid, array(1)) AND !in_array($bbuserinfo[usergroupid], array(6))"> This is forum 1 and you are not an administrator. <else /> This is not forum 1 or you are an administrator. </if> <if condition="in_array($forumid, array(1)) OR in_array($bbuserinfo[usergroupid], array(6)) OR in_array($bbuserinfo[userid], array(1))"> This is forum 1 or you are an administrator or your userid is 1. <else /> This is not forum 1 or you are not an administrator or your userid is not 1. </if>

For comparing single values to form a conditional, there are a few simple evaluators which you can use in additional to the is equal/is not equal evaluators above. I'll use numbers for the examples, though of course it usually makes no sense to use static numbers for conditionals.

== means is equal to. <if condition="1 == 2"> means "if 1 is equal to 2".
!= means is not equal to. <if condition="1 != 2"> means "if 1 is not equal to 2".
> means is greater than. <if condition="1 > 2"> means "if 1 is greater than 2".
< means is less than. <if condition="1 < 2"> means "if 1 is less than 2".

If you need further help with conditionals, you should ask on the vBulletin forums or the unofficial alternative at vBulletin.org forums.

Support

Be sure to check the manual and FAQ first, after which help about using the product is available from the release thread on vBulletin.org only. You must register there and confirm your vBulletin license is valid first. I'll do my best to help, but it's on an if-and-when basis since the number of vB Ad Management users rather exceeded what I was expecting. Other users often chime in to help out.

Reporting a bug is where you can report errors with the software.

Frequently Asked Questions

I'm using a brand-free version of vBulletin / Enabling advertisements makes my forum pages go blank!

The full copyright link to my website must be present for the modification to work. If you are using a brand-free version of vBulletin you may find that it is not added automatically and that page display fails when vB Ad Management is turned on. There are two easy ways to fix this. Copy the following text... `

<br />Ad Management by <a href="http://redtyger.co.uk/" target="_blank">RedTyger</a>

... onto the end of vBulletin's copyright text field at AdminCP > vBulletin Options > vBulletin Options > Site Name / URL / Contact Details (admincp/options.php?do=options&dogroup=address). If that doesn't work, you can paste it directly into the footer at AdminCP > Styles & Templates > Style Manager > Edit Template (in the style dropdown menu) > footer template. Where it says  is likely the best place.

Can I purchase a brand-free version?

You can, it costs $20 USD per vBulletin license the modification will be used with. The brand-free license matches the vBulletin license, so it entitles you to remove the footer branding (a download is provided with it already removed) and that is the only difference between the versions.

To purchase the brand free version, register if you have not already done so and when you have a validated account, send as much funds as is required via PayPal and in the message include all the URLs where the brand-free version will be used and your registered username so I can grant you access to the download section. Both are required information.

If you are able to send funds in GBP instead of USD that would be preferential, but is not essential. It makes no difference to you, but it reduces the amount Paypal tax me.

Can I create additional modules for download on my website?

Yes, you can create additional modules or features privately or publicly, you don't need to ask me first. But you may only distribute modules you have created, the engine itself and the forum and blog modules are for download on RedTyger and on vBulletin.org only and cannot be redistributed.

Can I offer my translation for download on my website?

Yes, if you have created a translation file then you can offer it for download, distribute it, sell it, whatever you like. You don't need to ask me first. But again, you may only distribute your own language file. The rest of the product is for download on RedTyger and on vBulletin.org only and cannot be redistributed.

Can I allow users to stop/start the auto-refresh?

You can, you need to add a link to your advertisement template as shown below, changing what is between [] to what is used in the $vbam_adcode for that template. So if you see $vbam_adcode[header] in your template, your link will look like this:

Stop

And a link to start it again looks like this:

Start

A link which both starts and stops refreshing would look like this:

Pause

To change the text depending on whether refreshing is paused or not:

Stop

Can you give me a regular expression to restrict shared adcode to one banner link?

^<a href="[\w-:./_]+"( target="_blank")?><img src="[\w-:./_]+"( alt="[\w ]+")?( border="[0-5]")? /></a>$

The above regex above will do just that. I'll run through what it means it briefly.

<a href="[\w-:./_]+"( target="_blank")?>

This part means a hyper link using at least one the characters 0 to 9, A to Z (including lowercase versions), and the other characters inside the square brackets. No other characters are permitted. They may optionally add target="_blank" to the link code, which means clicking the link will open it in a new window.

<img src="[\w-:./_]+"( alt="[\w ]+")?( border="[0-5]")? />

This part means an image with the source using the same character restrictions as for the link, plus optionally some text (A to Z and lower case versions only) to describe the image and an optional image border of 0 to 5 pixels wide.

All the optional items are only permitted at exactly in that place within the code. Further restrictions are possible if you wish.

You can restrict the image source to a location of your choice - so users can only use images you have put on your website and screened already, for example - simply by adding parts to the src (image source) code that users will not be able to work around. src="http://redtyger.co.uk/[\w-:./_]+" means only an image URL beginning with http://redtyger.co.uk will be accepted, or you can use http://(www.)?redtyger.co.uk to allow the URL with or without the www. part.

Perhaps you want to restrict the types of image the user can use for their advertisement. src="http://redtyger.co.uk/[\w-:./_]+(.jpg|.jpeg.|.gif)" means that the image URL must begin with http.redtyger.co.uk and end with .jpg, .jpeg or .gif. Just add more file extensions separated by | to extend the list.

Can I set a timescale for individual parts of an adcode block?

Yes you can, using conditionals. vBulletin has a variable called TIMENOW which is, surprise, the exact time when viewing a page. You can compare this with a time of your own choosing, specified using the Unix timestamp format. To get this number, you can use this Unix timestamp converter. It will provide you with a string of numbers which is actually the number of seconds since 1st January, 1970 (Don't ask). All you have to do is compare the time now with the time of your specification using greater than or less than, like this.

<if condition="TIMENOW > 1199163600"> If TIMENOW is greater than 1199163600, this will be displayed. Which translates as: If the time now is later than 1st January 2008, this will be displayed. </if> <if condition="TIMENOW < 1199163600"> If TIMENOW is less than 1199163600, this will be displayed. Which translates as: If the time now is earlier than 1st January 2008, this will be displayed. </if> <if condition="TIMENOW < 1262322000 AND TIMENOW > 1104555600"> If TIMENOW is less than 1199163600 and is greater than 1104555600 this will be displayed. Which translates as: If the time now is earlier than 1st January 2010 and later than 1st January 2005, this will be displayed. </if>

Conditions for certain times of the day are more complex and unfortunately can't be used in template conditionals.

I am getting an error message about function.include

If you are getting warning messages at the top of the page that looks something like this...

Warning: include(vbam_functions.php) [function.include]: failed to open stream: No such file or directory in home\website on line 1

...it means that the required files have not been uploaded correctly. Please review the instructions and try again.

How do I make the columns visible?

Left column:
In the template advertisement_leftcolumn, FIND:

<div id="leftcolumn_adcode" class="adcode" style="padding-right:$stylevar[spacersize]px"> $vbam_adcode[leftcolumn] </div>

REPLACE WITH:

<table align="left" border="1px" cellpadding="$stylevar[cellpadding]" cellspacing="$stylevar[cellspacing]" class="tborder" style="padding-right:$stylevar[spacersize]px"> <tr> <td class="thead"> Sponsored Links </td> </tr> <tr> <td class="alt1"> <div id="leftcolumn_adcode" class="adcode"> $vbam_adcode[leftcolumn] </div> </td> </tr> </table>

Right column:
In the template advertisement_rightcolumn, FIND:

<div id="rightcolumn_adcode" class="adcode" style="padding-left:$stylevar[spacersize]px"> $vbam_adcode[rightcolumn] </div>

REPLACE WITH:

<table align="left" border="1px" cellpadding="$stylevar[cellpadding]" cellspacing="$stylevar[cellspacing]" class="tborder" style="padding-left:$stylevar[spacersize]px"> <tr> <td class="thead"> Sponsored Links </td> </tr> <tr> <td class="alt1"> <div id="rightcolumn_adcode" class="adcode"> $vbam_adcode[rightcolumn] </div> </td> </tr> </table>

How do I put advertising with the last post in a thread only?

You do so using a conditional in your postbit adcode. <if condition="$GLOBALS['post']['islastshown']"> Content for the last post only goes here. </if>

The left/right columns are appearing in the wrong place or not at all.

The columns are specifically designed to fit to the default vBulletin theme, so custom themes or edited templates may have problems using columns. They are added by searching for a section of template and adding themselves, so you may want to change what they search for. In global.start.php, you'll find the following separate code a few lines below their //Label:

// Left column ... $vbulletin->templatecache['footer'] = str_replace('$spacer_close', '$spacer_close', $vbulletin->templatecache['footer']); // Right column ... $vbulletin->templatecache['header'] = str_replace('$spacer_open', $vbulletin->db->escape_string($rc_str_replace).'$spacer_open', $vbulletin->templatecache['header']);

The underlined parts of the code are the lines the columns are paired with in the template and the parts you should change.