phpBannerExchange 2.0 is a powerful, feature-rich banner exchange script written in PHP4 and mySQL for the Apache web server running on Linux. While it is likely the script will work on other platforms such as Microsoft SQL and Internet Information Server (IIS), the software has not been tested on these platforms.
This guide is intended to assist you with the features included with the script and to guide you through the every day administration tasks required to run a thriving banner exchange. This guide assumes you have already successfully installed the script according to the Installation instructions.
[top]
The Administrative Control Panel allows you to control nearly every aspect of the Banner Exchange such as validating accounts, adding/removing/editing categories, deleting accounts, administering banners, and the like. To access the Control Panel, you will need to point your web browser to the following URL: http://www.yourdomain.com/exchange_directory/admin/
Replace yourdomain.com with your domain name (e.g.: eschew.net) and exchange_directory with the path to your root Banner Exchange directory (e.g.: bannerex). You will be presented with a login prompt. Log in with the Administrator username and password you created when you installed the script.
[top]
The Administrative Statistics window shows a variety of information. This is your main administrative page, nearly all options are available from here. Below is a description of the statistics table:
| Validated Users: | The number of users who currently have a banner in rotation. |
| Total Exposures: | The total number of exposures for all users. |
| Loose Credits: | The amount of credits currently eligible to be redeemed. |
| Total Banners Served: | The total amount of banners that have been served. This value is Exposures + Loose Credits. |
| Pending Users: | The number of users currently awaiting validation. |
| Total Clicks to Sites: | The number of times a banner has been clicked on. |
| Total Clicks from Sites: | This value should be the same as the Total Clicks to Sites. If it is not, you likely have a cheater. |
| Overall Exchange Ratio: | This is the exchange-wide click-thru ratio. |
[top]
One of the most important feature in the script is the ability for the Administrator to validate accounts. This allows the Administrator to control the content that is served to the clients. For example, it would be a Really Bad Idea™ for a church/christian related banner exchange to host an account for a porn site: Validating accounts allows the Administrator to remove accounts that may be offensive or beyond the scope of the exchange BEFORE they are inserted into the exchange rotation.
Accounts are also moved back into the validation queue whenever anything important is changed such as the Site URL and the addition or removal of banners.
Accounts waiting to be validated are listed on the "Validate Accounts" page. To validate an account, simply click on the account name. You will then be presented with a page that allows you to alter every aspect of the account. Below is a description of the options available to you:
| Real Name: | This is the user's real name. |
| Login ID: | This is the unique username chosen by the user. |
| Password: | This field displays the user's password. If you are using MD5 encrypted passwords, the MD5 hash of the password is listed here. Changing this value will allow you to change the users password, even if you are using MD5 encryption. |
| Email Address: | This is the e-mail address the user entered when creating the account. |
| Category: | The chosen category of the user's site. |
| Exposures: | The current number of exposures the user's account has been given. |
| Credits: | The amount of credits the user has amassed. |
| Clicks to site: | The number of clicks on this user's banner. |
| Clicks from site: | The number of clicks originating from this user's site. |
| RAW Mode: | RAW mode can be used to create an account on a secondary exchange from another site and include it on your exchange. To utilize RAW mode, you would simply enter the HTML provided by the second banner exchange in the field provided. RAW Mode overrides the exchange settings in "view.php". |
| Account Status: | To validate accounts, insure that the "Approved" radio button is selected. |
| Default Account: | Default Accounts are accounts that are displayed ONLY when there are no eligible banners with sufficient credit to be displayed. Generally, these accounts should be used to advertise your exchange, your web page, or another exchange (using RAW Mode). Every single banner exchange needs at least one default account. If you plan on displaying a Default Account's banner exchange code on a web page, you will need at least TWO (2) default accounts. |
| Send Newsletter: | This option is for the user to opt-in to the newsletter/mailing list that is controlled through the Mailer Manager feature. |
| Banners: | Banner display is suppressed in phpBannerExchange 2.0. To view the account's banners, click on View/edit banners. Options available on this page are sufficiently self-explanatory. |
[top]
This feature allows you to add an account directly into the exchange. This feature uses the same form as the Validation routine listed above.
[top]
This page allows you to list all active accounts in alphabetical order. The accounts are listed by type (Default or Normal) in alphabetical order for ease of navigation. Clicking on a specific account name will allow you to edit the account properties. This feature uses the same form as the Validation routine listed above.
[top]
The Default Banner setting allows you to specify a specific banner to be displayed when no other banner is eligible for display and a default account is not eligible for display for whatever reason. Default banners should be uploaded to the server separately. Define the banner URL and target URL in the appropriately titled text fields.
[top]
The Mailer Manager is a simple mass-mailer utility that allows you to mail all users of the exchange. This feature includes some macros to make your life a little easier:
| %username% | Echos the user's Real Name. |
| %login% | Echos the user's Login ID. |
| %email% | Echos the user's e-mail address. |
| %statstable% | Echos the default exchange URL so the users can access their statistics. |
The form supports standard Unix linefeeds (n) for page breaks as well as most common HTML commands. The mailing manager automatically identifies HTML text and sends the message as a mime encoded message. This allows users to read the document in an HTML-enabled mail client.
[top]
The Category Management menu allows you to add, delete, and edit categories. Categories are used by your exchange clients to assist them in targeting their banners to specific pages. Every account should be categorized, even if the category is "Default" or "No Category"
Clicking the category name lists the accounts that currently belong to that specific category.
[top]
This feature allows you to add or remove administrators. Each added administrator has the rights to do everything the original administrator does (everything). This feature is useful if you have multiple users who approve banners, etc.
[top]
This feature allows you to change your password for the currently logged in Administrator.
[top]
A database backup and recovery tool is included with the script. It is recommended you run this tool often, to insure data integrity. Essentially, the database backup and recovery tool uses mysqldump to create a file in the admin/db folder that allows you to recover should the database ever become corrupt.
WARNING: IT IS STRONGLY RECOMMENDED THAT YOU SET UP A .HTACCESS FILE TO PASSWORD PROTECT THIS DIRECTORY!
It is a security risk otherwise, since this directory is globally writable. Contact your hosting provider for assistance with creating an .htaccess file if you do not know how to do this. More often than not, your "Control Panel" feature that comes with your hosting will do this for you.
If you wish to view a dump of the file and save it to your local computer, you may do so by clicking on the filename. This file can then be uploaded should the database ever need to be recovered.
[top]
phpBannerExchange 2.0 RC3 and higher contains a simple, yet powerful templating script that allows you to edit the default template to your liking. This templating system uses the "standard" {item} style tags. to echo variables from the main processing script to the HTML file the user actually sees. A template editor is included within the Admin interface to facilitate the editing of the template files.
Standard tags include:
| {title} | Echos the "name of your exchange - name of the page". Example: "MyExchange - Admin Control Panel Login". |
| {shortitle} | Echos the "name of the page". Example: "Admin Control Panel Login". |
| {menu} | calls the menu file for display on the page. |
| {msg} | Echos a message of some kind, such as "The banner has been edited." or other, similar verbiage. |
| {footer} | Echos the footer file. |
Additionally, there may be tags unique to the specific file you are editing. These tags are relatively self-explanatory.
Every effort has been made to include as much HTML as possible in the template files, however some special functions (such as while()'d statements) have basic table tags included in the PHP scripts.
The script does not currently support creating new files for security reasons.
[top]
This feature allows you to change things in your config.php file. If you decide, for example, to begin selling credits after you have installed the script, you may enable the store through this feature.
An explanation of the variables:
| Database Host: | The host name of your database. This is most likely localhost. |
| Database Login: | The username you use to connect to your database. |
| Database Password: | The password you use to connect to your database. |
| Database Name: | The name of the database you wish to use to store your user data. |
| Base Exchange URL: | The path on the Internet to which you have phpBannerExchange installed. For example, if you have installed the software to the directory "exchange" just off your root directory, the Base Exchange URL would be http://www.yourdomain.com/exchange. Do not include a trailing slash after the directory name. |
| Base Path: | The path (NOT the URL) of where the exchange script is installed. This should be entered automatically by the installation/upgrade script. If it is not, enter the base path (eg: /home/www/exchange). Do not include a trailing slash after the directory name. |
| Exchange Name: | The name of your exchange, as you would like it to appear in the exchange script. This value is displayed under the banner that is served as well as in e-mail and control panel pages. Examples: "The 1:1 Banner Exchange", "Commander Skippy's Banner Exchange" |
| Site Name: | The name of your site. This is used for the legalese in the "Conditions of Use". |
| Admin Name: | Your name or alias. It is primarily used in the footer of each page. |
| Admin Email: | The e-mail address you would like to use to receive exchange related questions, new account notifications, etc. |
| Banner Width: | The width, in pixels, of the banners you would like to support with your exchange. Standard banners are 468 pixels wide. |
| Banner Height: | The height, in pixels, of the banners you would like to support with your exhange. Standard banners are 60 pixels wide. |
| Default Ratio: | This is your default exchange ratio..sort of. The way this works is the first number is how many exposures are required to have one display. For example, setting this value to "3" will require 3 exposures before the account becomes eligible to display a banner. The second number is how many credits the script should take away when the banner is being displayed. So setting this option to "3" will take away 3 credits when the banner is displayed. Some common ratios are listed below: 1 banner display allows 1 banner to be displayed: 1:1 |
| Show Exchange Image: | This will allow you to specify if you wish to display a small image to the left of the banner. Typically, this is a 60x60 image in a 468x60 banner exchange. It will link back to your Banner Exchange main page. |
| Exchange Image Position: | The postion of the exchange image (as described above) relative to the banner itself. Options are Top, Bottom, Left or Right. Selecting Bottom for example, will display the Exchange Image (see below) under the banner. |
| Exchange Image URL: | If you have decided to show an exchange image above, enter the full URL to the image here (eg: http://www.yourdomain.com/image.gif). Otherwise, you may leave this value blank. |
| Show Exchange Link: | If you wish to show a brief exchange text link under the image, set this option to yes, and enter the text you wish to display here. You should keep this brief, something like "Join the (your exchange's name)!" or some such verbage. |
| Require Banner Approval: | This option controls how the banners are validated. You can set this option to No and the account and URL only need be approved, not the banners. setting this option to Yes will force the account into unvalidated mode when a banner is added or deleted. |
| Allow Uploads: | This option allows you to create an upload folder for your user's banners. Setting this option to No will require the user to his his or her own webspace and bandwidth to serve the banner for the exchange. |
| Maximum Filesize: | The maximum filesize you wish to allow your users to upload. A 30K banner would be expressed as "30000", for example. You may leave this value blank if you do not wish to use the upload feature. |
| Upload Path: | The *nix/Windows path to the upload directory. Typically, this will be something like /home/username/public_html/exchange/upload or similar. Do not include a trailing slash after the path. This path must be globally readable and writable (chmod 777 upload_directory). Contact your hosting provider if you are unsure of the path to your html directory. Do not include a trailing slash in the path. You may leave this value blank if you do not wish to use the upload feature. |
| Upload directory URL: | This is the URL to your upload directory specified in the Upload Path variable above. An example of this would be http://www.yourdomain.com/exchange/upload. Do not include a trailing slash in your URL. You may leave this value blank if you do not wish to use the upload feature. |
| Maximum Banners: | This is the maximum amount of banners you wish to allow your users to add to their account. If you would like your users to have the ability to add an unlimited number of banners to their account, set this value to 0 (zero). This feature works for both uploaded AND remotely hosted banners. |
| Anti-Cheat method: | Select the type of anti-cheat method you would like to use. Valid options are DB, Cookie, and None. The Cookies anti-cheat measure that uses cookies to store timeout data for a specific computer. Only after the timeout has expired will credits continue to add up for the account displaying the banner (the timeout value is expressed in a later variable). The DB method is the same as the Use Cookies variable except it does not use cookies: all data is stored in a database and automatically purged when the timeout expires. |
| Duration: | This is the timeout value for the two anti-cheat methods, expressed in seconds. This feature controls how long a client on the banner exchange member's page is not counted as an additional visit and subsequently an additional credit for the exchange member. It is recommended you set this value to a low number, perhaps 20 or 30 seconds. |
| Referral Program: | This option allows you to grant your users extra credits for signing up new users. By linking to your Banner Exchange main directory, (eg: http://www.somesite.com/exchange/index.php) with a special code, your end users can earn extra credits. For anti-cheat reasons, the credit is only granted after the created account is validated. |
| Referral Bounty: | This option is the amount of credits you wish to reward your users with for referring users for the exchange. |
| Starting Credits: | If you wish to provide new users with a set amount of free credits, enter this value here. When validating the account, you may change this amount for any individual account. |
| Sell Credits: | Enables the online store. The credit store will not be visible to end users unless this option is activated, even if there are items available for purchase. See the Online Store section for more details about the online store and configuration instructions. |
| Top x will display X accounts: | This value is used for the "top accounts" feature on the main client login page. Specify the maximum number of accounts you would like to display on this page. |
| Send Admin Email: | If you would like to be notified when a new user signs up to the exchange, click the "Yes" radio button. |
| Use MD5 Encrypted Passwords: | For security purposes, you may encrypt your passwords with the MD5 encryption routine, which is a 32 character hash of the password. Note that passwords will become unreadable (but will still work) when you use this feature. |
| Use gZip/Zend code: | If you wish to compress the pages and send the output as a gZip file, enable this option. This saves some bandwidth, but slows down the server. |
| Log Clicks: | Stores each click's date & time and IP address to the database for your end users. Note that on large exchanges, this could cause the database to get very large. |
| Use mySQL4 rand(): | Enables the mySQL rand() function in the view.php queries. This method is better than the exchange's built-in random algorythm, but requres mySQL 4.x or greater. |
| Date Format: | Select the date style to use. (mm/dd/yyyy or dd/mm/yyyy). |
[top]
The Style Sheet Editor allows you to both select and edit style sheets/skins for the script. A few sheets are included by default.
To add new style sheets, you may simply upload them to the template/css directory within your Banner Exchange directory on your server. Style sheets for phpBannerExchange 2.0 will be available from the phpBannerExchange 2.0 download site (http://www.eschew.net/scripts/). If you wish to edit these files, make sure you set the CSS files in the template/css directory to be world writable (chmod 777). Also, if you do create a new skin, please send it to me so I can share it with the other users.
[top]
This feature allows you to edit the questions in the Frequently Asked Questions area.
[top]
If you are allowing your users to host their own banners rather than uploading them to your server, the Banner Check Utility will save you a lot of time tracking down dead accounts. This tool automatically checks all the banners in the exchange for dead banners, which usually mean a dead account. When this tool runs, any dead banners it runs across are not deleted: the account is returned to an unvalidated state. An administrator can then check the account to insure it is indeed dead.
[top]
The Conditions of Use/Terms of Service document (COU) is there to protect you. The default COU indemnifies you as a Banner Exchange Administrator from any loss the end user incurs. In other words if a user breaks the rules and you decide to delete their account, you can do that because of the COU. Likewise, if your server goes down for a month or similar, the COU protects you from being sued and prevents a lot of general end user whining. It's a good idea to keep the COU as it is, but you may edit it if you wish.
Rules define what your exchange considers appropriate. For example, if you are running a banner exchange for gaming sites, an adult site would probably be inappropriate in your banner rotation. The rules clarify this to the end user.
With phpBannerExchange 2.0 RC2, the COU and Rules are both stored in the database.
[top]
The Promo Manager allows you to add coupons for your users to redeem for credits, a percentage off an item, or a special item that is not listed in the online store. Coupons are CaSe SeNsItIvE and supports most special characters (it has been tested with the usual (!@#$%, etc characters). Additionally, clicking on any promotion that is currently active will allow you to see the accounts that have used this promotion. An explanation of the fields:
| Promotion Name: | The name of the promotion. This is more for your reference than anything. |
| Code: | The coupon code users will need to enter to recieve the promotional item/credits. |
| Type: | There are three types of promotion types available: Mass Credits: A coupon of this type can be redeemed for an amount of credits. You can use this to encourage your users to visit a particular site, provide incentive to sign up for an account, etc. This is the only type of promotion that will work without the Commerce module enabled. XX% off item: Provides a discount expressed in a percentage for any item in the online store. Special Item: Provides a special item in the online store that is only available after the code has been entered. |
| Value: | This field expresses different things for different coupon types. For the Mass Credits type, it does nothing. For the XX% off item type, it expresses the percentage value you would like to use (for example, entering "50" into this field will provide a 50% off coupon). For the Special Item type, it expresses the price of the item. |
| Credits: | The amount of credits associated with the offer. This field is used for all coupon types. |
| Users can re-use coupon code: | Enabling this option will allow the user to re-use the coupon code as many times as he or she likes. No checkmark in the checkbox means that the coupon can only be used one time per user. See the Re-use interval field for more information regarding this. |
| Reuse Interval: | This is an expression in days to define how often a user can reuse a coupon. This is especially useful for the Mass Credits coupon type. You may wish to grant a certain amount of credits every month, for example. If the Users can re-use coupon code option is NOT enabled, this field is not necessary. Setting this option to zero (0) allows the user to reuse the coupon immediately. |
| Eligible User Type: | The type of user that can use the coupon. Valid options are New Users Only and All Users. |
[top]
The Update Manager is an easy way to check for updates to the script from the main phpBannerExchange site. This will also help me, the developer, roll out bug fixes at a faster pace. As files are updated with bug fixes, feature enhancements, and security updates, they will be made available on the phpBannerExchange web site. The script identifies which files are a different version from the currently installed files, and makes them available for you to download. The script DOES NOT install them for you. The only files that are not updated via this feature at this time are template files. Should a template file need to be updated or provided with a new feature, a link to the file will be available via the release notes. The decision was made to not include Template files via the Update Manager due to the fact that many exchange admins change their templates.
This feature requires that the file "manifest.php", which is located in the root phpBannerExchange directory, is world writable (chmod 777).
Detailed information on how this feature works
At the top of each file is a version number. Since I last updated most of the files (with this feature) on April 13, 2005, I chose the string 041305 (mmddyy). The script first opens each file and assigns the version number to an appropriate variable ($FILE_location_filename, so for example, the "addadmin.php" file would be "$FILE_admin_addadmin"), and then output to the "manifest.php" file along with a timestamp and the URL for the master list, which is an XML feed hosted on the eschew.net server.
The master list contains all the current version numbers for the files, so when I upload a new file, the version number in the master list will also be updated. The script downloads the master list, parses it, and extrapulates the version numbers from the XML feed. It then compares the version numbers from the master list with the manifest list version numbers. If they are different, then it offers the files for download as a .txt file. If they are the same, the script does nothing. If there are new updates, the release notes are provided as a link as well.
If you find a new update, right click then choose save link as, or save target as in your browser. Rename the .txt file to .php, then upload the file to your server, taking note to store it in the same place as specified in the link on the update page. Then, run the "Update Only" or "Complete refresh/update" link on the update page to insure the files have been successfully updated.
[top]
Pausing the Exchange allows you to "turn off" the exchange. When the exchange is paused, only default banners and banners from default accounts will be displayed and users will still amass credits.
[top]
If you wish to sell credits for your exchange to your end users, you may do so with phpBannerExchange RC3 and higher. This version of the script introduces a simple e-commerce system that allows administrators to receive payment via PayPal for users who wish to purchase them. This feature uses the PayPal IPN system to instantly verify payment and grant credits.
Be aware that I have NOT tested this feature extensively (or at all with PayPal for that matter) and can not be responsible for malfunction should the IPN feature not work properly (The verification script is a third party freeware script). If all else fails, use the tried and true method of adding the credits to the user's account manually when you recieve notification from PayPal that the payment has been processed.
The only thing that needs to be changed is the "paypal.config.php" file in the "/lib/commerce/" directory. An explanation of the variables are as follows:
| $businessname: | Your paypal account e-mail address. This is the same e-mail address you use to login to PayPal or someone would use to send you money. |
| $ipn_page: | This variable should not be changed in any way. It is reserved for future use, when phpBannerExchange supports more services. |
| $propername: | The proper name of the service you are using. Right now, "PayPal" is the only service that will work with phpBannerExchange. |
| $payment_currency: | The currency type you work with through PayPal. Valid Currency types are: US. |
| $currency_sign: | The currency sign you wish to use. (Note: use a backslash () when using a dollar sign ($)). |
| $currency_int: | The currency type expressed as a suffix. For example. 25 us dollars is expressed as $25 USD. |
| $decimal_separator: | The separator you would like to use in the decimal place, usually, this is a period (.) but can also be a comma (,). |
| $thousands_separator: | The separator used to separate thousands places. Usually, this is a comma (,) but can also be a period (.). |
| $places: | The "cent" places in your currency type. If you use US dollars, it's 2 places. |
[top]
These features help you get along in the software.
Clicking Home takes you to the stats page.
Clicking Logout logs you out of the administrative panel and destroys your session. It is important to do this every time you are finished administering the exchange.
Clicking Help takes you to this document.
[top]
There is no formal support for this script. I neither have the time nor the inclination to provide technical support for this script. You should be OK provided you read the documentation and carefully follow the instructions provided therein.
If you run in to a problem with the script and do need help, you can go to the Support Forums and ask a question.
[top]
Please let me know if you find a bug in the software. I spent a considerable amount of time debugging the script however I can not check everything on my own. If you happen to run across a bug, first check to see if it has already been reported and fixed by checking for updates using the Update Manager. If no files are available or updating does not fix the problem, please report the issue in the Support Forums. Be sure to include a detailed description of the bug you encountered, the error message, or the result condition so I can address the problem.
[top]
If you run across a security issue/vulnerability, please report it directly to me at darkrose@eschew.net so I can make an announcement on the forums once the script has been fixed. These types of problems usually require some sort of exploit and could compromise the security of thousands of machines. If you happen to run across a bug of this magnitude, it is essential that I be notified first so I can protect the security of these machines. Please be aware that support issues sent to this address will be ignored. You will NOT receive a reply support issues if e-mailed to me.
[top]
If you change something in the script or add a new feature, I encourage you to share it with the other users. My vision of what makes a good Banner Exchange script as far as features are concerned might be vastly different than yours, so if you make a modification to the script, I encourage you to share it with me. I plan to make all working mods to the script available for download as an add-on to the base script. If the modification is good enough, I will even include it in a future version of the script and you will receive credit for the code you have submitted or changed. You may e-mail your mods to me at darkrose@eschew.net.
I am seeking assistance with translating the software into different languages. All language files for the script are located in the lang/ directory under your root banner exchange directory. If you translate the files, please provide me with a copy and I will make it available for all users. You may e-mail the translated language files to me at darkrose@eschew.net.
The templates are located in the template/ directory. If you alter the templates or style.css file, please send me your new files and I will make them available to all users. You may email them to me at darkrose@eschew.net.
[top]