                             DOCUMENTATION

       WebAdverts 2.01 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 or for setting up a "banner exchange" between
your site and others.  Banners can be displayed on your pages either
through SSI calls, so that each time a page is loaded, a new banner will
appear, or via standard IMG tags.  (Banners may also easily be included
on CGI-generated pages.)  Multiple "zones" can be established, allowing
certain banners to appear only on certain 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 (overall and daily)
without viewing anyone else's.  Banners can be "weighted" to control
how often they are displayed, and can automatically be expired from the
rotation after a designated number of exposures, click-thrus or days.
(Alternately, they can be set to display with a frequency based upon the
frequency with which other banners are displayed on the advertiser's
site.)  Individual banners can be of any size and don't all have to be
consistent; WebAdverts can keep track of the height and width, as well
as of the ALT and link texts, for each banner individually.  (Optionally
requires SSI.)

WebAdverts is shareware.  If you use it, please register it!  The
registration fee is only $50 (US).  Payment should be sent via check or
money order to Darryl C. Burgdorf, Affordable Web Space Design, 3524
Pacific Street, Omaha NE 68105.

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

The files that you need are as follows:

ads.pl:  The small configuration script which should be called via SSI
  or IMG tags on your HTML pages to display banners.  (You can set up
  different "zones" for banner display simply by setting up multiple
  configuration scripts.)

ads_display.pl:  The script which actually handles the banner displays.
  It is referenced by the configuration script.

ads_admin.pl:  The administrative maintenance script.  With this script,
  you can add, edit and delete adverts.  It also allows you (and your
  advertisers) to check on how well your various adverts are performing.

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

SETTING UP WEBADVERTS:

Setting up the script is quite easy.  You'll first need to set up a
directory to contain your data files.  Make sure, of course, that it is
set world-writable ("chmod a+w <dirname>").  You can put the scripts in
that same directory, if you like, or in another directory; the latter is
to be prefered, though, for security reasons discussed below.  (On some
servers, you'll have no choice; it may be that your scripts *have* to be
in your CGI-BIN directory.)  Make sure that the first lines of your
configuration script and the admin script point correctly to the
location of Perl on your system, and be sure that both those scripts are
set world-executable ("chmod a+x <scriptname>").  The display script
itself does *not* have to be executable, as it won't be called except
from another script.

Make sure that the "require" statement in the config script shows the
correct full path to the display script, and define the following
variables.

In the display config script:

$adverts_dir:  The full server directory path (not the URL) to your
  adverts data directory.  Note that this directory does not need to
  be -- and in fact should *not* be -- the same directory within which
  your scripts are contained.  For security purposes, this directory
  should be password protected or (better yet) inaccessible to Web
  browsers.

$display_cgi:  The URL (not the path) of your configuration script.  If
  you're using zones, you'll have more than one config script; each of
  those scripts should point this variable to itself.

$advertzone:  The advertising zone.  If you're not using zones,
  simply leave this variable undefined.  If you *are* using them, see
  the "zoning" section below for a detailed explanation of how to do so.

$ADVUseLocking:  Under most circumstances, this variable should be
  defined as 1.  Set it to 0 only if, for whatever reason, your server
  doesn't support the flock() command.  (If this variable is set to 0,
  a semaphore-based file locking will be used instead of flock(); while
  it works reasonably well in most situations, it isn't nearly as
  efficient.)

$ADVLogIP:  If you set this variable to 1, WebAdverts will maintain
  running log files of the IP addresses which have viewed or clicked on
  each advert during the previous 12 hours.  If this logging is in
  effect, any "multiple" views or clicks from a single IP address will
  *not* be recorded.  This can make your info tracking a bit more
  reliable, and will also prevent an exchange member from artificially
  inflating his display count in order to earn more exposures for his
  own banner.

$DefaultBanner:  You can, if you choose, define this variable with the
  name of one of the adverts running on your system.  If you do so, that
  advert will be displayed at any time when (for whatever reason) the
  system isn't able to find an eligible advert via the normal routines.
  Note that this assignment is far more useful with non-SSI setups
  (banner exchanges) than with straight SSI-based advert runs.

