Clicky

Clicky Documentation

Clicky Developer Documentation

Clicky's tracking can be highly customized with JavaScript via the clicky_custom object; some of these properties can also be set in your site preferences. You can also log data manually, either from JavaScript events, or internal scripts (PHP, etc).

Most of the options here are only applicable for premium accounts, e.g. goals, custom data, and outbound/download tracking (Upgrade here).

Jump to:

clicky_custom

Customize how the tracking code works on your website.

All clicky_custom properties can be set with JavaScript for fine-grained, per-page or per-session control, but some are also available as site preferences. They are separated into two distinct sections below.

JavaScript-only properties

Most of these properties are session- or page-specific, or are for advanced users only, so they can only be set with JavaScript.

visitor
type: object
Attach custom data, such as a username or an email address, to a visitor session.

visitor_consent
type: boolean
Flag a visitor as consenting to logging Personal Data. This will override your default visitor privacy settings.

href
type: string
Override the URL that gets logged. Only applies to page view actions.

title
type: string
Override the page title that gets logged. Only applies to page view actions.

goal
type: mixed
Manually declare a goal as completed, and any revenue, if applicable.

split
type: object
Used for split testing your goals.

pageview_disable
type: boolean
Disables logging the default pageview upon load. Useful when you only want data logged for certain events and actions.

ping_disable
type: boolean
Disables tracking code pings. Pings help us give more accurate bounce rates and time-on-site values.

osa_disable
type: boolean
If there are any specific pages on your website that you do NOT want the on-site analytics widget to appear, set this variable.

heatmap_disable
type: boolean
If there are any specific pages on your website that you do NOT want to log any heatmap data, set this variable.

history_disable
type: boolean
Disables the automatic tracking of HTML5 history.pushState() navigation.

track_iframe
type: boolean
If you are trying to track an iframe, and not the parent document of the iframe, then set this variable.

getHighEntropyValues
type: boolean
Request more information about a user agent than is exposed by default. This uses the navigator.userAgentData.getHighEntropyValues() method available in Chromium-based browsers.

heatmap_objects
type: mixed
If your site's JavaScript disables event propagation on some elements (e.g. JS menus), use this variable to force Clicky to explicitly listen for clicks on those items.

cookie_domain
type: string
By default, the domain scope for our tracking cookie will be set to ".yoursite.com". The "." at the beginning means it will apply to every sub-domain. Change the domain scope with this variable.

Properties that can also be set via site preferences

These can be set by JavaScript like the options above, but are also available in your site preferences. If the same key is set in both places, the JavaScript one will take precedence. This allows for manual overrides for specific pages or visitors.

timeout
type: integer
Set how many minutes a visitor will ping our servers while on a single page. Default is 10.

outbound_pattern
type: mixed
If you have any outbound links that do a local redirect first, you'll need to use this to specify the URL pattern/s that our tracking code should look for to track clicks on these links. For example, /go/.

html_media_track
type: boolean
Enables automatic tracking of embedded HTML5 video and audio files.

outbound_disable
type: boolean
Disables the automatic tracking of outbound links and downloads.

sticky_data_disable
type: boolean
Disables tracking cookies that store UTM campaigns, referrers, and custom visitor data for 30 days.

cookies_disable
type: boolean
Disables all tracking cookies. Automatically set if visitor privacy is on, but you can manually set as well.

You can declare clicky_custom and the properties you want to use with a single command, or you can just define clicky_custom as a generic JSON object and add the properties one at a time later. Which one you choose is up to you, although we do recommend the "one at a time" method. This is so that your logic for outputting this data doesn't have to be all in the same place, and so that you don't accidentally overwrite the entire object with a later call to it.

Each of these methods are shown in the examples below, and each accomplish the same end result: add a few session variables, change the session timeout to 20 minutes, and customize the page URL and title.

Example: One at a time

<script type="text/javascript">
  var clicky_custom = {};
  clicky_custom.href = '/some/page?some=query';
  clicky_custom.title = 'Some page';
  clicky_custom.session = {
    username: 'bobjones',
    email: 'bob@jones.com'
  };
  clicky_custom.timeout = 20;
</script>
<!-- your hypothetical tracking code -->
<script src="http://static.getclicky.com/123.js" type="text/javascript"></script>

Example: All at once

<script type="text/javascript">
  var clicky_custom = {
    href: '/some/page?some=query',
    title: 'Some page',
    session: {
      username: 'bobjones',
      email: 'bob@jones.com'
    },
    timeout: 20
  };
</script>
<!-- your hypothetical tracking code -->
<script src="http://static.getclicky.com/123.js" type="text/javascript"></script>

