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 :-
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
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).
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
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.
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.
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 :-
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, Cathonian Software 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 dedicated 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.
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
Simple page-hit counter
In it simplest form, you just need to add the following to your webpage (use source mode not wysiwyg mode).
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.
- 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).
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.
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&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.
- 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.
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 :-
|Page Hits :|