$Ztext, $Zalt, $Ztarget, $Zwidth, $Zheight, $Zborder:  These variables
  allow you to set "zone-wide" defaults which will override a specific
  banner's defined link text, ALT text, link attributes, HEIGHT, WIDTH,
  and/or BORDER values.  This could be useful if on a particular page
  you want all adverts to have a certain consistent "look" which is
  unrelated to how they might look on any other pages.  (OK, fine, I
  frankly don't think this *is* all that useful.  But it was requested,
  and it was easy to implement.)  Of course, these settings will have
  absolutely no effect on anything if you're using IMG-based rather
  than SSI-based banner calls.

$ExchangeName, $ExchangeURL, $ExchangeLogo, $ExchangeLogoWidth,
  $ExchangeLogoHeight:  See below.  These only need to be defined in
  the display script if you want an "exchange logo" button included
  with the banners generated by SSI calls.

In the admin script:

$adverts_dir:  This variable is identical to the $adverts_dir variable
  in the config script.

$admin_cgi:  The URL (not the path) of the admin script itself.

$nonssi_cgi:  The URL (not the path) of the config script you want
  referenced by non-SSI (IMG tag) banner calls.  If you are using
  exclusively SSI-based banner calls, this variable can be left
  undefined.  If you're running a banner exchange, and have more than
  one config script (for multiple zones), this variable should point
  to the one you want referenced by your exchange members who don't
  specifically select one themselves.

%nonssi_cgis:  If you want to set up certain "zones" and then allow
  exchange members to be able to define the zones in which their banners
  will be displayed and the zone from which banners will be displayed on
  their own pages, then you'll need to set this variable with a series
  of "sets" (zone name and corresponding non-SSI config script).  For
  more information, see the section "Using Zones in a Banner Exchange"
  below.  Note that you still need to define $nonssi_cgi, as well, with
  the generic config script to be used by those who *aren't* only
  calling banners from a specific zone.

$UseLocking & $LogIP:  These should be set the same as the similarly-
  named variables in the config script(s).

$AdminDisplaySetup:  If you leave this variable set to 0, the admin
  display will simply show you all accounts.  If you have a large number
  of accounts, though, setting this variable to 1 will allow you to
  select which accounts to view (expired, active, those in a particular
  zone, those awaiting administrative approval, etc.) each time you
  load the display.  This can make the admin page much more manageable
  with large banner exchanges, for example.

$AllowUserEdit:  Setting this variable to 1 will allow banner exchange
  members a limited ability to edit their own advert information.  Note
  that new entries may still have to be approved by the administrator
  before they're put into the live rotation.  (See below.)

$RequireAdminApproval:  Setting this variable to 1 will require that the
  administrator approve any advert added or "self-edited" by an exchange
  member.  Setting it to 0 will allow everything to be part of the live
  rotation immediately, without admin intervention.  (The latter is
  *not* recommended.)

$DefaultDisplayRatio:  If you're allowing users to edit their own data,
  you'll want to set this variable to the standard display ratio used in
  your exchange.

$DefaultWeight:  The default weight for banner exchange member banners.
  Normally, this should be left at 1.

$DefaultLinkAttibute:  The default "link attribute" (e.g.,
  "TARGET=_top") to be assigned to banners if called via SSI tags.
  
$bodyspec:  Any attributes (BACKGROUND, BGCOLOR, TEXT, etc.) which
  should be assigned to the <BODY> tag on admin pages.

$header_file and $footer_file:  The full paths to optional text files
  containing HTML code to be placed at the top and bottom of admin
  pages.  This allows you to include certain "standard" information
  (links to exchange rules, for example) on all of the pages generated
  by the script.

$ExchangeName:  The name of your banner exchange.  If supplied, this
  will be used in the default HTML code supplied to exchange members
  for use on their own pages.

$ExchangeURL:  The URL of the "home page" for your exchange.  This
  should be the general information page that you want people to see
  first.  Like the name above, if supplied, it is used in the default
  HTML code supplied to exchange members.

$ExchangeLogo, $ExchangeLogoWidth, $ExchangeLogoHeight:  Optional image
  URL and size designations for a "Link Exchange"-style button graphic
  which can automatically be included to the left of exchange member
  banner displays.

$ExchangeBannerWidth & $ExchangeBannerHeight:  If you require all
  exchange members to use a specified banner size, you can define these
  variables with the designated height and width to ensure that the size
  attributes are included in the IMG tag in the HTML code supplied to
  your exchange members.

