Click Tracking API (advanced customization)

From wiki.usabilitytools.com
Jump to: navigation, search

This is the description for Application Programming Interface of UsabilityTools Click Tracking tool.

It is aimed at programmers - your IT department after reading this page will know how to customize the Click Tracking behavior to your website's needs.

Contents

Getting access to API

The simplest way of accessing the CT API is the static way is to add the following block above the original tracking script line:

 <script type="text/javascript">
   window['UT-CT-API-STATIC']={
   //settings go here
   }
 </script>
 <script type="text/javascript">
   (function(s,o,g,a,m){a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.defer=1;a.src=g;m.parentNode.insertBefore(a,m)})
   (document,'script','https://usabilitytools.com/clicktracker/script/XXXXX/tracker.js');
 </script>
 

How to treat multiple pages as one

Sometimes you want to track clicks on multiple pages and see a single heatmap with all the results. It's useful in e-commerce websites when all the product pages look the same, but have different product photos and description and, what's important - URL addresses. You can make Cick Tracking think that they are all the same using the `overridePage` API setting.

 <script type="text/javascript">
     //override the address from http://mypage.com/product?id=<some_numbers> to a single representative page
     //to get results from all the product pages as one
     window['UT-CT-API-STATIC'] = { overridePage:'http://mypage.com/product?id=3' };
 </script>
 <script type="text/javascript">
   (function(s,o,g,a,m){a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.defer=1;a.src=g;m.parentNode.insertBefore(a,m)})
   (document,'script','https://usabilitytools.com/clicktracker/script/XXXXX/tracker.js');
 </script>
 

We recommend overriding addresses to addresses that actually exist - for example put there a URL to one of your existing products. It will make this heatmap available also from the Statistics tab under this address.

You can also override page address at any time after the tracking script has loaded. See the advanced section.

Automated page joining (removing parameters)

You don't always have to use a simple address, it is also correct to generate the address.

Example:

A site example.com has a marketing campain that is tracked by adding ?utm=abc to addresses (this is how adwords and others do that).

