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.

Here’s an example of tracking usage of back end databases during the scriptDB switchoff.

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.

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

Page Content hide

5 Performance and quotas

6 Here’s the code

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]