Global Stats's tracking code has functions you can use to log any action you want on your website, and declare goals via javascript events. We also offer a way to log data from internal scripts. This is not possible with other services, as they don't document how their incoming tracking API works, and they rely solely on the referrer to verify information. Global Stats is different.


Tracking code functions


gtxp.log( href, title, type )

Call this function whenever you want to log a custom visitor action, e.g. a click on a button or menu, with which you can specify a URL, title, and type:

href
required
The URL you want logged for this action. Outbound links need to start with http/https, all other actions need to start with either a / or a #. If you just want to the log the literal URL in the anchor tag, use the value this.href, without quotes.
title
optional
The text you want to show up next to the URL. Try this.innerText (without quotes) to grab all the text in between <a> and </a>.
type
optional
The type of action you are logging. If left blank, it defaults to 'click' (event). Other options are 'download', 'outbound', and 'pageview'.


If you just need this in a few places, inline code is quick and easy as shown below. Otherwise, you probably want to add it to your core javascript functions that handle things like menus so you can automatically and dynamically track all of them in one place.

<a href="#menu/home" onclick="menu('home'); gtxp.log('#menu/home','Home'); return false;"><img src="media/menu/home.gif"></a>

gtxp.goal( id, revenue )

This function lets you declare goals from any javascript event, such as when the user clicks a button or downloads a file. An action will not be logged when calling this function. It just flags the visitor as having achieved the goal.

You can also track goals with the gtxp_custom.goal variable, but it's important to note that these two methods are very different from each other. gtxp.goal() should only be called by a javascript event. Any other usage may have unexpected results and is not supported.

gtxp.goal takes 2 parameters:

id
required
This can be a number representing a goal's numeric ID already configured for your site (listed in a site's goal set up area), or a string to define the goal "on the fly". The goal management page for any website lists the ID for each goal next to the goal's name. You'll need to specify the ID for the goal you want tracked when you call this function.
revenue
optional
If the result of this goal is always a fixed amount of revenue, you can easily specify that. However, if the value varies with each visitor, your code will need access to the value of the revenue, either through javascript, cookies, or internally. You will need to talk with your web developer(s) and/or your shopping cart provider to implement this functionality.


Examples: <a onclick="gtxp.goal( '10', '9.95' );" href="mailto:me@me.com">Email me!</a>

<a onclick="gtxp.goal( '10' );" href="http://different-web-site.com">Different website</a>


Dynamic goal examples: <a onclick="gtxp.goal( 'Clicked email' );" href="mailto:me@me.com">Email me!</a>

<a onclick="gtxp.goal( 'Downloaded file' );" href="/song.mp3">Download now!</a>





Logging data from an internal script

Global Stats lets you log data from an internal script, such as PHP, ASP, Perl, etc. Other services don't offer this feature because they don't document their incoming "API", and they only verify incoming data from the referrer. Global Stats is different.

This feature is useful in scenarios where data logging would not be possible with an external service such as Global Stats. For example, many sites use internal redirects for outbound links. Because these internal redirects do nothing but "redirect", a full HTML page is never actually loaded on your website, so our tracking code can't load and execute. But now, you can log data internally from that redirect script before sending the user on their merry way. This may introduce a slight delay in the redirect, but the benefit should outweigh the cost for most websites.

Even better, you can also use this to update sessions at a later time. You can add custom data, goal completions, and goal revenue, even if the session is expired and happened 30 days ago. The goals in particular should be useful for those of you who are unable to embed our tracking code, or custom javascript variables, in your shopping cart pages. You can find the session ID on Global Stats at a later time, and then update it using this code. (We plan to add a way to do this directly from your stats as well in the near future).

If you have used the stats API at all, you should be familiar with the Site Key. This is like a password to access your data. The site key is for reading data only, however. For writing data, we have created the admin site key. Anyone with access to your admin site key will be able to log data to your stats, so you should not share it with anyone. Both site keys are available from the main preferences page for any site.


How to talk to our tracking servers

The page you want to talk to is at http://stats.gtxp.com/in.php. This is the same script that our tracking code talks to. You just need to send the right parameters, and we'll log it.

