[WARNING]
This document is OLD (part of TraceWatch 0.234 documentation).
If you are using latest version of TraceWatch you should not be looking
at this.
Overview
You can use TraceWatch's PHP API to easily fetch statistical information from database to show on your web pages.
This feature is experimental, currently you can only get some basic information.
You do this in three steps, first include /twatch_include/api.php in your page, call twatch_connect() to connect to database then use twatch_value() with appropriate parameters to get the value you want.
<?php
include $HTTP_SERVER_VARS['DOCUMENT_ROOT'].'/twatch_include/api.php';
twatch_connect();
echo twatch_value('visitors','yesterday');
?>
The code above will show number of unique visitors your website had yesterday.
twatch_connect
twatch_connect ( [string instance_id , [string doc_root]] )
This function uses the information in /twatch_include/userinfo.php to connect to and select the database used by TraceWatch. It also sets some global and mysql session variables to be used by subsequent twatch_value() calls so you can't use mysql_connect() instead to connect to database.
Return Value
true if successfully connected to database false otherwise, $GLOBALS['twatch_error'] will contain the error message.
Parameters
- instance_id
- ID of TraceWatch instance to be used, 'default' (default instance) will be used if omitted.
- doc_root
- Absolute filesystem path to TraceWatch installation location. If omitted, function assumes TraceWatch is installed in root folder and will try to determine root folder from predefined PHP variables.
twatch_value
twatch_value ( string value [, string period] )
This function returns the value for the specified period of time.
Return Value
Positive integer value if successful -1 otherwise, $GLOBALS['twatch_error'] will contain the error message.
Parameters
- value
- A string containing space separated words, the first one being name of the value, others being options. Name of the value can be 'page_views', 'visitors' or 'online_visitors'.
- period
- A string representing the period of time for which you want the value. Currently it can be 'today', 'yesterday', 'this_month', 'last_month' or 'all'. If omitted, 'all' will be used.
Values
- visitors
- Number of unique visitors in the specified period of time. This value does not have any options.
- online_visitors [seconds=n]
- Number of visitors with at least one hit in last 10 minutes including current visitor. You can adjust the 10 minutes limit by seconds option:
E.g. 'online_visitors seconds=1200' means number of visitors with a hit in last 1200 seconds (20 minutes).
period will be ignored for this value. - page_views [this_page [with_params]]
- Number of page views of the whole website in the specified period of time.
You can use this_page option to get only views of the page on which twatch_value() is being called. Also use with_params option to take page's parameters into account (this option will not have any effect if you're counting current page without parameters).
'page_views' means number of page views of the whole website.
'page_views this_page' means this page's visits regardless of page parameters.
'page_views this_page with_params' means this page's visits with exact same page parameters.
Notes
- Current hit will be counted in shutdown function so the value you get for page_views and visitors (first hit only) does not include current hit however online_visitors includes current visitor.
- Periods are computed with regards to the TraceWatch's time-zone.