Introduction to Page-hit and Download Counters

Many websites contain so-called counters. Typically they display the number of times a page has been accessed or the number of times a file has been downloaded. Such capabilities cannot be implemented simply by using HTML since counter information has to stored on the server. Therefore a program must be written to run on the server to increment the counter that you wish to display on your web page. To increment a counter you must call an URL that looks something like this :-
/cgi-bin/counters/counter.pl?name=geewhizz

Let's look at this URL a little more closely. It calls a program called counter.pl located in the /cgi-bin/counters directory of your website. When the program counter.pl runs it is able read the values following the ? character. It therefore knows to use a file named geewhizz read the counter data from it increment that data and save it back in the same file. However in addition to incrementing a data value counter.pl will usually also output some text - the value of the counter. This text is what you want to display on your web page.

Including counter output in a web page

There are two ways this can be done. One requires use of a little javascript (very little - honestly) and one requires use of so-called server-side includes. However there's a wrinkle - depending on which method you choose the text output of the counter program must take a different form. Therefore the method you use is usually determined by the counter program. However just one of the features of Unicounter is that it can output text in both formats.

We'll come back to the problem of displaying the counter value later. First let's consider :-
- the two basic counter types - download counters and page-hit counters.
- reduction of false increments by IP tracking.
- pay-per-click advertising (ppc).
- caching.

Page-hit Counters

These simply count the number of times a page is accessed. This is the simplest form of counter. Typically instructions to call the counter program are placed at the bottom of the page causing the output data - the value of the counter - to be placed at the bottom of the page. The output from the counter program will be something like 723. On its own this is not very pretty so you should ensure that the HTML code around this data displays it in say bold red against a white background together with a few words like Page Hits since March 1st 2004. Some counters may generate output with formatting included but Unicounter outputs plain text.

IP Addresses eg 123.109.001.099

Ok a page counter is pretty simple but consider this. Suppose the page concerned when loaded checks whether it requires a frameset and if so reloads itself into one. This page will have been loaded twice but only one counter increment is appropriate. (If the frame reload code is placed above the counter code this may not actually be a problem unless the counter is called using a server-side include (SSI) but this example serves to make a point.)
More commonly if the user moves back and forth between pages and you want to count actual visitors to your site rather than page hits you need to distinguish between several users visiting your web page and a single user visiting several times. This can only be achieved by tracking IP addresses so if a counter does not have this capability you will never know how many actual visitors you are getting. Unicounter can maintain a list of up to 16 of the most recent IP addresses and only increments if the current visitor's IP address is not on its list. Of course you are not required to use this feature.

Computers often connect to the internet through a proxy-server. In this case Unicounter records the IP address of the proxy.

Pay-per-click (ppc) advertising

Many search engines (and some other sites) offer pay-per-click services in order to generate revenues. They should implement sophisticated methods to detect bogus multiple-clicks by well let's just call them saboteurs. Such methods should include but not be limited to IP tracking. If you place a ppc contract with a company such as Google you will want to know if the charges they make to you tally with the visitors they send to your website. You definitely need an IP-capable page counter. Indeed you should arrange that each referrer has their own unique counter. This is not difficult but is beyond the scope of this discussion.

Download Counters

Suppose you wish to count the number of times a file is downloaded from your website. In theory this could be achieved by calling the counter URL using the ONCLICK event of the link. However this method cannot be used to count downloads initiated from other sites. Instead a download counter is usually given the responsibility of delivering the required file after incrementing the count.

Adding a download counter to a web page requires two modifications - one to display the count and one to increment it. Some solutions will therefore consist of two programs. Unicounter however includes all functionality in a single program.
Some websites only publish download links that refer directly to the file to be downloaded so you may be obliged to let downloads initiated from other sites go uncounted.

Installing Unicounter on your web server

Unicounter is a perl script. If you wish to use a single instance of Unicounter to maintain counters for several pages and/or downloads it should be installed in its own directory. Normally you will have to place it within a subdirectory of /cgi-bin. e.g. create a directory called counters in the /cgi-bin directory and upload unicounter.pl into this directory. When uploading you must use ASCII mode otherwise the end-of-line markers may be invalid and the script will fail.

The Unicounter package when unzipped contains relevant parts of this website.
All files required for installation and testing are located in the script directory.

Internet Explorer and FTP

If you use the built-in FTP capabilities of Internet Explorer to upload your files you've got a problem - it does not seem to support ASCII mode so you will have to use the command-line program ftp.exe. You will need to use the commands open (to connect) ascii (enter ascii mode) cd (change directory) dir (get directory list) send (upload the program) and quit.

