. 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. Firespring Analytics is different.
Tracking code functions
firespring.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:
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.
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>.
The type of action you are logging. If left blank, it defaults to 'click' (event). Other options are 'download', 'outbound', and 'pageview'.
<a href="#menu/home" onclick="menu('home'); firespring.log('#menu/home','Home'); return false;"><img src="media/menu/home.gif"></a>
firespring.goal( id, revenue )
be logged when calling this function. It just flags the visitor as having achieved the goal.
You can also track goals with the firespring_custom.goal
variable, but it's important to note that these two methods are very different from each other. firespring.goal() should only
firespring.goal takes 2 parameters:
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.
<a onclick="firespring.goal( '10', '9.95' );" href="mailto:firstname.lastname@example.org">Email me!</a>
<a onclick="firespring.goal( '10' );" href="http://different-web-site.com">Different website</a>
Dynamic goal examples:
<a onclick="firespring.goal( 'Clicked email' );" href="mailto:email@example.com">Email me!</a>
<a onclick="firespring.goal( 'Downloaded file' );" href="/song.mp3">Download now!</a>
Logging data from an internal script
Firespring Analytics 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. Firespring Analytics is different.
This feature is useful in scenarios where data logging would not be possible with an external service such as Firespring Analytics. 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
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://analytics.firespring.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.
These first 3 parameters are required with all requests below.
They are all available from the main preferences page for any site on Firespring Analytics. Additional parameters are necessary depending on what you are trying to do. Each type of call is documented further down.
Every site on Firespring Analytics has its own unique ID. This is that.
There's the sitekey, and then there's the admin sitekey. This one allows you to write data to Firespring Analytics. Do not share this key with anyone else.
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, Firespring Analytics 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.
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.
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.
Options are pageview, download, outbound, and click. If left blank, or an invalid value is declared, pageview will be used.
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.
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".
// URL encode your values!
$href = urlencode("/some/page");
$title = urlencode("Some title");
$ref = urlencode( $_SERVER['HTTP_REFERER'] );
$ua = urlencode( $_SERVER['HTTP_USER_AGENT'] );
Logging custom data
You can log custom data to any existing session, even one many days old, without generating a visitor action.
This parameter is required and its value must be set to "custom", e.g. type=custom.
An array of key/value pairs you want to send, e.g. ['username'=>'billy', 'email'=>'firstname.lastname@example.org']. How do you send an array in the URL? See the example below!
// URL encode your values!
$username = urlencode( $_SESSION['username'] );
$email = urlencode( $_SESSION['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.
This parameter is required and its value must be set to "goal", e.g. type=goal.
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!