To get clicktracker to put data from example.com and example.com?utm=any_code to the same heatmap you can use the following API call:

 <script type="text/javascript">
     //get the real address and remove anything starting with ? or #
     window['UT-CT-API-STATIC'] = { overridePage: window.location.href.replace(/[?#].*$/,'') };
 </script> 
 <script type="text/javascript">
   (function(s,o,g,a,m){a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.defer=1;a.src=g;m.parentNode.insertBefore(a,m)})
   (document,'script','https://usabilitytools.com/clicktracker/script/XXXXX/tracker.js');
 </script>

Controlled page joining

You can join pages that have addresses beginning with the common prefix. And you can use a list of prefixes to put the same code on every page.

In the following example:

  • Clicks from all pages like http://example.com/page/1 and http://example.com/page/2 will create one heatmap.
  • Clicks from all pages like http://example.com/search.php?=jellybeans and http://example.com/search.php?=marshmallows (etc.) will create one heatmap.
  • All other pages will have separate heatmaps each.
   <script type="text/javascript">
       //List of the beginnings of addresses that will share heatmaps - ignoring anything that shows up at the end of any of the given address.
       var beginning_with = [
               'http://example.com/page/',
               'http://example.com/search.php?=' //Note the lack of comma at the last address
       ];
  
       for (var i = 0; i < beginning_with.length; i += 1) {
               if (window.location.href.indexOf(beginning_with[i]) === 0) {
                       window['UT-CT-API-STATIC'] = {overridePage: beginning_with[i]};
               }
       }
   </script> 
   <script type="text/javascript">
     (function(s,o,g,a,m){a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.defer=1;a.src=g;m.parentNode.insertBefore(a,m)})
     (document,'script','https://usabilitytools.com/clicktracker/script/XXXXX/tracker.js');
   </script>

Handle one-page sites and applications

Your site might have scripts that change the entire screen without reloading the page. If they change the address in the browser by appending #something to it, you can just tell Click Tracking to check the address again and treat it as if the page was switched.

 if(window['UT-CT-API']){
   window['UT-CT-API'].pageChanged();
 }


The if statement is there to prevent the call from happening if CT tracking script did not load yet. (if the page change happens before CT was initialized, it will get the new address anyway)

Warning: if you use overridePage, pageChanged will not report the new address, because the override is still in place. In that case you need to override the address to new value and then call pageChanged. See the advanced section.


Recording ratio (tracking only a fraction of visits)

Your site can be very popular. While this is always something good, you may want to limit the number of users whose clicks go to your heatmap.

This code lets you collect data for any user with 5% probability. You can change the ratio in the code. This way you can limit the expenses and extend the duration of your research.

 <script type="text/javascript"> 
     if((Math.random()*100)> 5 ){
       window['UT-CT-API-STATIC'] = { disableTracker:true };
       }
 </script>
 <script type="text/javascript">
   (function(s,o,g,a,m){a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.defer=1;a.src=g;m.parentNode.insertBefore(a,m)})
   (document,'script','https://usabilitytools.com/clicktracker/script/XXXXX/tracker.js');
 </script>


Advanced API options

There is a non-static way of accessing the API, but it depends on you being able to call methods right after the script has loaded.

This is an example of a way to wait for the script to load. (tested to work in new FireFox and Chrome, proved not to work in IE8 and older)

 <script type="text/javascript">
   (function(s,o,g,l,a,m){a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.defer=1;a.onload=l;a.src=g;m.parentNode.insertBefore(a,m)})
   (document,'script','https://usabilitytools.com/clicktracker/script/XXXXX/tracker.js', function(){
        
       //now that the script has loaded, window['UT-CT-API'] has API methods
       
   });
 </script>


Please note, that the line that you normally insert to the page was changed by adding the onload handler. Also make sure you change the Click Tracking project id (XXXXX in the above example). Our scripts are non-blocking, so your code runs before our script gets downloaded.

There are multiple other ways of listening to script onload, but we recommend ising the static API for better browser support and avoiding loading-time-related problems.

Mixing pageChange with overridePage

If you need to both override the address and track page changes it can be done in a way similiar to the following:

     //be sure the script has loaded, window['UT-CT-API'] has API methods  
     //add handling for your page's or framework's way of changing pages and addresses
     $(document).on('someCustomPageSwitch',function(){
       window['UT-CT-API'].overridePage( window.location.href.replace(/[?#].*$/,'') );
       window['UT-CT-API'].pageChanged();
     })

Support for left-layouts

By default, Click Tracker saves positions relatively to the middle of the viewport. It's like that because the most of webpages nowadays is centered horizontally. If your page is aligned to left, you can set different mode of tracking by API.

   // before tracking script is loaded
   window['UT-CT-API-STATIC'] = { 
       leftLayout: true
   };
   // only when you sure that tracking script is loaded
   window['UT-CT-API'].forceLeftLayout();

Use it carefully! If you realize that you have to change the tracking mode when project is already started, hold on! Instead, create new project and attach new script when mode change is made. When you mix data gathered for left and center layouts, heatmaps will have no sense. The only case when you don't have to create new project is adding tracker to previously not tracked page.

Listing of all API methods and settings

 window['UT-CT-API-STATIC'] = { 
   disableTracker: true,                   // disables tracking
   overridePage: String,                   // overrides the page address to specified string
   leftLayout: true                        // forces left layout
 };
 
 window['UT-CT-API'].pageChanged();          // forces update of the current address
 window['UT-CT-API'].overridePage(String)    // overrides the page address. if called after tracker initialized itself, it has to be followed with a pageChanged() call
 window['UT-CT-API'].disableTracker();       // sets disabled flag. works only before tracker initializes itself
 window['UT-CT-API'].forceLeftLayout();      // forces left layout