tòmò web analytics
Copyright since 2011 by Yves Goergen
Website: http://unclassified.de/go/tomo
Licence: GNU General Public License (GPL) Version 3
Encoding: UTF-8 (without BOM) (auto-detect: °°°°°)

This file contains general notes on installation and usage.


ABSTRACT
========

tòmò is an embedded web analytics software. That means that you do not need to set up a separate server or configure sites and accounts. Just put it somewhere on your webspace, add a bit of HTML (or PHP/Python/…) code to your existing page and you’re done. tòmò will automatically track all visits and follow your visitors around, recording what they look at and do.

Through its intuitive query interface, you get real-time information about your visitors just the way you need. What pages are most popular? What languages do your visitors prefer? What browser window space and plug-ins can you design with? What countries or regions do your visitors come from and who sends them to you? How is your latest advertising campaign going and how long does it keep visitors on your site? How quickly loads your page? From these questions, you can continue with individual queries to get all the statistics you can think of.


REQUIREMENTS
============

tòmò is a web application written in PHP and JavaScript. The server-side components require PHP 5.3 to run (earlier PHP 5 may work but has not yet been tested). For the database, PHP must have SQLite support. Although tòmò’s database layer supports other databases like MySQL or PostgreSQL, these have not been tested. SQLite has some functions that would need to be added to other DBMS as user-defined functions to run some statistical queries.

The client-side JavaScript module should work in any browser since the year 2000 and remain silent in older browsers. Cookies support is highly recommended. JavaScript support makes it a lot nicer. I have tested with the following browsers:

* Internet Explorer 6-8 on Windows XP
* Internet Explorer 9 on Windows 7
* Internet Explorer 10 on Windows 8
* Firefox 1-16 on Windows XP and 7 (wrong adblock detection up to 2.0)
* Chrome 15, 21, 22 on Windows XP
* Opera 9, 11.5, 12.0 on Windows XP (activity timespan less reliable)
* Safari 5.1 on Windows XP

(The latest tòmò version is only tested with the latest stable Chrome release at that time.)

tòmò does not support multiple sites or cross-domain use. You must install a copy of the tòmò server files on every domain and subdomain that you want to track. You can share the GeoIP/GeoLite files and the tracking database between multiple instances though, if you can specify a path in your server file system from one instance to another, or to a common place to store those shared files. Be aware that, if you use a shared database, all tracked requests are collected in one single group, so all analyses will run over all sites’ requests if not further filtered by domain name. This may be useful if you operate multiple subdomains that are somewhat related to each other.

As a consequence of this, visitor and session identification currently will not work across domains. When a visitor passes from one tracked domain to another, a new session will be started for requests on the other domain, and the visitor will not be recognised as returning but will in fact be assigned a different identification value for each domain. You can somewhat guess such a relation from timing, referrer and other session details in the full visitor log though. This guesswork may be implemented in the future.

A note about online translation services: tòmò has been specifically tested with Google Translator and is working fairly well in Firefox, Chrome and partially Internet Explorer (tested in 7-9, unknown for IE6 and 10). Since the web pages are embedded into a different domain, limited cross-domain support is required for activity tracking and in-page action tracking to work. Current Firefox and Chrome versions support that. Internet Explorer supports it from version 8 on, but effectively won’t report activity or in-page actions at all. The reason for this cannot be determined. IE 9 has even been observed to miss certain page requests entirely every now and then.


INSTALLATION
============

To install tòmò on your website, please perform the following steps:

Server side
-----------

* Unpack the downloaded release archive (not the source package)
* For first-time setup:
  - Copy the file config.inc.php.dist to config.inc.php
  - Copy the file tomo.db.dist to tomo.db
* Copy all files (except doc, src and tools) into a directory on your webspace

That’s it. And don’t overwrite the two files config.inc.php and tomo.db when upgrading because these files are where your configuration and tracking data are!

In the configuration file config.inc.php you can tweak a few settings. The file has some comments in it so you can learn about the settings right there. tòmò comes with an empty database already, so there’s nothing to set up for it.

Client side
-----------

To add tracking for a web page, some code must be inserted into that HTML page.

