Universal analytics measurement protocol for your GAS libraries

A little while ago, I did a an article on Instrumenting VBA for Google Analytics, which uses Universal Analytics to track the use of sections of VBA code. One of the things that is missing when you share out Apps Script libraries is the ability to know whether they are actually being used. It occurred to me that we simply use the same trick in your libraries to track usage of those. I'll provide a library you can use of course.


You can include it from MIHfxr-fc_7bXa1l0Dkk0oqi_d-phDA33

Here are some slides from a talk I gave on this topic at GDG #devfestlon London, Nov 2014.

final Instrumentation with Analytics.pptx



Here's how to use

function myFunction() {
  var ua= new cUAMeasure.UAMeasure ("UA-45xxxx1027-1","EXCEL","bruce");
  ua.postAppView("testingua");
  ///do some stuff
  ua.postAppKill();
}

And here's what happens when you run something. I'm reporting against my EXCEL account, which may seem a little odd, but in another post I'll show how you can use real time analytics to track whats happening in an application where lots of moving parts are communicating. See Universal analytics for checking co-operating processes for how you can use this to track that processes are happening as you expected in real time




A few notes

User privacy
To get the full value out of this, ideally you need to find a way of uniquely identifying users, so that you can count repeat visitors, how many unique people are using your code etc. If you are running in the context of your domain you might be able to use the getEffectiveUser(), or store something in the User Properties specific to any particular user. If you don't supply  a user name (in the example above I've used my own), then a unique id for the session will be automatically generated. If this happens, then each visit will look like a different user to analytics. Whichever way you go, the resultant userid is salted and one way encrypted so that what goes to Google complies with their terms and conditions of no user identifiable data being store on their analytics system, so feel free to use whatever you like there. 

Your analytics property code
That's the code that starts with UA-. You'll need to get one from your analytics dashboard.

Opting out
it's possible to turn off all analytics by passing a fourth argument as true. The best way to do this would be to have some kind of global variable which you could turn on and off as required.

var optOut = true;

..
..code
new cUAMeasure.UAMeasure ( code,analyticsAccount,userId, optOut)
..
...

Page Name

Code enclosed between ua.postAppView(page) .... ua.postAppKill() are recorded as a session against the page name given. So in the example above, the session was shown against the pagename. This is how you will track whatever you want to track - just set the page name to something that means something to you. I also recommend that you build in something about the page name to the 

Versions

By default, the version of the cUAMeasure library will show up in analytics against your session. I find that using this version field is really useful for knowing who is using what version for backwards compatibility, so I recommend that you pass some version text that identifies your own library. That way you can version analysis with analytics reports.

Failures

Analytics failures because of URLFetch problems and so by default these are silent. You can cause an exception to be thrown by setting the failSilently parameter to false when you construct the class. In either case a view or a kill will return itself or a null if it fails if you need to detect failures.

Performance and quotas

A view or a kill each do a fetch. Although the amount of data transferred is very small, it will nevertheless use up  quota and might contribute to rate limits problems if you have that type of application. As a separate topic, you do have these problems, you might be interested in Backing off on rate limiting. I purposefully did not use back off for this, since I don't want delays introduced by waiting for measurement failures. Because of this you need to be careful that you put measurement instrumentation probes sparsely and at a sensible place (not within loops etc.)  - To put it in context ... here's how long it takes to register a pageview - 6 milliseconds.

UrlFetchApp.fetch([http://www.google-analytics.com/collect, {payload=v=1&tid=UA-45711027-1&cid=30,-107,45,99,-93,-13,86,61,-19,84,-95,113,66,55,-60,115&t=appview&an=EXCEL&av=DataHandler-v0.7&cd=db_query_DriverScriptDb-v0.2&sc=end, method=POST}]) [0.006 seconds]

Here's the code



For help and more information join our forumfollow the blogfollow me on twitter

You want to learn Google Apps Script?

Learning Apps Script, (and transitioning from VBA) are covered comprehensively in my my book, Going Gas - from VBA to Apps script, available All formats are available now from O'Reilly,Amazon and all good bookshops. You can also read a preview on O'Reilly

If you prefer Video style learning I also have two courses available. also published by O'Reilly.
Google Apps Script for Developers and Google Apps Script for Beginners.