$email_address:  Your e-mail address.  The "@" character in your address
  must be "escaped" with a backslash (e.g., "scripts\@awsd.com").  

$mailprog:  The absolute path to your system's sendmail program.  (Note
  that this is *not* the same as the "mail" program, and has absolutely
  nothing to do with Matt Wright's "formmail" or any other CGI script.)
  If your system doesn't have "sendmail," you can instead define the
  variable as "SMTP" to instruct WebAdverts to access your server's mail
  server directly.  (The former is preferable if available, of course,
  as it's more efficient.)  Please note that the use of WebAdverts'
  e-mail functions is entirely optional; if you simply don't want to do
  so, simply leave this variable unassigned.  As well, the e-mails are
  of use only to those running exchanges, and not to those running
  straight advertising, as the notifications in question are (a) an
  e-mail message to the administrator whenever a user joins or updates
  his stats and thus requires new admin approval and (b) an optional
  message to the user whenever such approval has been granted.

$WEB_SERVER & $SMTP_SERVER:  If you're using a direct SMTP interface,
  you can define either or both of these variables with the relevant
  server names.  If you leave them undefined, the script will attempt
  to determine for itself what the names should be.  If you're using
  sendmail, of course, these variables are irrelevant.

FINALLY, if you're using Perl 5 rather than Perl 4, *and* are utilizing
the direct SMTP interface rather than the "sendmail" program, uncomment
the "use Socket" line in the config file.  (In other words, remove the
initial hash mark symbol.)  Otherwise, just leave it alone.

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

USING WEBADVERTS:

All advert maintenance is handled through the ads_admin.pl script.  To
access the administrative functions, load "ads_admin.pl?admin".  (The
QUERY_STRING addition -- "?admin" -- tells the script to let you access
the admin functions rather than merely the user info display functions.
If you simply load "ads_admin.pl" without the "?admin" addition, you'll
only be given the users' option to view a particular advert.)  Input
your administrative password, and you'll be ready to go!

(The first time you access the admin page, you'll be asked to
assign an 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.  You can also create "groups" of adverts (not to
be confused with the "zones" explained below), which will simply allow
your advertisers to view the stats for all of their adverts on a single
page.

When you add a new advert to the list, you will be asked for quite a few
pieces of information.  Most are optional; how (and how often) the
banner appears will be determined by what you input.

              -------------------------------------------

Name & E-Mail:  The name and e-mail address of the advertiser or
  exchange member.  These are included for your reference only.

Start Day:  If you so desire, you can have WebAdverts wait a certain
  number of days before beginning to display the advert.  If you don't
  input a value, displays will begin immediately.

Expiration:  You can allow an advert to run until it has been displayed
  a certain number of times, until a certain number of people have
  "clicked" on it, or until a certain number of days pass.  Once the
  banner has expired, it will no longer be shown in the rotation;
  however, you *will* still have access to its statistics from the admin
  page.  No advert information will be deleted by the script without
  your specific instructions!

Display Ratio:  If you're setting up a "banner exchange" system, you'll
  probably want to define this variable instead of or in addition to
  defining a set number of exposures.  This tells the script how often
  to display a banner based on how often the member displays other
  banners on his own site.  For example, a display ratio of 2 tells the
  script to display the advertiser's banner once for each two exposures
  that someone else gets on his site.  If this variable is set to a non-
  zero value, the status displays for the advert will include an example
  of the HTML code which should be placed on the advertiser's page to
  pull banners from the exchange.  And yes, the script *does* check to
  make sure that a member's banner isn't displayed on his own pages.
  (Non-integer values are allowed, by the way, so if you wanted, for
  example, for exchange members to earn two exposures for each three
  displays -- a 3:2 ratio -- you could set this variable to 1.5.)

Site URL:  The URL address to which a user will be sent when the banner
  is "clicked."  THIS IS OPTIONAL!  By leaving this undefined, you can
  easily create "display only" banners.  The URL does not have to point
  to an actual Web site, by the way; "mailto" URLs are also valid here.

Banner URL(s):  The URL address or addresses for the banner(s) to be
  displayed with the advertisement.  You can optionally include more
  than one banner, putting each URL on a separate line.  If you do so,
  each time the advert is called in rotation, the script will randomly
  determine which banner to actually display.  Note that the banners
  do *not* have to reside on your own server.  So long as the URLs are
  valid, it doesn't make a bit of difference to the script where they
  are located.  If no banner is defined, the script will assume that
  the account is for a remote "display only" site.  This allows you
  to set up exchanges similar to the "Commonwealth Exchange" in which
  members on various sites all display adverts from paying advertisers
  rather than from each other.

"Weight":  This setting influences how often a banner is displayed.  If
  you set the weight to "0" the banner won't be displayed at all.  (This
  can be handy if you set up an advert before you've received payment or
  before your customer's requested start date, for example, or if you
  want to take something out of the rotation on a temporary basis.)  If
  you set the weight to "1" the banner will be displayed each time it
  comes up in the normal rotation sequence.  If you set it to higher
  numbers, the banner will be displayed less often.  (For example,
  setting the weight to "2" will cause the banner to be displayed every
  other time it comes up in the rotation, setting it to "3" will cause
  it to be displayed every third time, etc.)  You don't necessarily need
  to use the weight setting at all.  It is primarily intended to allow
  you to "push" certain advertisers' banners more heavily than others.
  Note that you must *always* have at least one advert available with
  a weight of 1 (and actually, generally, *most* of your adverts
  should have a weight of 1).  If you do not, you will find that on
  some cycles, *no* advert will be available for display, and you'll
  end up with no banner at all on your page.

"Zone(s)":  The zone or zones (separated by spaces) in which you want
  the advertisement to be shown.  If you want it to be shown in all
  zones, or if you aren't using zones, simply leave it undefined.  For
  more information on zones, see below.  (If you've defined the
  %nonssi_cgis variable, instead of a simple text box, you'll see
  two select boxes.  One will allow you to select the zone or zones
  in which the banner will be displayed, and the other will allow you
  to select, if appropriate, the zone from which banners will be
  displayed on the relevant exchange member's pages.

Password:  The password which 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!

Link Attributes:  Any attributes which you want included in the
  banner's link tag.  Unless you use frames on your site, you probably
  won't have much use for this, and can safely leave it undefined.  If
  however, you want a new browser window to open when the banner is
  clicked, or if you have the banner inside frames and want to be sure
  that the frames are removed from the destination page, define this
  variable accordingly (with, for example, TARGET="_top").  (If none of
  that makes sense to you, you probably don't need to worry about it.)

Banner Width & Height:  The size (in pixels) of the banner to be
  displayed.  Defining these variables can make page display a bit
  faster; however, they are not required.  In fact, in certain
  situations, you might *not* want to define them.  For example, if
  you simply load the banner from your advertiser's server, it might be
  changed without your specific knowledge, and the new banner might not
  be the same size as the old one.  Similarly, if you've defined several
  banner URLs for the advert, they might not all be the same size.

Border:  The setting for the BORDER attribute of the banner's IMG tag.
  The default setting of "2" will put a standard link border around your
  advert.  In most cases, this should not be changed!  However, if for
  some reason you need to change the size of the border (or eliminate it
  completely), you can do so here.

ALT Text:  The text you want to appear in place of the banner itself,
  for the benefit of those who can't or won't load the image.

Link Text:  Optional text which will appear either above or below the
  banner, as you prefer.

"Raw" HTML:  A way to override just about everything above, by actually
  specifying the particular HTML code that WebAdverts should insert on
  your pages.  A complete discussion of "raw" mode appears elsewhere
  in this document.

              -------------------------------------------

You also have the ability from the advert add/edit page to reset the
start date, exposure count and click-thru count.  This can be useful,
for example, if an advert expires and is later renewed.

Finally, you also have the option to print out a simple list of the
names and e-mail addresses of all your advertisers or exchange members.
This can be useful, for example, if you desire to send out a "mass
mailing" to let all your advertisers know about upgrades to your
system.

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

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

When the page is parsed by the server, the tag will be replaced with
the appropriate banner and link.  You will, of course, have to make sure
that the tag points to the correct location of the script on your
system.  (If you're unfamiliar with the use of SSI tags, you can find
more extensive information online in the WebAdverts FAQs file.)

To display a banner without SSI, include a link and image tag similar
to the following:

  <A HREF="ads.pl?banner=NonSSI;page=01"><IMG SRC="ads.pl?page=01"></A>

You can "fancy it up" however you like; just make sure that both the
link and the image call point to the correct config file and that the
"?banner=NonSSI" is tacked on to the end of the link address and that
both the link and image address include the (same) "page" number.

Note that the "page=" designations should be different on each page (or
at each location) from which you call a banner.  Even if you're only
calling a single banner on a single page, you need to include the "page"
designations, as without them, the script will not function correctly.

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

SSI VS. NON-SSI:

As a general rule, if you have the ability, you should *always* use
an SSI call instead of an IMG tag.  The processing is slightly faster,
and the resulting banner will be less generic.

The biggest disadvantage of SSI calls, of course, other than the fact
that they simply can't be used on some servers, is the fact that they
can't be used "across system boundaries."  If you're going to run a
"banner exchange" system, you'll *have* to use IMG tags.

Note that *both* SSI and non-SSI calls can be used to display adverts
from the same "pool"; it is perfectly feasible to have pages on your
own site display banners with SSI tags while remote sites *also* pull
banners from your rotation using IMG tags.

IMG tag calls *do* offer one additional option, though.  If you wish to
show a single banner advert in a particular location, if you're using
SSI tags, you can only do so by assigning it its own zone.  With IMG
tags, though, you can specify the advert simply by adding an extra entry
("setdest=<ID>") to the QUERY_STRING.  For example, if you wanted to
always show an ad named "rugrats" in a particular spot, you could call
it as follows:

  <A HREF="ads.pl?banner=NonSSI;setdest=rugrats;page=01">
  <IMG SRC="ads.pl?setdest=rugrats;page=01"></A>

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

RUNNING A BANNER EXCHANGE:

If you're running a banner exchange, you'll want initially to set up
each member's account as you would an account for a normal advertiser.
Assign the "display ratio" as appropriate, so that a certain number of
banner display's on the member's site will generate an exposure of that
member's banner on someone else's site.

Once you've completed entry of the member information, you'll see on
the response page an example of the HTML code which should be inserted
on that member's pages to display banners.  (That same info is visible
any time the member checks his own stats.)  The HTML code provided will
allow the script to keep track of which member's site displayed the
banner, as well as, of course, of what site the user should be sent to
if the banner is clicked.

If you desire to do so, you can allow members to enter or edit their own
information.  If you've set the $AllowUserEdit variable to 1, anyone
will be able to create a new advert simply by entering a new name and
password, or to edit an existing advert so long as they know the correct
password.  The edit screens in this case are "stripped down" versions
of the full administrative edit screen; users can only edit their name,
e-mail address, site URL, banner URL and password.  When a new advert
is created by a user in this way, it is first put on a "to be approved"
list on the main admin screen.  Until the administrator approves it (by
"editing" it, with or without actually making any changes), it will
*not* appear in the actual rotation, though the new member may begin
immediately to accumulate credits by displaying banners on his own
site.

Note that you should always have at least one "pure" banner in your
rotation.  What I mean by that is that there should be at least one
banner which is *not* displayed solely on the basis of a specified
display ratio.  (You can use the spot like "Link Exchange" does, to
advertise the exchange.)  Even if you've specified a "default" banner,
it's still a good idea to have at least one advert in the exchange which
is *always* available to be displayed.

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

"ZONING" BANNERS:

WebAdverts allows you to set up "zones" for your adverts, in order to
ensure that certain banners are seen only on certain pages.  You do so
by setting up separate configuration files.

Assume, for example, that you want to treat your main page as one
"zone," and all your other pages as a second zone, since you plan to
charge advertisers more to appear on your main page than to appear on
your other pages.

You could do so by setting up two configuration files, "zone_A.pl"
and "zone_B.pl."  In the former, you'd define $advertzone as "A"
($advertzone = "A";), and in the latter, you'd define it as "B."  Your
main page would then include an SSI tag calling zone_A.pl, while your
other pages would include SSI tags calling zone_B.pl.

(When using IMG tags, you don't need separate configuration scripts.
You can simply add "zone=<zone>" to your QUERY_STRING.)

When you enter new adverts, you would define the adverts' zones as
either "A" or "B," as appropriate.  Those adverts assigned to zone A
will show up on your main page; those assigned to zone B will appear on
your other pages.

If you want a particular advert to be able to appear in *either* zone,
either define its zone as "A B" or leave it undefined.  (Any advert with
no zone defined will be shown in *all* zones.)

Note that all of your adverts still comprise a single list, and can
still be maintained with a single admin script.

If you want to be able to show *all* your advertisers on a single page,
create a config file with the $advertzone variable defined as "ShowAll"
($advertzone = "ShowAll";).  Any time that config script is called,
*all* of your current adverts (those which have not expired and which
have a non-0 weight) will be displayed.

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

USING ZONES IN A BANNER EXCHANGE:

Zones themselves work the same regardless of whether you're using SSI-
or IMG-based calls.  However, while with SSI-based calls, the manual
assignment of zones for banners works fine, if you're running a banner
exchange, things are just a bit more complicated.  You can't expect your
members to "pick" zones appropriately at random; you need a way to let
them know which zones exist and to allow them to select appropriately.

Hence the %nonssi_cgis variable.

If you leave this variable unassigned, your banner exchange will be
untargeted.  All members will reference the same config script to call
banners (the script referenced in $nonssi_cgi), and all banners (unless
you, as the administrator, specifically assign them zones) will be
eligible for display on any page.

If, on the other hand, you assign a value to this variable, you
introduce targeting -- which can be used to split banners and pages into
categories based on topic, age-appropriate content, or whatever else you
come up with -- into your exchange.

Let's say you've set up four zones, "G" (config script zone_G.pl), "PG"
(config script zone_PG.pl), "R" (zone_R.pl) and "X" (zone_X.pl).  You'd
define the %nonssi_cgis variable as follows:

  %nonssi_cgis = (
    'G','http://foo.com/ads/zone_G.pl',
    'PG','http://foo.com/ads/zone_PG.pl',
    'R','http://foo.com/ads/zone_R.pl',
    'X','http://foo.com/ads/zone_X.pl'
    );

Now, when you or a member add or edit an advert in the exchange,
you'll be able to select the zone or zones in which the banner can be
displayed, as well as the zone (unfortunately, only one) from which
banners will be displayed on the member's page.  When the advert data is
displayed to the member, the appropriate CGI script will be referenced
in the "cut and paste" HTML code presented.

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

INCLUDING BANNERS IN CGI OUTPUT:

Since you can't include SSI tags in CGI output, you'll have to use
one of two alternative methods if you want banners to appear on your
dynamically-generated pages.

First, of course, you can simply have your CGI script include in its
output HTML a link and IMG tag similar to the following:

  <A HREF="ads.pl?advert=NonSSI&page=XX"><IMG SRC="ads.pl?page=XX"></A>

As noted earlier, the "XX"s should be replaced with unique "page"
numbers; the simplest way to accomplish this is to have your CGI script
generate a random number to be inserted.  That way, you can ensure that
each page created by your script will generate a unique banner call.

The second option is to simulate an SSI call to the script.  To do this,
essentially, all you have to do is include the contents of your config
script as a subroutine in your CGI, as shown below.  (The $ADVNoPrint
variable is an addition necessary in this case to suppress the printing
of the "content type" line; the $ADVQuery null definition will ensure
there are no conflicts between WebAdverts and any QUERY_STRING info
your other script may use.)

              -------------------------------------------

sub insertadvert {
	require "/full/path/to/ads_display.pl";
	$adverts_dir = "/full/path/to/ads";
	$display_cgi = "http://foo.com/ads/ads.pl";
	$advertzone = "";
	$ADVUseLocking = 1;
	$ADVLogIP = 0;
	$DefaultBanner = "";
	$ADVNoPrint = 1;
	$ADVQuery = "";
	&ADVsetup;
}

              -------------------------------------------

In the portion of the CGI script that prints your output page, simply
add a call to the subroutine (&insertadvert;) in the location where you
want the banner to be displayed.

For example, if you want the banner to appear immediately at the top
of your page, the CGI code might look something like the following:

              -------------------------------------------

print "<HTML>\n";
print "<HEAD><TITLE>CGI Output Page</TITLE></HEAD>\n";
print "<BODY>\n";
&insertadvert;
print "<P>Text of page.</P>\n";
print "</BODY></HTML>\n";

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

USING "RAW MODE" BANNERS:

"Raw" mode allows you to actually specify the particular HTML code that
WebAdverts should insert on your pages.  If you want to include in the
rotation a banner from an advertiser who requires certain HTML code or
banners from a network such as Link Exchange, this is how you do it. 
Note, though, that if you do so, what you enter in the "raw mode" text
input box will be copied exactly onto your pages when the banner is
called.  The ability to include "raw" HTML can be handy, but use it
carefully.  It would be quite easy to "screw up" your pages if the HTML
inserted here is incomplete or incorrect.

Generally speaking, if you utilize "raw mode" for your banner entries,
whatever you input will be copied *exactly* onto your Web pages. 
WebAdverts will be able to track the number of times the advert was
displayed, but nothing more.  You won't get click-thru data.  But
there are a few tricks available to allow you to let WebAdverts modify
this supposedly unmodifiable text.  Some banner exchanges utilize
a numbering system to keep track of separate banner calls.  (WebAdverts'
own "page" designations in IMG tag calls serve as an example of this.)
If you wish to put such a number in the raw mode entry, simply include
"<RAND>" where you want a random "page" number inserted.  And if you
want to be able to track click-thrus as well as exposures, include
"<URL>" immediately before the destination URL in the HTML entry.  This
will insert a "pass-thru" reference to your WebAdverts script and enable
WebAdverts to log the click-thru before sending the user on to the
banner's real destination.

As an example, let's assume that you want to include banners from an
outside banner exchange, which happens to utilize WebAdverts, in your
site's normal advertising banner rotation.  If the code with which you
were provided by the exchange looked like this:

<A HREF="http://foo.com/ads.pl?member=rugrats;banner=NonSSI;page=01">
<IMG SRC="http://foo.com/ads.pl?member=rugrats;page=01" WIDTH=400
HEIGHT=40 ALT="Foo Exchange"></A>
<BR><SMALL>Foo Exchange</SMALL>

Then inputting the following into the "raw HTML" text input box for the
account displaying the exchange's banners would allow you to track the
number of click-thrus, as well as ensure that each time the banner is
called, a new page number is used and thus a new call is made to the
remote host server:

<A HREF="<URL>http://foo.com/ads.pl?member=rugrats;banner=NonSSI;
page=<RAND>">
<IMG SRC="http://foo.com/ads.pl?member=rugrats;page=<RAND>" WIDTH=400
HEIGHT=40 ALT="Foo Exchange"></A>
<BR><SMALL>Foo Exchange</SMALL>

(Note the placement of the <RAND> tags and the <URL> tag.)

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

SENDING E-MAIL NOTIFICATIONS:

If you have a file called "welcome.txt" in your adverts data directory,
you'll have the option each time you add or edit an account of sending
the contents of that file as a "welcome" e-mail message to the account
holder.  An example "welcome.txt" file is included in the downloadable
program package.  The <--UserID-->, <--Password--> and <--HTMLCode-->
"comment" tags are, of course, replaced by the program with the actual
information for the particular user being e-mailed.

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

GENERAL SECURITY NOTE:

The directory containing your data files should be password-protected
or (better yet) should be located somewhere inaccessible to browsers.
You probably don't want random passers-by snooping about in your
advertisers' or exchange members' data.  This is especially important
if you're running an exchange in which members can update their own
information, as if someone can read the data files, they can read
the individual members' passwords, as well.

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

REGISTERING WEBADVERTS:

WebAdverts is shareware.  If you use it, please register it!  The
registration fee is only $50 (US).  Payment should be sent via check or
money order to Darryl C. Burgdorf, Affordable Web Space Design, 3524
Pacific Street, Omaha NE 68105.

(If you happen to live in a country other than the United States, you
can write a check in your local currency for the equivalent of $57.50.
That will cover the $50 registration fee and the $7.50 service fee which
my bank charges.  Please do *not* write me a check in US funds drawn on
a non-US bank; the service charge for those can be anywhere from $10 to
$25!)

The unregistered version of the script is not crippled in any way.  I'm
not trying to "coerce" anyone into sending me money.  But I don't think
it's an unreasonable request.  I believe WebAdverts is a commercial-
quality product; a *lot* of work has gone into its creation.  If you
use it, I'd appreciate it if you would be kind enough to send in the
registration fee.  I'll be that much more likely to be able to continue
spending time and effort on the scripts in the WebScripts collection,
and you'll have the satisfaction of knowing you did the right thing.  ;)

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

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) files <http://awsd.com/scripts/faqs.shtml>,
or ask on the WebScripts Forum <http://awsd.com/scripts/forum/>.

-- Darryl C. Burgdorf
