BBClone
Summary
BBclone is a web counter written in PHP. It looks similar to Big
Brother Webstats.
But it is not *just* a counter : BBClone gives a detailed view of the visitors of your web site.
It does it by displaying the nth last users
(and the data they provided, like their IP, browser and so on) that went
of the web site, not just showing a number of visitors. This is very handy
for slow to medium traffic web site webmasters that want to see who visit
their sites, what browser people use, where do they come from etc. Please
note that it's very design, BBclone is not useful for high traffic websites
where you only need agregated data.
Features
For each visitor, BBClone can display
- IP address,
- Hostnames,
- operating system,
- robots,
- browser,
- referring URL (where do they come from),
- visit date,
- number of time the visitor has loaded the page,
- number of visitor
- ranking of the most frequent countries, referrers, OS, browsers, robots, page views and some more
Other features include :
- Localizations: English, French, German, Spanish, Portuguese, Italian, Chinese (Trad. and Simpl.)
and some more
- reload resistance
- hostname resolution
- time statistics
- proxy workaround
- number of visits by a visitor
- logging routine optimized to run *fast* on any website
- blacklist (list of IP that won't affect the counter)
- fancy icons
Installation
<![CDATA[
The following description applies to a generic BBClone installation, that does
not reflect particular weblogs/content management systems. For this purpose it's
recommended you take a look at our links page first,
which features a listing to external resources.
1. Setup
Following code needs to be added to the files you wish to monitor. It's a good
idea to create a test file at first to see whether BBClone is already working.
To do you can use the following sample and point your browser to it.
define("_BBC_PAGE_NAME", "Test");
define("_BBCLONE_DIR", "bbclone/");
define("COUNTER", _BBCLONE_DIR."mark_page.php");
if (is_readable(COUNTER)) include_once(COUNTER);
?>
Attention! You have to customise this snippet to suit your needs.
_BBC_PAGE_NAME
contains the title you want to use for the page. This title will be displayed
in your stats later.
_BBCLONE_DIR
The path to the BBClone directory. Remember the sketch from 1.3?
Now you need the result of your preparation for setting this
variable. You may need to change this entry depending on the
file's location. If unsure, please reread section 1.3. Don't
forget the trailing slash at the end of the directory.
You can also use the following snippet:
define("_BBCLONE_DIR", "bbclone/");
define("COUNTER", _BBCLONE_DIR."mark_page.php");
if (is_readable(COUNTER)) include_once(COUNTER);
?>
This time we left out the page title. If BBClone doesn't find one it will
automatically create one derived from the file's path. This is useful if you
have a lot of pages and want to automate the naming process.
1.5 Adding the counter code to the pages
Now that we tested anything and found it working, we can go on to register
visits. The "traditional" method requires *.php pages. You also need to have
permissions to run PHP (of course). If you want to put your code somewhere
else the file needs to be included into a *.php file eventually, so the server
recognises it and is able to run the PHP interpreter.
Inside of PHP files not everything is necessarily PHP code. Sometimes passages
of code alter with pure html. each PHP codeblock is started with "<?" and ends
with "?>". If you want to add the code within such a PHP code block, you will
have to write:
define("_BBC_PAGE_NAME", "Test");
define("_BBCLONE_DIR", "bbclone/");
define("COUNTER", _BBCLONE_DIR."mark_page.php");
if (is_readable(COUNTER)) include_once(COUNTER);
(or without the page title, see 1.4 for details)
If however you're outside of such a block and find nothing but html tags then
you need to add the php enclosings so the server knows it has to parse this
passage as PHP code. Please note that the server can't run php from within a
*.html file. In this case you would see the counter code "as is" in the html
source
If you run an apache server and are allowed to use .htaccess you can even
monitor your *.html pages without ever editing or renaming them. (Credits go
to Dave Higgens, who first made this suggestion in our forums)
1. Add the following to your .htaccess:
AddType application/x-httpd-php .htm .html
php_value auto_append_file "/the/path/that/leads/to/count.php"
The path needs to be a local absolute path like the example above. Create the
file "count.php" and add the following:
<?php
define("_BBCLONE_DIR", "/the/path/that/leads/to/bbclone/");
define("COUNTER", _BBCLONE_DIR."mark_page.php");
if (is_readable(COUNTER)) include_once(COUNTER);
?>
In our example "count.php" is situated in the www-root. If your files are
located elsewhere you need to modify the paths accordingly (see 1.3). An
absolute path is required to make this snippet work. If you don't know the
absolute path to your BBClone directory you can do the following:
Go to your bbclone directory, open index.php in your favorite editor and add
the line:
echo "<?php\n"
."define("_BBCLONE_DIR", ""
.dirname(__FILE__)."/");\n"
."define("COUNTER", _BBCLONE_DIR.""
."mark_page.php");\n"
."if (is_readable(COUNTER)) include_once(COUNTER);\n"
."?>\n";
Point your browser to it, copy and paste the output and save it into a file as
"count.php" (to stick with our example). Don't forget to remove the line from
index.php afterwards else it will be displayed each time you call your stats.
Now the following will happen:
Each time someone calls one of the ".htm" or ".html" pages the code snippet with
the counter code will be automatically appended. BBClone will automatically
create a page title derived from the file's path which will be used in the page
stats then.
2. Configuration Options
The following is a listing of all configuration options in config.php all along
with explanations and example settings. Note, that most options can also be read
in a localised version by selecting the "Configuration" link on top of your
statistics page.
2.1. Options affecting the visual presentation
$BBC_MAINSITE
If this variable has been set, a link to the specified location will be
generated. The default value is pointing to the parent directory. In case
your main site is located elsewhere, you probably want to adjust the value
to suit your needs.
$BBC_MAINSITE = "http://www.example.com/"; => Link to the specified URL
$BBC_MAINSITE = ".." => Link to parent directory
$BBC_MAINSITE = ""; => Show no link
$BBC_SHOW_CONFIG
BBClone defaults to revealing the stats' settings. In case this behavior
isn't desired you can deny access to it by deactivating the option.
$BBC_SHOW_CONFIG = 1; => Display show_config.php
$BBC_SHOW_CONFIG = ""; => Don't display show_config.php
$BBC_TITLEBAR
The title being displayed in the navigation bar of all bbclone pages.
The following macros are recognised:
%SERVER => server name
%DATE => the current date
$BBC_TITLEBAR = "Statistics for %SERVER generated the %DATE";
$BBC_LANGUAGE
BBClone's default language, in case it hasn't been specified by the browser.
It's strongly recommended you set your language (if listed) because will
encode search engine keywords according to $BBC_LANGUAGE. You can, however,
overwrite the default. See explanation of
$BBC_CUSTOM_CHARSET for details.
The following languages are supported:
bg, ca, cs, da, de, el, en, es, fi, fr, hu, it, ja, lt, nb, nl, pl, pt-br,
ro, ru, se, sl, tr and zh-cn
$BBC_LANGUAGE = "en";
$BBC_MAXTIME
This variable defines the length of an unique visit in seconds. Each hit from
the same visitor within this period will be considered as one visit, as long
as two successive hits don't exceed the specified limit. Default is the de
facto web standard of 30 minutes (1800 seconds), but depending on your needs
you may wish to assign a different value.
$BBC_MAXTIME = 0; => Treat each single hit as unique
$BBC_MAXTIME = 1800; => Treat every hit within 30 minutes by the same
visitor as unique visit
$BBC_MAXVISIBLE
How many entries you want to have listed in the detailed stats? The default
value is 100. It's recommended not to set it higher than 500 to avoid too
heavy load.
$BBC_MAXVISIBLE = 100;
$BBC_MAXBROWSER
Defines the number of browsers to be displayed on the global stats. The figures
represent unique visits.
$BBC_MAXBROWSER = 10;
$BBC_MAXEXTENSION
Defines the number of countries/extensions to be displayed. The figures represent
unique visits.
$BBC_MAXEXTENSION = 10;
$BBC_MAXHOST
Defines the number of hosts to be displayed. Only the actual domain is taken,
any prefixes will be omitted. So in most cases this may be a representative
listing of the internet access providers your visitors are using as well. The
figures are based on unique visits but do not necessarily represent them all
(see $BBC_PURGE_SINGLE for details)
$BBC_MAXHOST = 10;
$BBC_MAXKEY
Defines the number of search engine keywords to be displayed. Although the words
were extracted from unique visitors, they don't represent the number of unique
visits, because one query may contain multiple keywords and not all visitors
will come from a search engine.
$BBC_MAXKEY = 10;
$BBC_MAXORIGIN
Defines the number of referrers left by visitors (if any). The figures represent
unique visits, but the referrers listed there may also come from spambots or
otherwise bad behaving bots. BBClone omits referrers from identified bots so the
noise signal shouldn't be too high.
$BBC_MAXORIGIN = 10;
$BBC_MAXOS
Defines the number of operating systems. The figures represent unique visits.
The detection depends on the user agent string, so there may be occasions, where
BBClone cannot determine an operating system.
$BBC_MAXOS = 10;
$BBC_MAXPAGE
Defines the number of page views. Unlike most other settings this one represents
pure hits.
$BBC_MAXPAGE = 10;
$BBC_MAX_ROBOTS
Defines the number of bots. Bot is defined as any program or script that does
any sort of task automation without any human interaction. So this definition
also applies to download managers, feedreaders or bookmark checkers. The figures
represent unique visits
$BBC_MAXROBOT = 10;
$BBC_DETAILED_STAT_FIELDS
Contains a comma separated list of all columns to be displayed in the detailed
stats. You can choose from:
id => The x-th visitor since you've started counting
time => The time at which the last hit was registerred
visits => The hits of one unique visitor
dns => visitor's hostname
ip => visitor's ip address
os => The operating system (if available and/or no robot)
browser => The software used for establishing the connection
ext => visitor's country or extension
referer => The link from which a visitor came (if available)
The order of the list is also representative for the column's arrangement in the
detailed stats.
$BBC_DETAILED_STAT_FIELDS = "id, time, visits, ip, ext, os, browser";
$BBC_DETAILED_STAT_FIELDS = "date, ext, browser, os, ip";
$BBC_DETAILED_STAT_FIELDS = "id, time, ext, dns, visits, os, referer";
$BBC_TITLE_SIZE
BBClone's top title bar. Size is in "pt".
$BBC_TITLE_SIZE = 14;
$BBC_SUBTITLE_SIZE
BBClone's subtitles. Size is in "pt".
$BBC_SUBTITLE_SIZE = 9;
$BBC_TEXT_SIZE
Ordinary text and column names in time stats. Size is in "pt".
$BBC_TEXT_SIZE = 8;
$BBC_NUM_SIZE
Numeric data within the time stats' charts. Size is in "pt".
$BBC_NUM_SIZE = 7;
2.2. Options affecting BBClone's functionality
$BBC_TIME_OFFSET
In case the server time doesn't match your local timezone, you can adjust the
time in minutes by using this switch. Negative values will set back the time,
positive ones will set it forth.
$BBC_TIME_OFFSET = 300; => Set time forth by 5 hours (5 x 60 min)
$BBC_TIME_OFFSET = -300; => Set time back by 5 hours (5 x 60 min)
$BBC_TIME_OFFSET = 0; => Use the server time "as is"
$BBC_NO_DNS
This options defines, whether IP addresses should be resolved to hostnames or
not. While hostnames tell a lot more about the visitor, resolving them may
considerably slow down your site, if the DNS servers used are slow, limited
in their capacity or otherwise unreliable. Setting this variable may solve
the problem.
$BBC_NO_DNS = ""; => resolve addresses to hostnames
$BBC_NO_DNS = 1; => turn off name resolving
$BBC_NO_HITS
BBClone's default is to show hits in the time stats, because it gives a quite
useful Impression from the actual server load. If, however, you prefer to use
unique visits as base for your time stats, you can change the way of counting
by setting this variable.
$BBC_NO_HITS = ""; => Show hits in time stats
$BBC_NO_HITS = 1; => Show unique visits in time stats
$BBC_IGNORE_IP
This option can be used to exclude particular IP addresses or address ranges
from counting. In case you want to add several expressions, use a comma as
separator. This option does not accept any hostnames, you first have
to convert them to ip addresses. You can, however, leave off octetts from right
to left in order to block ip ranges (as illustrated in the example below).
$BBC_IGNORE_IP = "127., 192.168."; => Ignore specified ranges
$BBC_IGNORE_IP = ""; => Don't ignore anything
$BBC_IGNORE_REFER
In case you don't want to have particular referrers from your visitors listed
in your ranking or detailed stats, you can define a comma separated list of
keywords, each referrer will be checked against with. BBClone uses two variants
of detection:
If the expression starts with a slash, it will be considered a part of the
referrer uri. This is useful for blocking unwanted sites on freehosts
If the expression doesn't start with a slash, it will be compared with the
referrer host only. This is useful for specifying unwanted hosts without
accidentally blocking legitimate referrers from visitors
$BBC_IGNORE_REFER = "spambot.org, /v1agr4/"; => Ignore specified matches
$BBC_IGNORE_REFER = ""; => Don't ignore anything
$BBC_IGNORE_BOTS
You can use this option to determine the treatment of robots. The default is
to ignore them in the top hosts ranking but leave them in the remaining
stats. If you don't want to see any robots at all you can set this option to
"2", then only human visits will be taken into account.
$BBC_IGNORE_BOTS = 2; => Completely ignore robots
$BBC_IGNORE_BOTS = 1; => Don't list hostnames of robots
$BBC_IGNORE_BOTS = ""; => Treat robots as normal visitors
$BBC_IGNORE_AGENT
This option defines how BBClone tells one visitor from another. Default is to
use the IP address only, which provides realistic figures in most cases. If,
however, your visitors often are hidden behind proxy servers, deactivation of
this option could provide more realistic figures, since a new visitor will be
assumed by the time the user agent has changed.
$BBC_IGNORE_AGENT = 1; => Ignore different user agents of one visitor
$BBC_IGNORE_AGENT = ""; => Treat each user agent change of one visitor
as separate visit
2.3. Miscellaneous Options
$BBC_DEBUG
BBClone doesn't display any messages in its counting mode. Time and again,
however you may wish to see what BBClone is doing or why it no longer is
working. That's what the debug mode is for: If you activate it, you'll get a
lot of lengthy messages, which should help you with your problem in most cases.
Remember to turn this mode off again, as it isn't meant to run permanently.
$BBC_DEBUG = ""; => Run BBClone in its counting mode
$BBC_DEBUG = 1; => Turn on debugging for troubleshooting
$BBC_KILL_STATS
Whenever you wish to reset your stats you can activate this switch and have
them deleted by the next visit. Don't forget to deactivate it afterwards,
else you'll probably experience unusually low traffic ;).
$BBC_KILL_STATS = 1; => Erase all collected data
$BBC_KILL_STATS = ""; => Keep all collected data
$BBC_USE_LOCK
Before BBClone writes to a file it attempts to lock the file to prevent it
from being corrupted. Should BBClone complain that it would not be able to
lock files you can set an alternative method by using this switch. As a rule
of thumb you should use the method BBClone is suggesting unless you have a
very good reason not to use it. Possible options are "dio", "flk" and "sem"
$BBC_USE_LOCK = "flk"; => Use flock() (WinNT/2k/XP/2k3, Unix/MacOs X)
$BBC_USE_LOCK = "sem"; => Use SysV Semaphores (Unix/MacOs X only)
$BBC_USE_LOCK = "dio"; => Use Direct I/O (PHP >= 4.2.0 and Unix/MacOs X
only)
$BBC_PURGE_SINGLE
Host, referrer and keyword stats can generate a huge amount of data, however
mostly caused by one time visitors. By enabling this switch you can purge these
entries and considerably shrink access.php in its size without affecting your
actual visible host and referrer ranking.
$BBC_PURGE_SINGLE = 1; => Purge single host, referrer and keyword entries
$BBC_PURGE_SINGLE = ""; => keep all entries
$BBC_CUSTOM_CHARSET
In case there's no translation for your language or you want to use a particular
character set, you can overwrite the language used for converting keywords by
setting your desired encoding here.
$BBC_CUSTOM_CHARSET = "UTF-8"; => Use UTF-8 as encoding
$BBC_CUSTOM_CHARSET = ""; => Use the default charset of the
translation
The BBClone Team (c) 2004
]]></plaintext></body></div>