Requirements
============

 - PHP at least version 4 (?)
   (Written and tested on 4.3.11)
   (Tested on 4.3.10)
 - MySQL at least version 4 (?)
   (Written and tested on 4.0.24)
   (Tested minimally on 3.23.49)
 - GD (graphics library) for PHP, for graphical reports
   (Written and tested on version 2.0.28)

Installation
============

Given a server which meets the requirements above, first extract the
archive.  Copy the vs_config.php.default file to vs_config.php, then
change at least the variables set in the mandatory section to match
those of your site and database server.  NOTE: When you change/save
the vs_config.php file, make sure there is nothing before the <? at
the top, and nothing after the ?> at the end.  Extra characters here
will break the graphs.

Upload these files including
the customized vs_config.php file onto a directory on your server.
We will assume that you have chosen a folder named "vicestats" so
from now on refer to the directory you have made when you see that.
This directory should be within your site's document root.

Navigate to the page:

http://www.example.com/vicestats/vs_install.php

With your web browser, where www.example.com is your domain name.  Now
simply follow the instructions.  When this process is complete you may
optionally navigate to this page:

http://www.example.com/vicestats/vstrack.php

And then:

http://www.example.com/vicestats/

Your visit to vstrack.php should show up in the reports at the page
just above.  If so, everything is working!

Now, to track visits to your site, you must include the file "vs.php"
in all pages you want to track.  This may be done, for example, like so:

<?
@include_once($_SERVER["DOCUMENT_ROOT"]."/vicestats/vs.php");
?>

With changes to match the actual directory you have chosen.  If you
have followed the suggestions made here, then this should work fine
without modification.

Alternately, you can use the javascript based tracking script.  This
script can be inserted on any web page, .php, .html, .asp, whatever!
The code to put this tracking script on your page looks like this:

<script type='text/javascript' src='/vicestats/vs_js.php'></script>

Again, assuming that /vicestats/ is the location that Vice Stats is
installed into on your web server.  For this method to work, two files
within the directory must be world available (i.e. not password
protected, etc).  These are vs_js.php and vs_img.php.

The javascript snippet above runs a bit of code that automatically
renders the proper image tag to transmit the page event to Vice Stats.
You may, also, encode the resulting <img> tag directly into your
page, though that may cause errors it is still available for pages
where you cannot insert javascript.  In such a case, you may also
include the 'vs_img=off' parameter to turn off displaying of the
logo image even when the global configuration is set on.

That's it!  As suggested by the installer script, these files can now
be safely removed, though you might want to keep some for reference:

 - browscap.ini
 - ip-to-country.csv
 - mysql-create-tables.sql
 - vs_config.php.default
 - vs_install.php
 - vstrack.php
 - All documentation (the all uppercase named files)

Multi User Installations
========================

As of version 0.4, Vice Stats supports tracking multiple web sites with
a single installation (source and database).  To work properly, the
$vs_defaultUser config setting must contain the value "multi" and the
user ID must be supplied at run time.  

Special codes generated when the user accounts are created are used to
make sure that page tracking is recorded only to the proper account.
When logged in as a regular user, a link is available to show the exact
code that may be used for tracking pages for that user.

When logged in as user 1, you may administer users.  At this point, there 
exists the adding, editing, and listing of users functionality.  The 
default username and password of user 1 are both 'vsadmin'.  It is suggested
that you change this default password.

Do not use the admin account (user 1) for recording statistics.

Upgrade
=======

For upgrading from any version from 0.1 up to 0.3, you may simply extract
the distribution archive into the original installation directory.

As of version 0.4, the database structure has changed.  You will need to
completely remove any existing installation (source and database) and
install from scratch.