Tracking the *real* number of users in Google Add-Ons using Google Analytics

I developed my first add-on Word Cloud Generator for Google Docs without knowing much about who was using the Add-On and how they were using it.

Over time I introduced enhancements such as enabling downloadable word clouds but did not know if those enhancements were indeed being used. I googled the essentials, set up Analytics tracking, and included the basic tracking code in my script file.

This basic tracking code is well explained on the Google Developers analytics.js page

I quickly realized that the basic set up did not result in useful information on usage for Add-Ons as the counts were vastly exaggerated (tracking was done using cookies that were not persistent and resulted in information per use, and not per user). (The number of installs displayed in the developer dashboard was not much help for analytics). Then I found an Analytics resource that presented the code to be used and a blog with a discussion of the cookie issue by Romain Vialard:

This (ultimately) with a lot of trial and error, finally worked.

However it took me a very long time to understand what this code was doing and how to use it. Not a fun experience. So in case there is somebody out there looking for a step by step explanation of why the above works and what it means, I posted my code on gist with a LOT of comments. I hope it helps someone to save some time and get to tracking Add-On usage rather than googling!

Leave a message if you have any additional tips or comments

/* 
 The most common way to track users in Google Analytics is by using cookies. But sometimes 
 there are platform and security limitations that will not allow cookies to be set or 
 stored for multiple sessions. The following code uses the localStorage property (available 
 now in most browsers) to provide an alternate way to the cookie-based solution. The code 
 is heavily commented to help even the most casual users understand the overall workings 
 of the code. Feel free to ignore this part if you know what you are doing. 

This work is based on a Google example: 
https://developers.google.com/analytics/devguides/collection/analyticsjs/cookies-user-id 
I have simplified it and added comments

There is a blog about this code in medium:link and some basic concepts explained in the 
comments section: 
*/

// First I make sure that there is localStorage available in the browser. The code 
//only works if localStorage is available.
if (window.localStorage) {

  /* The first step to setting up a google analytics tracker is to issue a GA create 
  command. Typically it is done as follows: 
  ga ('create', 'UA-XXXXXXXX-5', 'auto')

  This tells the GA code to create a tracker for the property with an id 'UA-XXXXXXXX-5 
  and tells GA to use a default domain to store the analytics cookie.

  But I want to create the tracker a bit differently. I want to do three things:

  1) I want GA not to use cookies
  2) I want GA to use a client id to identify the browser so that I can track the user 
  and not every session of the user
  3) I want to store the client id locally (ie on the browser) so that it can be passed 
  on to GA for the next time 

  */


  ga('create', 'UA-XXXXXXXX-5', // these two parameters remains exactly the same as 
     //Google's standard tracking code
     // I pass the added information via the following object:
     {
       'storage': 'none', // Tells GA not to store cookies as local storage is being used
       'clientId': localStorage.getItem('local_client_id') // Tells GA to set a clientId 
   //to identify this browser/user

       /* Gotcha alert */

       /*        
       This tripped me up. So warning to you too: The value of clientId is initially null! 
       This is because there is nothing in localStorage yet and therefore 
       getItem ('local_client_id') will return null. GA when creating the tracker will 
       generate a random unique number as a client id      
       */


     });


 /* 
  Once the tracker is created I want to get the random client id generated by GA 
  and store it locally. 
  I want to do this because next time when the tracker is created the locally 
  stored client id will be passed, so that the GA knows it is NOT a new user 
  (because GA already has the client id)

  To do this Google offers a cool way to get tracker information. I call ga and 
  pass in an anonymous function with a single parameter. When ga gets a call 
  with a function (with a single parameter) 
  it puts the created tracker data in that parameter.

  The function passed earlier requests the client id from ga and stores 
  in the localStorage  

 */


  ga(function(tracker_data) { 
    localStorage.setItem('local_client_id', tracker_data.get('clientId')); 
   // get the client id from GA and store it locally
  });

}
else {/* fallback if there is no local storage - In this case, GA will 
count each and every hit even when the same user accesses the app multiple times*/
  ga('create', 'UA-XXXXXXXX-5', 'auto');
}
// Send the hit - it will only be counted when the client id matches  
ga('send', 'pageview');

GA concepts:

Tracker objects: A JS object created by GA that can collect and store data and then send that data to Google Analytics.

Tracking id: A string like UA-000000–01. It is included in tracking code to tell Google Analytics which account and property to send data to.

Client id: The client id is a unique, randomly generated string that usually gets stored in the browsers cookies, so subsequent visits are associated with the same user.