clicky_custom.visitor

IMPORTANT!
Logging "Personal Data", such as a username or email address, requires disclosure in your site's privacy policy, and depending on the "legitimate interest" of the data, consent may be required as well.

The visitor property allows you to add your own custom data to a visitor session, such as a username or email. This data will be stored in our database and accessible whenever you request the details of this session, whether that's through the website itself, the API, or otherwise.

Analytics API

The Analytics API allows you to extract your website's traffic data into several common formats, making it easy to integrate, analyze, or store your data within your own application.

The API accepts requests via standard HTTP GET, and can respond with XML, JSON, serialized PHP, and CSV.

Send requests to the following URL:
https://api.clicky.com/api/stats/4

IMPORTANT
For performance reasons, the API has restrictions on visitors-list, actions-list, and segmentation requests:

Required parameters

The following parameters are required with every request to the API.

site_id

Every site has its own unique numeric ID. Your request must include the site's ID that you want to access data from. Available from your site preferences page.

sitekey

The sitekey is a 12–16 character string of random letters and numbers that is unique for every website and is assigned when you first register your website with us. Because you don't "login" to the API like you would to a normal website, every request must be authenticated by your sitekey. Available from your site preferences page.

type

The type of data you want. Note that some data types are only available with a premium account.

Tip: You can request more than one data type by separating them with commas:
type=visitors,countries,searches.
Consolidating multiple types into one request will get you your data much faster than separate requests for each type.

Popular items

Results are ordered from most popular (e.g. most occurrences) to least popular.

Chronological items

Results are ordered from newest to oldest.

Tallies

Optional parameters

The following parameters are optional. If a parameter is not included in your request, or the specified value is invalid, the default value will be used automatically.

output

What format you want your data in.

limit

The maximum number of results that you want returned. If you are requesting multiple types and/or "daily" values, this limit will apply to each group of data, not the overall set.

page

Use in combination with limit to page through results. For example, limit=100&page=2 will return results 101–200.

date

The date or date range you want to access. The maximum range is 366 days for Pro users, and 31 days for everyone else. If you give an invalid date or date range (range too large, end is before start, etc.), we'll automatically use "today" instead. If you are requesting a date range for a "popular" or "tally" type, the value returned for each item is the total sum of that item's values from all dates within the date range—unless you specify the "daily" option, detailed below.

daily

When you request a date range, by default the results returned are the total/sum values for the entire date range. If you would like the results to be returned on a per-day basis, then you can specify daily=1 in your request.

Examples:
- type=visitors&date=last-7-days
- type=visitors&date=last-7-days&daily=1

Note: If all data types being requested are tally types (e.g., type=visitors,actions), and you are requesting CSV output with daily values, the output format changes so each line is date,value.

Examples:
- Tally data only: type=visitors,actions&date=last-7-days&daily=1&output=csv
- Other data types: type=searches,visitors&date=last-7-days&daily=1&output=csv

hourly

For some data types, we track hourly data in addition to daily. Currently supported data types are visitors and actions. To request hourly data for a supported data type, just append hourly=1 to the request, and hourly data will be returned for all of the dates that you are requesting.

Note:
- If you request hourly data, the request can only contain data types that support this type of data. In other words, you can't mix hourly visitor data with daily top searches. These requests must be made separately.
- When hourly data is requested, it is automatically broken down by individual days. In other words, daily=1 is automatically applied to these queries.

Examples:
- type=visitors
- type=visitors&hourly=1
- type=visitors&hourly=1&date=last-7-days

trends

Set trends=1 to get the trend percentage returned along with the value. This is the same percent value you see in red or green next to each item in our reporting interface. The range we support is from -999 to 999. We do not return the "%" symbol with this value, so it's easier for you to manipulate on your end. If you are going to display it on your website or in a report, you'll probably want to add the "%" to the end so it's clear what it is.

Example: type=searches&date=last-7-days&trends=1

item

Use this to get the stats for just a single item for the type you are requesting. This works differently than the "filter" parameter below, which is a wildcard search. item is an exact match string. Sending in, for example, type=search&item=cookie will only return the results for the specific search of "cookie", whereas filter=cookie would also return results for "cookies", "oatmeal cookies", etc.

You can only specify one data type if you are also requesting item, since you can only specify one item per request.

Hot tip: Specify daily=1 to get the daily breakdown for this item, instead of just the total sum over your requested date range.

Examples:
- type=links-domains&date=last-7-days&item=google.com
- type=links-domains&date=last-7-days&item=google.com&daily=1

heatmap_url

This works in conjunction with a type=pages request. Appending &heatmap_url=1 to the request will append the heatmap viewing authentication to the end of the URL, so these links can be clicked on directly to view a heatmap for that page.

