Written on 21 October 2013. Posted in Banner Auctions Wizard Documentation.

Banner Auctions Wizard Installation

PreRequirements

Joomla 3.2+
AltaUserPoints component v1.1+

Optional (but recommended) extensions

Virtuemart
VM2Buypoints components (recommended)
ACY mailing (3rd party)

Introduction

Banners Auctions Wizzard is a native Joomla3 Bootstraped component allowing site admin to set auctions on advertisement spaces . It provides the users wanting to advertise on the site, with a simple front-end interface for banner addition/edition , banners management, prices, impressions and clicks statistics, banner ranking etc...

Banner prices are set in points (AUP) for 1k (1000) banner impressions.

AltauserPoints component is required to manage the points transactions. You can download it from www.alphaplug.com.

Prepare your site

Visit your site and define the spaces you want to offer as Banner Auctions.
Define the corresponding allowed Banner image/swf sizes. For your information most usual banner sizes are listed here: http://designerstoolbox.com/designresources/banners/
In core Joomla Banners component , define a (new) category as 'Advertisers (only) category' for Auctions.
For each of the banner sizes you selected, you must create a banner category within the Adverisers category (as children categories). Auctions are set wirthin each banner category (inside the main advertisers category). In the category name you set, it is a requirement that you also set the category banner size tag. Just like [250x250] where 1st 250 is the width in pixels and the 2nd 250 is the height in pixels. For example a category name could be: Square Banners [300x300]
Set new banner modules for each banner subcategories you created.

Installation and configuration

Install this component using the Regular Joomla Installer

Then Visit the component administration page. Components menu -> Banner Auctions component.

Click Options button on the top right to edit component settings.

FIELD: Advertisers Banner category ID
Create a category in the core Joomla Banner component where advertisers will be able to add banners. It is then required you create subcategories based on banner allowed sizes.

Make sure you include the banner size tag in the subcategory names like [WxH] or [250x250] where W is the banner width and H is the banner height. These tags are required to force user to upload the correct banner size to the correct category and to be displayed in the correct banner module.

FIELD: Banner minimim price for 1000 impressions
Banner Prices in this component are in points for 1k (1000) banner impressions. You can set here a minimum price allowed for 1000 impressions so the auctions and prices will never go below this amount.

FIELD: Minimum impressions
Set here the minimum impressions quantity to be purchased. You can leave empty to ignore

FIELD: Maximum impressions Set here the maximum impressions quantity to be purchased. You can leave empty to ignore.

FIELD: Show additional fields
Enable the additional (optional) fields tab in the Banner edition form.

FIELD: URL for points purchasing
Advertisers need points to purchase Banners. If they don't have points they have to get some. Leave empty to ignore and the buy points button will not show.

FIELD: Autopublish Banner submissions
Disable this if you want to moderate banner creation and edition. This is way to ensure that banner content fits to your site content.

FIELD: Notification Email
Set the email here, required if you enable one or more of the notification features below.

FIELD: Notifiy on Banner Addition
FIELD: Notifiy on Banner Edition
FIELD: Notifiy on Banner Deletion

FIELD: ACY mailing List ID
This feature requires a 3rd party mailing list component available from http://www.acyba.com . Using this component , you can create an Advertisers list and set the list ID in this field here so every advertiser gets added to the list when adding their first banner. This can be very helpfull if you wish to be able to communicate with all past and presents advertisers on your site.
FIELD: 3rd party Points manager
You need to install this separately: Get AlphaUserPoints from http://www.alphaplug.com

FIELD: AUP rule for banner transaction Here is the AUP rule function name for Banner auctions transactions. Points deductions when a adding banner or adding more impressions to an existing banner. Points additions when deleting a banner with some left unused impressions oe when removing impressions from an exisiting banner. We recommend you leave this as default, but you could change it for any reason.

HOW IT WORKS

The component has 4 main views:

Banner addition/edition form
My Banners: shows a table of user created banners with all the required parameters to keep in mind to manage auctions successfully (Price, current impressions, total impressions, clicks, ranks etc...)
Statistics charts: this page shows a combo chart providing a impressions and clicks amounts among time (year/month/day/hour)
Ranks: Shows a list of top banners (leading auctions) for a set category.

1. Banner addition/edition form

The component allows users to add and edit banners from the front end, It adds the banners to the core Joomla Banner table. The form is a simpler version of the core Banners component's with a price field added. Prices are in points and set for 1k impressions. Basically a banner module will be set to display 1 (ore more) banner from the top priced banners.

When a banner is added / edited via the front end form, banners are reordered according to their price. if more than one banners have the same price, then their total impressions value is compared and banner with the most total impressions get the best place. If more than one banners have same price and same total impressions, the older banner gets the best place.

Here are the form fields:

FIELD: Banner Category (radio buttons)
This custom field displays the category set within the advertisers category. For each banner category it shows the category name and description, the category auction current leading price and the mist of pages where banner modules are set to display banners from this category.

FIELD: Banner Name for advertiser use.

FIELD: Banner Image
Supported file extensions are JPG, GIF, PNG and SWF
The file size must match the dimensions mentioned in the category size tag ( like in [728x90] , where first value is width, second is height)