How do you send data to this script, from your script? All web languages have functions that can talk to external scripts on remote servers. In PHP, one such function is file. There are other functions available, the main difference being how the data from the remote script is returned to you, but that doesn't matter for this usage. in.php will not return anything to you.

Most default installations of PHP allow these functions to talk to remote servers like ours, but an administrator does have the ability to turn this feature off. Make sure to ask your administrator or web host if this feature is enabled, otherwise you will have to use another method such as cURL, which is not documented on this page.


Required parameters

These first 3 parameters are required with all requests below. They are all available from the main preferences page for any site on Global Stats. Additional parameters are necessary depending on what you are trying to do. Each type of call is documented further down.

site_id
required
Every site on Global Stats has its own unique ID. This is that.
sitekey_admin
required
There's the sitekey, and then there's the admin sitekey. This one allows you to write data to Global Stats. Do not share this key with anyone else.
ip_address /
session_id
required
You must include one of these, so we know who this data is for. Generally, you're going to specify the IP to log actions "live" as they are happening (since you won't know the session ID at the time), and you'll want to use the session ID when you are updating a session at a later time to add a goal or custom data to it. You can get the visitor's IP address in PHP with $_SERVER['REMOTE_ADDR']. If you forget to include both of these, Global Stats will use the IP of the connecting machine instead, which in this case would be your server's IP - not what you want!


IMPORTANT! Always URL encode all parameters that you send. Otherwise, there is a very good chance the request will fail.

Logging an action

To log an action, you can use the following parameters. href is required, all others are optional.

href
required
The URL of the action. Page views should just be the /path?and=query, outbounds should be full URLs starting with http/https. For events we recommend you log "virtual" URLs, and start them with a #, e.g. #menu, #button, etc.
title
optional
The title of the action. For a page view, this should be the document title. Note that each unique URL logged to your site can only have one page title ever associated with it.
type
optional
Options are pageview, download, outbound, and click. If left blank, or an invalid value is declared, pageview will be used.
ref
optional
The external referrer, if any, for this action (e.g. if they arrived at your site from a link or search on another site). This value will only be logged for the very first action of a session.
ua
optional
The visitor's user agent, e.g. Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:68.0) Gecko/20100101 Firefox/68.0. Our code will automatically extract the browser and OS information from it so you should pass it through "as is".


Example: // URL encode your values!
$href = urlencode("/some/page");
$title = urlencode("Some title");
$ref = urlencode( $_SERVER['HTTP_REFERER'] );
$ua = urlencode( $_SERVER['HTTP_USER_AGENT'] );

file("http://stats.gtxp.com/in.php?site_id=1&sitekey_admin=1&ip_address=".$_SERVER['REMOTE_ADDR']."&href=".$href."&title=".$title."&ref=".$ref."&ua=".$ua);


Logging custom data

You can log custom data to any existing session, even one many days old, without generating a visitor action.

type
required
This parameter is required and its value must be set to "custom", e.g. type=custom.
custom
required
An array of key/value pairs you want to send, e.g. ['username'=>'billy', 'email'=>'billy@billy.com']. How do you send an array in the URL? See the example below!


Example: // URL encode your values!
$username = urlencode( $_SESSION['username'] );
$email = urlencode( $_SESSION['email'] );

file("http://stats.gtxp.com/in.php?site_id=1&sitekey_admin=1&session_id=123&type=custom&custom[username]=".$username."&custom[email]=".$email);


Logging goals and revenue

You can declare a goal for a session well after it has expired, without generating a visitor action. You can also attach revenue to that goal. You can even attach revenue to a goal that has already been flagged as completed for this session, if revenue was not logged previously.

type
required
This parameter is required and its value must be set to "goal", e.g. type=goal.
goal
required
This should be an array, with keys "id" (required) and "revenue" (optional). How do you send an array in a URL? See the example below!


Example: file("http://stats.gtxp.com/in.php?site_id=1&sitekey_admin=1&session_id=123&type=goal&goal[id]=123&goal[revenue]=49.95");