Example: type=pages&heatmap_url=1

visitor-details

This is used in combination with type=visitors-list. There are many details associated with every visitor and by default we'll give you all of them. This is fine in most cases, but if you are requesting a large date range, or if you have a high traffic site, extracting all of those details can take a while. If you only need a few specific details about your visitors, use this parameter to specify which ones as a comma-separated string; the response will be much faster and smaller as less data is transferred.

The details you specify must match the exact field names that we output. Do a type=visitors-list request to see the available options. These are singular instead of plural and use underscores instead of dashes (e.g., web_browser instead of web-browsers).

Example:
type=visitors-list&visitor-details=ip_address,session_id,landing_page,geolocation,web_browser

time_offset

This parameter is available for type=visitors-list and type=actions-list. It lets you specify the time range (in seconds), relative to "now", of data returned. For example, if you request type=visitors-list&time_offset=3600&limit=all, you would only get back visitor sessions from the last hour. Note that the default limit will still apply unless you specify one, so we recommend using limit=all to ensure that all results are returned.

When this parameter is used, the date parameter has no effect. The largest offset you can request is 86400 (1 day).

segments

If you are requesting type=segmentation, specify the segments you want returned here as a comma-separated string. The values you can input here are exactly the same as any of the "tally" or "popular" data types. For example:
segments=visitors,bounce-rate,web-browsers

This will return the number of visitors and the top web browsers for the visitors who match your filters. This query works exactly like a type=visitors-list request in terms of filtering. For example, if you wanted to filter down to all visitors who arrived via google.com, you would use:
type=visitors-list&domain=google.com.
For segmentation, you would use the same domain parameter, but change the type to segmentation:
type=segmentation&domain=google.com. However, you also need to specify the segments you want returned for these visitors.

For example, if you wanted to view the number of visitors and the top web browsers for people who arrived via google.com, you could do this:
type=segmentation&domain=google.com&segments=visitors,web-browsers

There is an additional data type you can specify here as well, segments=summary. This will provide you with a summary of all visitors who match your filters—the same data you see when you apply a filter within our stats interface (total visitors, actions, average actions per visit, bounce rate, and more):
type=segmentation&domain=google.com&segments=summary,countries,web-browsers

filters

Various filters are available for type=visitors-list, type=actions-list, and type=segmentation. Here are some of the most common ones:

ip_address, uid, new_visitors, returning_visitors, online, heatmap, actions, time, href, landing, exit, search, search-local, domain, link, browser, os, resolution, country, city, language, hostname, org, source, shorturl, custom, goal, campaign, split

These filters are available for type=visitors-list and type=segmentation, and should be sent URL encoded. If you have trouble getting these to work, try applying filters on your visitors page and copying the URL variables from there.

Note: ip_address and uid override all other filters. In other words, if you filter by either of these parameters, all other filters are ignored.

Examples:

session_id, action_type, href, ip_address, uid

These filters are available for actions-list. The href should be URL encoded. If you have trouble, try using the filtering functionality on your actions page and copy the URL variables into your API requests.

NOTE: session_id can also be used with visitors-list to return the visitor details for a specific session ID, regardless of the date range set.

Valid action_type values are:

Other parameters

There are several other optional parameters that might be useful in specific situations:

Responses

Popular and Tally data types

The response will be a group of items with the following keys. Popular data is ordered from most popular to least popular. Tally data only returns a single item unless the daily parameter is specified.

IMPORTANT: If all data types being requested are tally types (e.g., type=visitors,actions), and you are requesting CSV output with daily values, the output format changes so each line is date,value.
Example: type=visitors,actions&date=last-7-days&daily=1&output=csv

The common keys include:

For the "goals" data type, additional keys include:

Chronological data types

Each type has its own response structure.

visitors-list

Returns a list of visitors in reverse chronological order.

Common keys include:

Example Requests

Some example requests are shown below. The results are from our demo traffic data. Note that the PHP output shown is "unserialized" for readability; simply remove the &unserialize parameter to get the raw output. Run the returned string through unserialize() to convert it into a PHP array.

Today's visitors, actions, average actions, average time, and bounce rate
Hourly visitor and action tallies for the last 7 days

Example Code

The code shown below is a simple way of getting data from our API and converting it into a PHP array.

<?php
  $data = unserialize(file_get_contents("https://api.clicky.com/api/stats/4?site_id=32020&sitekey=0f3545d91b71cf50&type=visitors-list&output=php"));
  foreach($data as $item) {
      foreach($item as $date) {
          foreach($date as $visitor) {
              if(empty($visitor['referrer_url'])) {
                  $visitor['referrer_url'] = "(no referrer)";
              }
              echo "{$visitor['time_pretty']} - {$visitor['ip_address']} - {$visitor['referrer_url']}<br>\n";
          }
      }
  }
