Manual

vB Ad Management - Version 4.00 Beta

Features

vB Ad Management is a free and flexible advertising management system for vBulletin forum 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.
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.
Advertisement sharing and advertisement revenue sharing. Any part of your advertisement code can be set aside for ad sharing and ad revenue sharing (not the same thing!) with your forum members and staff.
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.
Random advertisement arrays. An adcode block may contain single advertisements or a random rotation of any number of multiple advertisements.
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 with a set beginning time, ending time or both.
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!

Changelog: Differences between version 3.14 and 4.00 Beta

Added version-specific manuals (you're reading it!) to improve the instructions as much as possible. This includes the newly expansive text in the manual as well, of course. Manuals for versions before this one may be lower quality.
Added global support for vBulletin template conditionals in adcode.
Added full support for vBulletin phrases in adcode.
Added optional automated template edits.
Added forum Sponsors box.
Added full page advertisements.
Added timescales for advertisements, now you can specify when an advertisement should begin to be displayed, or when it should expire and stop being displayed, or a timespan using both.
Added live AJAX preview for adcode. A preview will be shown when you load the settings page and you can instantly update the preview without reloading the page.
Added warnings for important related options that have been disabled in Global Settings.
Added the option to use up to 25 additional custom advertisement blocks.
Added the option to use forum staff as an ad sharing assignment.
Added the ability to use unlimited ad sharing fields.
Added the hiding of ad sharing UserCP options for those who do not have ad sharing access.
Added postbit and threadbit advertisements to searches.
Added a template group for advertisement templates. They can all now be found in the group "Advertisement". The group name is phrased, so if you are using a translated version it may be named something different.
Changed almost everything about the user interface. Total overhaul.
Changed almost everything about the code as well! Entirely rewritten. Faster, uses less memory, database queries improved.
Changed static and random advertisements to use the same adcode.
Changed archive advertisements to be assigned separate adcode blocks.
Changed database queries to use the slave server, if any.
Changed columns to be activated independantly of advertisements. So you can enable a column and use it for something else if you wish, as well as place additional adcode blocks within the column.
Changed the settings to be rewritten and moved most of them to an external file.
Changed postbit "display as user" option to to a more general "blend" option, where various templates can optionally imitate the templates they accompany. The blend options now also are provided as separate templates so they can be edited. The new templates are named advertisement_x_blend.
Changed archive advertisements to have their own separate settings and adcode, as conditionals used in main advertisments are unlikely to work there as well.
Changed phrases to be installed separately to the product, allowing for easy language translations and product upgrades without requiring an updated language file (although it may leave translations incorrect or missing).
Changed almost all the settings text and separated it into description, example and additional notes.
Changed various files to be back inside the product. For very small files it wasn't worth the import.
Changed "Remove advertisements" link to be a phrase instead of a manual-input option, now it is $vbphrase[adintegrate_remove_ads].
Removed forumbit and threadbit ad sharing. This is primarily due to the new method of ad-sharing, plus the fact that I've never heard of anyone using either of them. I'll probably re-add them if there's enough interest.
Removed more complex adsharing user random assignment added earlier. It didn't make enough difference to be worth it.
Removed automatic Google Analytics integration, it is not really an advertisement feature. It's something for a separate modification.
Removed the option to identify a user whose adcode is being used on that page. It was unreliable and the user may not be on the page anyway, giving the impression that it was not working.
Removed all userid, threadid and announcementid exclusion settings, they were inefficient and rarely used. If still needed, they can either be dealt with using conditionals or usergroups.
Removed postbit avatar option, a blank avatar is provided in the postbit blend templates and can be edited to an image if required.
Fixed issue where sharing was not properly triggered when it was at the very end of Adcode.
Fixed announcement advertisements not working. See BugID 27.

Changed files

All of them!

View all vB Ad Management changelogs

Download

vB Ad Management 4.00 Beta is available to all registered RedTyger users from the vB Ad Management 4.00 Beta release announcement.

At least one major version update has been released since this version, this version may no longer be available for download. You should consider upgrading to the latest version which is likely to contain major benefits over this version.

BETA: This is not a general availability release, you should only use it if you are comfortable with the possibility of encountering problems. As this is an old version, you should upgrade even if the next version is BETA. Please do not report problems with this release.

Requirements: vBulletin forum software 3.5 or later.

Installing/Uninstalling

New installation

Extract the contents of the download file to your computer.
Upload vb_ad_management.xml via the Product Manager at AdminCP > Plugins & Products > Manage Products > [Add/Import Product].
Upload languages/vb_ad_management_english.xml also via the Product Manager if you wish to use the English language version of the product, or use an alternative language file if you have/can find one.
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 admincp/vb_ad_management goes in your forum's admincp directory, etc.
Reload your AdminCP page so that the new vB Ad Management menu appears.
In AdminCP > vB Ad Management > Custom is an option to delete unused custom blocks, you should run this once to optimise memory even if you are not using any custom blocks.
Done!

Upgrading from a previous version

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.

You are viewing prices in:

Or you can use the currency converter for any amount. Live exchange rates by Yahoo! Finance.

If you'd like to pay to have it done for you, it'll cost you:
£10 GBP if you would like me to install vB Ad Management for you.
£20 GBP plus for configuring and/or installation. It depends what and how much needs doing.
Create a private discussion with me or contact me for further details.

Creating an advertisement

Each section of code is assigned a "block" both on the forum 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 on your forum wherever you insert $x_advertisement into your forum template, where x is the name of the block. It's as simple as that! Optionally you can also set a period of time for the ad block to be shown, as well as have your template edit done automatically.

Editing the templates

To edit the templates to insert your advertisement block, visit AdminCP > Styles & Templates > Style Manager > Edit Templates. Open the appropriate template and paste in $x_advertisement, where x is the name of the block. All of the default advertisement blocks are also templated, they are named advertisement_x and can be found within the Advertisement template group. Within the modification, locations are described by their name within vBulletin rather than a description of their location. So the navbar block is applied to the navbar template, and so on. How the names transribe to their location within your forum is described below.

Header is the template containing the row which includes the logo at the top of your forum pages.

Navbar is the navigation bar at the top of your forum which begins below the logo and ends after the links bar.

Threadbit is the template for a single row when viewing a list of threads.

Forumbit is the template for a single row when viewing a list of forums/subforums.

Postbit is the template used to display posts, announcements and private messages.

Footer is the template that contains everything at the bottom of your forum pages from the time downward.

Archive header, footer, left and right columns.

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 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

Can I purchase a brand-free version?

Sorry, currently you can't. The modification must be used with the branded link visible.

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. There's a couple of notes included with the language file you should bear in mind when doing the translating. You don't need to ask me for permission to translate, though if you'd like me to include a link to your translation on my website then just let me know and I'll see what I can do. But you may only distribute your own vb_ad_management_(language).xml file. The rest of the product is for download on RedTyger and on vBulletin.org only and cannot be redistributed.

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>

Why won't Ad sharing work with my comment stripper?

Comments are required for the modification to be able to separate advertisements from everything else to be sure it only alters the intended content, removing them means it can no longer do that. Comment strippers are almost universally unnecessary and you'd lose little by not having one.