Installation and Usage
for BANNERMATIC Banner Ad System
This copy of BANMATx.ZIP contains the latest revised
edition with all required files for a complete installation.
Revision Dates: banmat1.zip - September 15, 2006
banmat2.zip - September 15, 2006
banmat3.zip - September 15, 2006
Copyright: 1996-2006 by Joe DePasquale
E-Mail: crypt@getcruising.com
Website: http://www.getcruising.com
==============================
This application is for Unix web servers running Perl 5.0 or higher.
Additional documentation is available at http://www.GetCruising/crypt
helpme.txt - How to install Perl scripts on a Unix server.
whatsnew.txt - Revision history for all 'CGI Scripts from the Crypt'.
Also visit the "Users' Self-Support Forum" to post questions and
answers, especially if you have some extra time, knowledge and
a desire to help some other poor lost souls!
THERE IS *NO* FREE *NOR* FEE-BASED TECHNICAL SUPPORT FOR THESE SCRIPTS!
Due to extremely limited time, E-Mail with technical support
questions WILL NOT BE ANSWERED! Please use the available resources
here and elsewhere on the WWW to solve problems.
E-Mail genuine bug reports to: crypt@getcruising.com
==============================
WHAT IT DOES:
There are three versions of BANNERMATIC, each using a different
method to identify and display banners ..
Version 1 (SSI) is the simplest to set up - if your web server allows
server-side-includes. However, since you can't pass a parameter to
the script from an SSI, this version can't record pagecodes and
groups.
Version 2 (Cookies) passes the banner number to the browser as a
cookie. If the user then clicks the banner, their browser sends the
cookie (with banner number) back to the script, and the script can
then redirect user to the sponsor's URL. It's so simple, but
unfortunately, some people fear cookies so disable their software.
Version 3 (Ip Address), is the most versatile and should function with
any web browser, since they all send the 'REMOTE_ADDR' value that
this version uses.
All three versions are similar enough so that you could use all three
on the same website and have them share the same data files, 'bandat.txt',
and 'ban.log'. This allows one copy of 'banman.pl' to control the
data from all three scripts.
The main control file (bandat.txt) has one record per line, with
8 pipe (|) delimited fields per record.
0 = URL the complete url where the user is sent if they click the banner.
1 = IMG the complete path of the banner GIF or JPG file.
2 = URL Ttl, total click-thru's, incremented by the script.
3 = IMG Ttl, total banner views, incremented by the script.
4 = GROUP, an option that restricts showing a banner only on
specified groups of pages. Each group code must be a single
letter or number. Each banner can have any number of group codes
in this field. When the coding you place on a web page contains
a group code, the script will start at the next available banner
and search each banner until it finds one which has the same code
as the web page. If it finds none, it shows the default banner.
5 = Start Date set when banner was added to the bandat.txt file (YYYYMMDD).
6 = E-Mail, address of the sponsor for mailing script-generated
banner statistics reports.
7 = A newline (\n) character.
-------
PAGECODE and GROUP: Versions 2 and 3 Only
These versions send two important variables to the script.
PAGECODE is the page name (or your choice of any alias) where the
banner appears. You cannot use a plus (+) sign or pipe (|) in the
PAGECODE. Best to stick with letters, numbers and the underscore (_) for
composing PAGECODES. Every location on your website which will display
a banner, MUST have its own unique PAGECODE. This also means multiple
banners on the same page must have different PAGECODES. Why? When a
banner is displayed, an association between the PAGECODE and a cookie
(version2) or IP# (version 3) is saved. If a second banner with the same
PAGECODE is displayed, the original association is overwritten. Thus if
user clicked the first banner, they would go to the second location.
GROUP is an optional single alpha-numeric character (A-Z,a-z,0-9). When
passed to the script it causes only banners in that GROUP to appear
on the page. Conversely, if a banner record contains 1 or more GROUP
codes, the banner will only be shown on pages in those groups.
Here is an example of what PAGECODEs and GROUPs do for you ..
Your small 4-page website includes restaurant reviews on pages
'chinese.html' and 'mexican.html', real estate listings on
'forsale.html' and personal info and favorite links on 'index.html'.
You have 6 banner ads .. #1, 2 and 3 are food-related, #4 and 5 are
real estate sponsors and #6 is a 'CGI Scripts from the Crypt' banner.
You could create 3 GROUPS .. 'F' for food, 'E' for real estate and
'X' for default ('none of the above').
Then use these PAGECODEs and GROUPs on the web pages:
chinese+F mexican+F forsale+E index+X
Finally, when adding the banners to the 'bandat.txt' database, fill
in the GROUP(s) of pages where you DO want the banner to display.
Sponsor #1 wants their restaurant banner to appear on only the
'F' group pages - use just 'F' in their banner record. Sponsor #2
wants their restaurant ad on ALL of your pages, so fill in 'FEX'
in the group field of their banner record.
In the "HOW TO USE IT" section are examples of the complete HTML
code you need to place wherever you want a banner to appear.
In summary, each banner can be in any combination of groups, but
each page can be in only one group (or none). Of course the more
groups a banner is in, the more exposures it will get, but its
click-thru ratio will theoretically be higher if you use the GROUP
option wisely.
-------
If you will be using animated GIF banners, choose the option
$cacheFlag = 'Y' when configuring the script. Otherwise the user is
likely to see a 'slide show' of all your banners. The cache flag
disables slide shows but visitors will see the same banner
on a given page until it is erased from their browser's cache.
The BANNERMATIC MANAGER shows current data about all your banners in
table format. Across the bottom of the screen, you will have
button-options for ADD (add a new banner), EDIT (for an existing
banner), DELETE (an existing banner) and UNDO (reverses the last change
you saved). For each banner, the display includes the sponsor's URL
(clickable), the banner name (click to see the banner), total
click-thrus to the URL, total impressions, click-thru success ratio,
groups, starting date and sponsor's E-Mail address (clickable).
There is also a 'SEND SPONSOR REPORT' option which accepts an E-Mail
address and if it matches any address(es) in the 'bandat.txt' file,
the stats are sent to that sponsor's E-Mail address.
'ban.log' has a one-line record added to it each time there is a
click-thru. You can browse this file to see more detail of where your
clicks are coming from and going to.
Version 3 uses 3 additional files: 'banipdat.txt' keeps records of
which visitor viewed which banner, so that if they return to click the
banner, the script will know where to send them. The script runs a
daily refresh for banip.dat which removes IP address records
1 days old or older. Finally, 'banipcnt.txt' keeps a record of the last
day-of-week (0-6) a refresh was run, so that it only runs once a day.
BANNERMATIC uses the Perl 'flock' function to prevent simultaneous
changes (corruption) of data files. Banners are selected by calling
the Perl 'srand' and 'rand' functions.
==============================
INSTALLATION:
1. SETUP YOUR FILES -
You can add your banners using BANNERMATIC MANAGER. If you add them
manually to 'bandat.txt', fields 0 and 1 are required; fields 2 and 3
must be zero or greater; fields 4, 5 and 6 are optional (but
recommended). See "WHAT IT DOES" for an explanation of the format.
Edit 'banstats.htm' in a text/html editor. Find this line and
replace it with the URL to your 'banmatx.cgi' script, where x is the
version type. Your path may differ:
<form
action="http://yourdomain.com/cgi-bin/banmatx.cgi" method="POST">
For VERSION 1 (SSI) ..
It seems there are several ways of implementing Server-Side-Includes.
Usually, you will have to name all the pages with the '.shtml' extension,
indicating to the server that it needs to search the page for a valid
SSI tag. You may have to use '.stm', '.shtm' or some other. Check the
SSI documentation in your web host's Tech Support area.
Here's an example:
<!--#exec cgi="/cgi-bin/banmat1.cgi"-->
You can adjust the width and height tags in the script itself to the
actual banner size you will use. The sample files and set-up are all
the standard of 468 x 60 pixels.
For VERSION 2 (COOKIES) or VERSION 3 (IP ADDRESS) ..
Following are two examples of HTML code which you will place on each
page where banners are to appear. Refer back to "WHAT IT DOES" for an
explanation of how to substitute for 'PAGECODE' and 'GROUP'. If you
don't want to use the 'GROUP' option just omit the '+GROUP' part of
code. Replace 'banmatx.cgi' with 'banmat2.cgi' or 'banmat3.cgi'.
The 'COMMAND' is one of 'IMG' or 'URL' and follows the equal (=)
sign in each example.
EXAMPLE :
<font size=1><a
href="http://yourserver.com/cgi-bin/banmatx.cgi?PAGECODE+GROUP=URL">
PLEASE CLICK TO VISIT OUR FRIENDS AT:<br>
<img
src="http://yourserver.com/cgi-bin/banmatx.cgi?PAGECODE+GROUP=IMG"
border=1 width=468 height=60></a></font>
2. CONFIGURE THE SCRIPT -
Next, open the main script file in a text editor - either
'banmat1.cgi', 'banmat2.cgi' or 'banmat3.cgi' depending on the version
you downloaded. Find the section called "CONFIGURATION" and use the
sample paths and directions to set all the required paths and
variables to the correct values.
3. UPLOAD FILES AND SET (CHMOD) PERMISSIONS -
All .gif and .jpg banners must be uploaded as BINARY files.
All others are ASCII.
Place the .cgi and .pl files into your cgi directory. This includes
'banmat1.cgi', 'banmat2.cgi' or 'banmat3.cgi' (755), 'banman.pl' (644),
and if you are using version 3, also 'banip.pl' (644). Set the
permissions as indicated using the 'chmod' command.
Create a directory named 'banmat' (755) and place 'banbak.txt' (666),
'bandat.txt' (666), 'banflk.txt' (666), 'ban.log' (666) and 'banpwd.txt' (666)
there. If using version 3, you also have 'banipcnt.txt' (666) and
'banipdat.txt' (666) which belong in the 'banmat' directory also.
Place 'banstats.htm' (644) into any www directory. Your banners can be
in any folder accessible from the web on your website or any other website.
==============================
HOW TO USE IT:
If set up correctly (!) just sit back and watch (?) as the script
and your visitors do all the work.
To RUN BANNERMATIC MANAGER, use 'manager' as a query-string.
Examples -
http://www.getcruising.com/cgi-bin/banmat1.cgi?manager
The response should be the password authorization form. The
initial password is 'password'. Of course you should change it soon
to something unique by entering a new password in the
'Change Password' box.
To SEND SPONSOR REPORT, fill in the form -
Example -
http://www.getcruising.com/banstats.html
You will probably want to make 'banstats.htm' available to anyone, so
sponsors can access their current statistics. It takes an E-Mail
address and if it matches any addresses in the 'bandat.txt' file, the
stats are sent to that sponsor's E-Mail address.
==============================
THAT'S ALL THERE IS TO IT!