?>

This would produce HTML output similar to the following:

Mon Apr 13 2015, 4:39pm - 50.46.135.0 - http://bing.com/search?q=unique+visitor+versus+visitor<br>
Mon Apr 13 2015, 4:14pm - 208.181.22.0 - (no referrer) <br>
Mon Apr 13 2015, 4:06pm - 95.129.203.0 - (no referrer) <br>
Mon Apr 13 2015, 3:50pm - 37.250.124.0 - (no referrer) <br>
Mon Apr 13 2015, 3:11pm - 99.6.169.0 - (no referrer) <br>
Mon Apr 13 2015, 2:58pm - 128.151.211.0 - (no referrer) <br>
Mon Apr 13 2015, 2:18pm - 90.174.2.0 - (no referrer) <br>
Mon Apr 13 2015, 2pm - 24.10.83.0 - (no referrer) <br>
Mon Apr 13 2015, 1:21pm - 78.97.148.0 - (no referrer) <br>

Account API

This API takes your username and password and returns a list of all sites in your account, including hostname, nickname, site ID, sitekey, admin sitekey, timezone, and a few basic stats (visitors online and visitors 'today').

This is useful for automated processes you have set up to, for example, extract data from the Analytics API. If your processes refresh their data every day by grabbing the output from this API, then they will always be up to date when you add new sites, delete sites, edit existing ones, reset site keys, etc.

Default output is XML, but you can request JSON or serialized PHP instead.

Send requests to https://api.clicky.com/api/account/sites with the parameters listed below. You can use HTTPS instead of HTTP if desired.

Parameters

username

password

output

Live examples

(Yes, our demo account has no password.)
(Note: sitekey_admin is not output here for security purposes.)

Proxy Tracking

Approximately 15% of people use ad-blockers, most of which also block trackers – even privacy-friendly trackers like Clicky. This means that a very significant portion of your traffic won't be logged by most services.

Luckily for you, Clicky is not like most services. With our reverse proxy tracking configuration, the tracking code and all tracking beacons will route through generic pathnames on your website's domain name instead of ours. This makes tracking much harder to detect and will only be blocked by visitors who set up a manual override for your site. When we switched to this method for tracking clicky.com, our numbers increased by almost 20%. What a difference!

There's only one other analytics service we know of that has even a general guide on how to set up proxy tracking, and other services may in theory support a similar set up. The Clicky difference is that our guides are fully dynamic and generate the code for your specific site rather than just giving you a template and having you figure out how to make it work for your site.

These dynamic guides are built into the tracking code page in your site preferences. Simply choose your server type or preferred method – Nginx, Caddy, Apache, .htaccess, and plain old PHP – and customize a few other options as needed. All the code is then generated for you. It's a bit more involved than standard tracking set up, but it's really just a matter of getting the code into the right place, and it's absolutely worth it if you have the means.

Tracking Code Settings:

Configuration Code for nginx:

http {
    ### COPY THE TWO LINES BELOW INTO YOUR EXISTING HTTP{} BLOCK
    # CACHE FOR CLICKY ANTI-ADBLOCK PROXY - https://clicky.com/help/proxy
    proxy_cache_path /dev/shm levels=1:2 keys_zone=clicky:8m max_size=8m inactive=1d use_temp_path=off;
}

server {
    ### COPY THE CODE BELOW INTO YOUR EXISTING SERVER{} BLOCK

    ### CLICKY ANTI-ADBLOCK PROXY - https://clicky.com/help/proxy

    # DNS RESOLVER (if already defined elsewhere, this can optionally be deleted).
    resolver 1.1.1.1;

    # JAVASCRIPT TRACKING CODE
    location = /85d35be8f33 {
        rewrite /85d35be8f33 /js?in=%2F3fd5bb595e1 break;
        proxy_pass https://static.getclicky.com;
        proxy_http_version 1.1;
        proxy_ssl_server_name on;
        proxy_set_header Host static.getclicky.com;
        proxy_cache clicky;
        proxy_cache_valid 200 1d;
        proxy_cache_use_stale error timeout updating invalid_header;
        add_header X-Cache $upstream_cache_status;
    }

    # JAVASCRIPT BEACON
    location = /3fd5bb595e1 {
        proxy_pass https://in.getclicky.com/in.php;
        proxy_http_version 1.1;
        proxy_ssl_server_name on;
        proxy_set_header Host in.getclicky.com;
    }
}