FIELD: Alternative text
String for the HTML img tag alt attribute.
FIELD: Click URL
Destination url for the banner click. Whatever you set here, it will be replaced by a url like:
index.php?option=com_banners&task=click&id=126
This is used to track clicks. If users add a SWF banner, the destination URL is set inside the swf file so the clicks are not tracked anymore. To keep tracking clicks from a SWF banner, it is recommended to create the banner (to get a banner ID) and to edit it , updating the URL in the SWF replacing www.mysite.com/myproduct with index.php?option=com_banners&task=click&id=[banner_id] and then setting www.mysite.com/myproduct in the Click URL form field.

This way a swf banner click will open index.php?option=com_banners&task=click&id=[banner_id] wich tracks clicks and redirect to www.mysite.com/myproduct

This is described to advertisers when adding a swf banner.

FIELD: Auction: Your Price
This is where advertiser is setting the auction price for the banner. Prices are in points for 1000 banner impressions.
If advertiser selected the [250x250] category, the current leading price is 500 points (for 1000 impressions)
If banner module is set to show only one banner (like most used banner modules) only the auction leader's banner (highest price) will be displayed. So unless this new banner has a higher price than 500 (or equal but more impressions) it will not be displayed.
Admin can set a minimum price in the component settings.

FIELD: Banner Impressions
Advertiser must set here how many banner impressions to be purchased at that previously set price.
This Impressions amount is considered when ranking banners with the same price. Banner with the most impressions will get a better ranking compared to another banner with the same price but fewer Impressions.
To be precise, when some banners have the same Price and same Impressions amount, older banner will get the best ranking.

Additional Options (Optional)
These additional options are functional but not required and currently not used by the component.

FIELDS: Start and Stop Publishing dates
Set publishing dates for the banner

FIELD: Keywords
Option to correlate Banner keywords to site content keywords.

FIELD: Meta Keyword Prefix
Used to save performance when using Keywords matching content.

When form is subitted to add a new banner, points are deducted from advertiser's account.
Deducted Amount is set like:
Deducted points = Price * (Impressions / 1000)
If user doesn't have enough points, the banner addition is canceled.

When a banner has been added, it is possible for the advertiser to edit it.

The edition form page is basically the same as the banner addition form except the category can not be changed as it is depending on banner file dimensions.

When editing, an advertiser can change the price and impressions of own banner to make it more competitive. For each price or impressions change (and also on banner deletion) Advertiser gets more points deducted if price or impressions have been increased or points refunded if price or impressions lowered.

For example
Mr Ad is adding a Banner: price 50 points (for 1k impressions) and 10000 impressions
10000 / 1000 * 50 = 500 points deducted

After the banner has been displayed 2000 times, Mr Ad decides to lower the total amount of impressions from 10000 to 8000 but to arise the price from 50 to 60.

As soon as there is a price change, calculation is made in 2 parts: close old contract refunding points for left (unused) impressions at the old price and opening new contract deducting points for new impressions amount at new price.

Left Impressions / 1000 * Old Price =
8000 / 1000 * 50 = 400 points to be refunded

6000 / 1000 * 60 = 360 points to be dedcuted

Difference = 40 refunded

An advertiser can browse own banners visiting the My Banners page.

2. My Banners

This page dispalys a table listing every advertiser's submitted banners with all the usefull information to manage banner auctions:

- State: published or pending moderation
- Visual: thumbnail and full size
- Banner name, banner category, file type, click url
- Impressions (current / total progress bar and %)
- Click and click/impressions rate chart
- Page where the banner is supposed to show (if ranking is enough). For each page diplayed here, the advertiser can see the required ranking for own banner to be displayed and a check sign shows if the banner is currently displayed there.
- Price: Category current top price and own banner current price.
- Ranking (which corresponds to the banner ordering +1 )
- Actions: Edit - View banner stats - Delete (if a banner is deleted before it spends all impressions, Advertiser gets spent points back for the unused impressions)

3. Banner statistics

This page shows the same information displayed in My Banners page, but for teh chosen banner only.
It also shows a Google combo chart displaying clicks and impressions based on time frames (Year, Month, Day, Hour)

4. Ranks page

This page shows leading competitors within one Banner category.
When creating a menu item to this page, you must provide, in the menu item settings, the default Banner auctions category ID you want to display. Visitor will be able to browse other auctions category thanks to a select list.
It displays a quick reminder about the category (name, desciption, banner size and site pages where this category is displayed). It finally shows a list of top ranking banners with their rank, price and impressions.

When developping this component we found a little bug in core Joomla Banners component. This bug prevents tracking more than one click or impressions by hour. Every impressions and clicks are counted so there is no security issue regarding the use of Banner Auctions, only the banner charts get meaningless if you don't apply the very easy fix. Error reported at:
http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_id=8103&tracker_item_id=33389 Fix: in component/com_banners/models/banner.php in click() function the query is:

$query->update('#__banner_tracks')

    ->set($db->quoteName('count') . ' = (' . $db->quote('count') . ' + 1)')

    ->where('track_type=2')

    ->where('banner_id=' . (int) $id)

    ->where('track_date=' . $db->quote($trackDate));

Mistake is on the second line, change quote for quoteName, and incremental update will work fine. This fix has to be applied also in
component/com_banners/models/banners.php in impress() function for impressions.

Created on 21 October 2013.
Last updated on 02 March 2017.