Access Rights

You must set the access rights of the script file and the directory to 755. If you have command-line access to the server this is typically done using the chmod command. If you are using Internet Explorer right click the directory and choose properties from popup menu. An array of boxes will be displayed representing 9 attributes. The Owner must have complete access (all three boxes ticked). Other groups should be given execute and read access. Repeat this process for the script file unicounter.pl

Testing the installation

To verify that it has been installed correctly open a browser window and type in an url of the form :-
http://www.yourdomain.com/cgi-bin/counters/unicounter.pl?name=test&create=23

If it is working correctly the returned value should read document.write('23'); This will appear in the main window of the browser. If it fails do the following.

Check that the case of each url character is correct. URLS ARE CASE SeNSItive !!!!
Check that you have set the access rights correctly for both the script file and the directory.
Check that you uploaded the script file in ASCII mode. This ensures end-of-line markers are translated correctly.
Check that unicounter.pl is located in the /cgi-bin directory (or a subdirectory thereof).
Check your webserver tech support pages and ensure that the path to perl directory corresponds exactly with the value on the first line of the script file. (Open the script file with a plain text editor such as Windows Notepad and if necessary adjust and upload the new version. NB The first two characters of the line must be #! Also check that the file is not obviously corrupted - there should be no strange characters. If there is a strange character at the end or beginning of each line it is because the end-of-line markers have not been translated correctly. Try using a different editor such as Windows Wordpad but be sure to save any changes in plain text mode.)
Try renaming the script file unicounter.cgi.
Finally try uploading in BINARY mode. This may work if your server is running Windows rather than Unix/Linux.
If none of these helps you will need the help of a webmaster or some other tech support. Unfortunately SKARO.NET cannot offer such support.

If you are planning to use server-side includes you should also check how this feature is enabled. Typically filenames with the .shtml extension will be supported automatically.

Caching - yet another problem

Assuming that it is installed and working we have another issue to consider - caching (pronounced 'cashing'). To understand this problem we must first think about how the internet actually works. When you request a file on a computer perhaps on a different continent the file may pass through around a dozen servers before it reaches you. Now consider a server somewhere in the middle of that chain. It would make sense to store files that pass through so that there is no actual need to demand an original copy from the source the next time it is requested. This is common practice helps to keep the internet running smoothly and is called caching. However the output from a counter may vary each time it is called so caching the output of the counter is not a good idea. So all we need to do is turn off caching - if only life were so simple!!!

Whilst most internet servers may support the most recent versions of the HTTP communications language some may not. We are therefore left with a variety of methods to switch off caching. Three options are documented in the Unicounter script file but only one is used. You may wish to edit the file and choose a different option.

Ok let's find out if caching is a problem or not. First of all lets enable caching. To do this add &cache=1 to the url and press ENTER. The displayed value of the counter will increase. If you repeatedly press ENTER to reload the url the counter value will probably remain unchanged (indicating caching is active). If you hit the REFRESH button (at the top of the browser window) or press F5 the value of the counter should be incremented. Thus you should note that reentering an url typically results in a cached response but refreshing usually results in an uncached response. So let's try turning off caching. To do this adjust the url to read &cache=0 and press ENTER. The value of the counter will definitely increment. Ensuring that the url address box is focussed press ENTER again. If caching has been turned off successfully the value of the counter should increment. If not you will have to edit the file unicounter.pl and select one of the other methods listed upload the new version and retest.

If the cache value is not specified cache=0 is assumed.
When entering the parameter cache=0 you must use numeric zero not the letter O.
If you edit any script file it MUST be saved in plain text format. For small editing jobs Windows Notepad will suffice - this works only with plain text so there is nothing to worry about. If end-of line markers are not displayed correctly in Notepad try using Wordpad instead.
Specifying the value cache=1 should only be required in exceptional circumstances.

Sneaky Trick

There is a way to ensure that the counter url is (almost) never affected by caching - add a dummy parameter pair &rand=value to the url ensuring that value is random. You will need javascript to create the random value - use the Math.random() function. This parameter pair will be ignored by the counter program but the servers don't know that so even if the result is cached it is never likely to be used again since the random value will change every time it is called. However I imagine some network engineers may object to this practice - if widely used with large pages it could slow down the whole internet.

Tracking IP addresses

Finally try setting name=test2 and add &trackip=8 to the url. This will create a new counter with IP address tracking enabled. It will store up to 8 most recent IP addresses. Hopefully repeated refreshing will cause counter output to remain constant. This indicates that IP tracking is working correctly. However this feature may fail on some servers.

The parameter trackip will be ignored unless a new counter is created. Thereafter it is read from the counter file.
If you wish to change the value of trackip you must delete the counter data file before calling the counter url with a new value. Alternatively if you have a suitable text editor you may edit the file.
The purpose of this restriction is to prevent unauthorised adjustment of the counter.

Installing Unicounter into web pages

As mentioned previously there are two ways that counter output can be integrated into a web page. These methods require javascript or server-side includes. Unless you currently use server-side includes in your website I recommend you stick to javascript.

Simple page-hit counter

In it simplest form you just need to add the following to your webpage (use source mode not wysiwyg mode).

<script type="text/javascript">
  document.open; // Not all browsers require this but it is strongly recommended unless called previously
  document.write("Page hits = ");
</script>
<script type="text/javascript" src="/cgi-bin/counters/unicounter.pl?name=MyPageCounter&amp;trackip=8">
</script>

Ok let's explain exactly what this does.
The first pair of <script> tags encloses two statements. The first instructs the browser to get ready for what comes next. The second inserts a short text prefix before the counter value. The second pair of <script> tags simply calls the counter program which outputs the following text.

document.write('1');

The numeric value will vary.
You should normally ensure that all text placed beside the counter is static rather than created dynamically using document.write statements.
The parameter trackip is ignored unless a new counter file has to be created.
Whilst the Unicounter script expects parameters to be separated by & characters these must be encoded in web pages as & when called using <script> or <a> tags etc. (but not when using server-side includes).

Server-side includes
The server-side include version is somewhat simpler but may not be available on all servers or may need activation. You must add something like the following to your web page. Again you must perform editing in source mode.

Page hits = <!--#include virtual="/cgi-bin/counters/unicounter.pl?name=MyPageCounter&trackip=8" -->

The text "Page hits = " will be displayed before the value of the counter.

Download Counter

Adding a download counter will require two changes to be made to your existing webpage.

1: Triggering the counter

You must change the HREF value of the link. Your web-page editor may allow this to be done by other means however I shall detail the necessary changes required to the source code.
Your existing link will look something like this.

<a href="geewhizz.zip">Click here to download</a>

This will have to be adjusted to read something like this.

<a href="/cgi-bin/counters/unicounter.pl?name=geewhizzdownloads&amp;deliver=http://www.mywebsite.com/geewhizz/geewhizz.zip">Click here to download</a>

The deliver parameter requires the full url.
trackip is ignored unless a new counter has to be created.
The & character must be encoded as &

2: Displaying the counter value

This is exactly the same as displaying a page-hit counter except that you must add an additional parameter when calling the counter url. This will stop the counter value being incremented.

inc=0

You must use zero not the letter O.

Tips and Tricks

Using tables or style sheets to improve appearance

Every cell in a table can have its own color. A page-hit counter is typically placed centrally at the bottom of the page. To give the counter a bold appearance you may use a table with a single cell. However download counters are typically displayed next to the download link. Given that tables cannot be inserted into lines of text you may prefer to use a style sheet thus.

Normal text <span style="background-color:blue; color:white">counter text</span>

Creating secret counters

If you wish to monitor but not not make public your site traffic you need a page counter that is not displayed. Unicounter makes this very easy - all you have to add the parameter write=0 to the counter url. You can then create a secret web page that displays all your counter values together. Just remember to add the parameter inc=0 to each counter url on this page.
Also see pictorial counters.

Naming conventions

If you use Unicounter to track both page-hits and downloads use a sensible naming convention such as geewhizz_ph and geewhizz_dl to denote page-hits and downloads respectively.

Resetting the counter to a value of your choice

Using an FTP client (or built-in browser capabilities) simply delete the counter data file (not the perl script).
Call the perl script using an url of the form :-
http://www.yourdomain.com/cgi-bin/counters/unicounter.pl?name=mycounter&create=123

Page Hits :

Keywords

Unicounter free page-hit counter free download counter free website counter free internet counter

Links

SKARO.NET : Shareware and freeware programs for Windows

Maverick : Program launcher / application launcher & toolbar with integrated utilities

Enforcer : Anti-piracy / registration SDK for software developers

Zipfusion : Zip self-extractor (sfx)

WipeDir : Uninstall utility for developers