WebAdverts

                             DOCUMENTATION

       WebAdverts 1.04 by Darryl C. Burgdorf (burgdorf@awsd.com)

                  http://awsd.com/scripts/webadverts/

              ===========================================

WebAdverts is a comprehensive system for maintaining a set of rotating
banner ads on your site.  Banners are displayed on your pages through
SSI calls, so each time a page is loaded, a new banner will appear.  (A
separate script can also be utilized to include banners on CGI-generated
pages.)  WebAdverts keeps track of exposures and click-thrus for each
banner, as well as of the average total number of exposures per day.
Individual passwords allow each of your advertisers to view their own
advert stats without viewing anyone else's.  Banners can be "weighted"
to control how often they are displayed, and are automatically expired
from the rotation when their maximum number of exposures or click-thrus
is reached.  Individual banners can be of any size and don't all have to
be consistent; WebAdverts keeps track of the height and width, as well
as of the ALT and link texts, for each banner individually.  (Requires
SSI.)

              ===========================================

The files that you need are as follows:

ads_admin.pl:  The administrative maintenance script.

ads.pl:  The script which actually displays the banner ads.  It is
  called via SSI tags on your HTML pages.

ads_cgi.pl:  An alternate version of the above script which can be used
  to insert banners on CGI-generated pages.

ads_all.pl:  Another script, called via SSI, which displays *all* of the
  adverts in the current rotation on a single page.

ads_configure.pl:  The script utilized by all of the above scripts to
  define certain key variables.

              ===========================================

SETTING UP WEBADVERTS:

You'll first need to set up a directory to contain your files.  Put the
various scripts into that directory, and make sure they are all set to
be world-executable (use "chmod a+x" or "chmod 755").  You'll need
to create two empty text files, adcount.txt and adpassword.txt, and set
them both world-writable ("touch adcount.txt", "touch adpassword.txt",
"chmod a+w adcount.txt adpassword.txt").  Finally, you'll need to create
a subdirectory which will contain the advert stats, and set it world
writable ("mkdir ads", "chmod a+w ads").

(On some systems, executable files must be located within the CGI-BIN
directory, but access to text files in that directory is not allowed.
If that is the case on your system, simply locate all of the text files
in a separate directory elsewhere.)

Make sure that the first line of the ads.pl, ads_admin.pl and ads_all.pl
scripts point correctly to the location of Perl on your system.  (No
such reference exists in the other two scripts, as they are both called
only from within other scripts.)  Make sure that the "require" statement
in each of the scripts shows the correct full path to the configuration
script.

Once all that is done, you'll need to assign several variables in the
ads_configuration.pl script itself.  They are as follows:

$advertcount:  The absolute path to the "adcount.txt" file.

$adverts_dir:  The absolute path to the directory in which your advert
  data files will be stored.  You may want to password protect this
  directory (via a .htaccess file) to prevent miscellaneous visitors
  from accessing the data files directly.

$advertspasswordfile:  The absolute path to the "adpassword.txt" file.

$advertcgi:  The URL of the "ads_admin.pl" script.

$gotoadvert:  The URL of the "ads.pl" script.

$AdvertTracking:  This variable defines whether you want to base banner
  display on total exposures or total click-thrus.  It should be set to
  "1" if you sell banner space on the basis of total exposures and to
  "2" if you sell instead based on the number of click-thrus.

              ===========================================

USING WEBADVERTS:

When you visit ads_admin.pl with your Web browser, you'll be presented
with a page containing a password input box and two buttons:  one allows
you to view the stats for a specific advert, the other allows you to
view the stats for all your adverts and also allows you to access other
administrative functions.

The first time you choose to view all the stats, whatever you've typed
into the password box will be assigned as your administrative password.
On future visits, you'll need to type that same password again, or you
will be denied access.

From the administrative page, you can add, edit or delete adverts, or
change your password.

When you add a new advert to the list, you will be asked to identify the
maximum number of impressions allowed, as well as the URLs of the banner
itself and of the page to which it should link.  (Note that the banner
itself can reside anywhere, even on another system, as long as you can
view it in a Web browser.)  You will also be asked to assign a specific
password to the advert.  This password will allow your client from the
main ads_admin.pl page to view the stats for his particular advert only.

DO NOT assign specific banners the same password that you use for
administrative functions!

To display adverts on a particular page, simply insert an SSI command
pointing to the "ads.pl" script.  It should look something like the
following:

<!--#exec cgi="/ads.pl"-->

You will, of course, have to make sure it points to the correct location
of the script on your system.

If you use a CGI script to generate pages dynamically, you can include
banners on those pages with the adsub.pl script.  Simply "require" the
script in your CGI program and then call the "insertadvert" subroutine
(&insertadvert;) from the program to insert the banner while the page
is being generated.

              ===========================================

This documentation assumes that you have at least a general familiarity
with setting up Perl scripts.  If you need more specific assistance,
check with your system administrators, consult the WebScripts FAQs
(frequently-asked questions) file <http://awsd.com/scripts/faqs.shtml>,
or ask on the WebScripts Forum <http://awsd.com/scripts/forum/>.

-- Darryl C. Burgdorf