Clicky's tracking code has functions you can use to log any action you want on your web site, 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. Clicky is different.

Note that goals and internal script logging are Pro-only features. The clicky.log() function, used to capture Javascript events, will work with any premium account. (Upgrade)


Tracking code functions

  clicky.log  

Log an action based on any Javascript event. URL, title, and action type can all be specified.

  clicky.goal  

Log a goal as completed based any Javascript event.


clicky.log( href, title, type )

Clicky works great for tracking events in Javascript and Flash applications. You'll simply need to call this function whenever you want to log a visitor action, 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, all other actions need to start with either a / or a #. If you just want to the log the URL as it is in the anchor tag, use the value this.href. (this.href will only work within the HTML scope, not in Flash).
  • title: Optional. The text you want to show up next to the URL. Our standard tracking code uses the text of the link itself but you may want to use something else.
  • type: Optional. The type of action you are logging. If left blank, it defaults to 'click'. Other options are 'download', 'outbound', and 'pageview'.


Javascript

You'll want to use an "onclick" event handler for the link to call the log function. For example:

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

Flash (ActionScript)

Flash has builtin functions for calling external javascript functions.

For ActionScript 3 or higher, use this the code below, swapping out URL, TITLE, and TYPE for what you want to log. (URL is required, the others are optional).

ExternalInterface.call("clicky.log", "URL", "TITLE", "TYPE");

For ActionScript versions less than 3, use getURL() instead. You'll need to prefix our function with the javascript: protocol. Replace URL, TITLE, and TYPE for what you want to log. (URL is required, the others are optional).

getURL("javascript:clicky.log( 'URL', 'TITLE', 'TYPE' );");

clicky.log() creates a 500 millisecond second pause whenever it is called for download or outbound types, to ensure the user's browser has time to talk to us before moving on to the next page. You can change this value with clicky_custom.timer. For Flash, we recommend setting this value to 0, since Flash apps don't generally load new HTML pages.



clicky.goal( id, revenue, no_queue )

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 clicky_custom.goal, but it's important to note that these two methods are very different from each other. clicky.goal() should only be called by a Javascript event. Any other usage may have unexpected results and is not supported.

clicky.goal takes 3 parameters:
  • id: Required. Each goal has its own unique numeric ID in our database. The goal management page for any web site 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.

    As of February 2011, we support dynamic goals, which means they can be declared on the fly from within your Javascript. To use dynamic goals with this function, pass in a name for your goal instead of an existing ID. For example, "Clicked button". Further documentation for dynamic goals is embedded with the goal setup page for any of your sites.

  • 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.

  • no_queue: Optional. Clicky's tracking code uses a queue system to send some logging requests in batches, to save resources. clicky.goal uses this system by default. This is good in that if you are trying to log a goal for an event that will cause a new page load, then the goal can still get logged after the new page has loaded (otherwise, it would only be logged in rare instances). There are some cases however where this is not ideal. If this applies to you, set this parameter to a truthy value (1, true, etc) and then goals will always fire immediately when you call this function.


clicky.goal doesn't have any kind of pause timer built into it. If the user is going to be redirected to a different web site after this click, you need to both ensure that the goal is fired immediately, and that there is a pause before the new page is loaded, to ensure the click is registered on our end. In this case you'll want to specify the no_queue parameter for this function, as well as call clicky.pause() to create a small delay. clicky.pause() takes one parameter, which is the number of milliseconds you want to pause for. If you don't specify that, it will automatically use what you have declared with clicky_custom.timer. If you have not declared that, then it will use the default value of 500 milliseconds (half a second).

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

<a onclick="clicky.goal( '10', null, 1 ); clicky.pause( 500 );" href="http://different-web-site.com">Different web site</a>


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

<a onclick="clicky.goal( 'Downloaded file', null, 1 ); clicky.pause( 500 );" href="/song.mp3">Download now!</a>





Logging data from an internal script

Clicky 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. Clicky is different.

This feature is useful in scenarios where data logging would not be possible with an external service such as Clicky. 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 web site, 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 web sites.

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 Clicky 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.

Note: This feature requires a Pro or higher account.


How to talk to our tracking servers

We've written a function, available here, to do most of the hard work for you. You can use that, or you can read the documentation here to see how it all works, and write your own code. It is fairly simple to send data to us. You just need to know which parameters to use. The choice is yours!

The page you want to talk to is at http://in.getclicky.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 parameters are required with all requests. They are all available from the main preferences page for any site on Clicky. Additional parameters are necessary depending on what you are trying to do. Each type of call is documented further down.

  • site_id

    Every site on Clicky has its own unique ID. This is that.

  • sitekey_admin

    There's the sitekey, and then there's the admin sitekey. This one allows you to write data to Clicky. Do not share this key with anyone else.

  • ip_address / session_id

    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, Clicky 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

    The URL of the action. Outbound links should start with "http". All others should start with a slash / or a hash #.
    /this/is/ok
    #thisIsOk
    this/is/NOT/ok

  • title

    The title of the action. For a page view, this would be the document title. Note that each unique URL logged to your site can only have one page title ever associated with it.

  • type

    Options are pageview, download, outbound, and click. If left blank, or an invalid value is declared, pageview will be used.

  • ref

    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

    The visitor's user agent, e.g. Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB; rv:1.9.0.6) Gecko/2009011913 Firefox/3.0.6.
    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://in.getclicky.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, and its value must be "custom".

  • custom

    Required, of course - the point of this request is to log custom data! This should be an array of key/value pairs you want to send. 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://in.getclicky.com/in.php?site_id=1&sitekey_admin=1&session_id=123&type=custom&custom[username]=".$username."&custom[email]=".$email);


Logging a goal and/or 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, and its value must be "goal".

  • goal

    Required, of course - the point of this request is to log a 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!

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



Too complicated? Try the function we wrote instead

Remember, you can make your life a lot easier by just using the function we created to do this for you. It automatically URL encodes everything, includes the remote visitor's IP if you forget to declare both the IP and session ID, forms the URL for you, etc!