To enable page load time tracking, this JavaScript code should be inserted as far at the beginning of the HTML code as possible, at best directly at the beginning of the <head> element. It is optional. If it is left out, the page load time tracking will be unavailable.

	<script type="text/javascript">
	var _tomoStartTime = new Date();
	</script>

Another script must be inserted that runs the whole tracking thing. It loads the tòmò JavaScript file which will automatically do its job when loaded. If JavaScript is disabled or unavailable in the browser, the <noscript> tag loads an image that will at least track the basic page request albeit with no extended browser information. This code should be inserted at the end of the page, at best directly before the closing </body> tag:

	<input id="tomoHistoryInput" type="hidden" />
	<script id="tomoScript" type="text/javascript" src="/path/to/tomo/?autostart=1"></script>
	<noscript><img src="/path/to/tomo/?imgns=1&amp;pt=...&amp;re=<?php echo urlencode($_SERVER['HTTP_REFERER'])?>&amp;rnd=<?php echo mt_rand(0, 999999)?>" alt="" style="display: none;"></noscript>

Replace all occurrences of “/path/to/tomo/” with your actual URL to the tòmò directory. The URL should not contain a protocol or domain, just a relative (or maybe absolute) path to the directory on your webspace. This will automatically adopt to https requests as necessary and is generally the most portable method. Cross-domain tracking is intentionally not supported by tòmò anyway, so don’t even try (see Requirements above).

For the <img> element above, please set the “pt” parameter as the page title according to the page you insert the code into. If you can do that programmatically, do it. The <img> element also uses PHP code to determine the original page’s referrer which would otherwise be unavailable to the tracker if invoked as a resource from the page itself. If your page is written in another programming language, you should be able to adapt the code. If it’s plain HTML, you can remove the “re” (referrer) parameter (and the PHP code) from the image URL, losing referrer tracking for non-JavaScript requests. The second PHP snippet only makes the image URL more random to really bypass any aggressive web cache along the way. This is normally optional and the rnd parameter can safely be removed, it is ignored by the tracker.

XHTML and <noscript> note: If your page is served with the content type application/xhtml+xml or text/xml, some browsers (Firefox and Chrome at least) will parse the page in XML mode and load every resource they find – including those within a <noscript> element! tòmò should recognise such double requests and update the first logged pageview accordingly. Firefox documents this in bug 342299 <https://bugzilla.mozilla.org/show_bug.cgi?id=342299>.

Background database cleanup
---------------------------

To make use of the background database cleanup, you need to have access to cron jobs. This can purge old and unused data that is used for temporary visitor recognition at a time with low visitor frequency. By performing this task automatically in the background, you’ll also not have to wait for it when accessing the viewing interface every couple of days.

The script must be invoked like this if the .php extension is mapped to PHP CLI:

	/path/to/your/webspace/tomo/index.php cleanup

If this does not work, you can use the full syntax:

	php /path/to/your/webspace/tomo/index.php cleanup

It is recommended to run this once a week. The viewing interface will perform this task directly if it hasn’t been running for 14 days. To run it every Sunday on 3:15 am, use this schedule:

	15 3 * * 0


EXTENDED TRACKING
=================

You can customise the tracking a bit by not using the autostart feature and calling JavaScript API functions to configure more parameters. For example, to also set the page language and a custom session variable, you can use the following code snippet instead:

	<input id="tomoHistoryInput" type="hidden" />
	<script id="tomoScript" type="text/javascript" src="/path/to/tomo/"></script>
	<script type="text/javascript">
	tomo.setPageLanguage("ja");
	tomo.setSessionVariable("mySessionVar", "bla");
	tomo.start();
	</script>

If your page is available in multiple languages and you don’t use the first URL path level as language identifier (like in example.com/ja/about), you can tell tòmò about the language of the currently displayed page with the setPageLanguage call. Please use short language codes, like two-letter ISO 639-1, because they are stored in plain in the database with every page view. Do not use language names like “Norwegian Nynorsk”, “Traditional Chinese” or the like.

When not using the autostart parameter for the script request, you need to explicitly call tomo.start() to track the pageview.

You can also set custom variables along the page lifetime, like when the user clicks on a link that changes something on the page. Just invoke the setSessionVariable function like in the above example and the new data will be sent to the server automatically.

TODO:
* Distinguish custom variable scopes
* Explain more JavaScript API functions
