Improved integraiton with Google Analytics.

By migrating to gtag (which is the preferred client of GA), we can
provide seamless integration with GA. This version is stricter in
respecting Do-Not-Track.

Author: delapuente

Assets/WebGLTemplates/WebVR/lib/telemetry.js

@@ -1,7 +1,26 @@
-/* global localStorage, location, Raven */
+/* global Raven */
 (function (window) {
 'use strict';
 
+/*
+ * The main requirements when dealing with Do-Not-Track (DNT) are:
+ *
+ *  1. Prevent explicit collection, storage and sending data if DNT is enabled.
+ *
+ *  2. GA and Telemetry APIs should not throw or error if DNT is enabled,
+ *     although they must ensure requirement #1.
+ *
+ *  3. If DNT is enabled in the middle of the gameplay, the API must ensure
+ *     requirements #1 and #2. If DNT is disabled in the middle of the gameplay,
+ *     resuming data collection is not mandatory.
+ *
+ * FOR MAINTAINERS: Some collection can happen implicitly when loading 3rd party
+ * libraries. Try to prevent loading external libraries if DNT is enabled and
+ * this does not conflict with requirement #2.
+ */
+
+var CURRENT_VERSION = '1.0.2';
+
 if (!('MozillaResearch' in window)) {
   window.MozillaResearch = {};
 }
@@ -13,64 +32,57 @@ if (!('telemetry' in window.MozillaResearch)) {
 var navigator = window.navigator;
 var telemetry = window.MozillaResearch.telemetry;
 
-telemetry.ga = {
-  create: function (trackingId, cookieDomain, name, fieldsObject) {
-    window.ga('create', trackingId, cookieDomain, name, fieldsObject);
-    return function (command) {
-      if (navigator.doNotTrack === '1') { return; }
-      var args = Array.prototype.slice.call(arguments);
-      if (name && command !== 'provide') {
-        command = name + '.' + command;
-        args[0] = command;
-      }
-      window.ga.apply(undefined, args);
-    };
-  }
-};
-
 var NO_OP = function () {};
 
+// Always returns what is in `window[GA_ALIAS]`. According to:
+// https://developers.google.com/analytics/devguides/collection/analyticsjs/how-analyticsjs-works
+// The `analytics.js` script will redefine the `window[GA_ALIAS]` function after
+// loading. Accessing the function indirectly ensures we always get the most
+// recent implementation of it.
+Object.defineProperty(telemetry, '_gtag', {
+  get: function () {
+    return window.gtag || NO_OP;
+  }
+});
+
 telemetry.performance = {
   mark: NO_OP,
   measure: NO_OP
 };
 
 telemetry.start = function (config) {
   config = config || {};
-  if (navigator.doNotTrack === '1') {
-    return;
-  }
   if (config.errorLogging) {
-    startErrorLogging();
+    setupErrorLogging();
   }
   if (config.analytics) {
     var researchAnalytics = startAnalytics();
     if (config.performance) {
-      configurePerformanceAPI(researchAnalytics);
+      setupPerformanceAPI(researchAnalytics);
     }
   }
 };
 
 setupAnalytics();
 
 function setupAnalytics() {
-  window.ga = window.ga || function () {
-    (window.ga.q = (window.ga.q || [])).push(arguments)
-  };
-  window.ga.l = +(new Date());
+  if (doNotTrack()) { return; }
 
-  if (navigator.doNotTrack === '1') {
-    return;
-  }
-  injectScript('https://www.google-analytics.com/analytics.js', function (err) {
+  window.dataLayer = window.dataLayer || [];
+  window.gtag = window.gtag || function () { dataLayer.push(arguments); };
+  window.gtag('js', new Date());
+
+  injectScript('https://www.googletagmanager.com/gtag/js?id=UA-77033033-6', function (err) {
     if (err) {
       console.warn('Could not load Analytics.js script:', err);
       return;
     }
-  });  
+  });
 }
 
-function startErrorLogging() {
+function setupErrorLogging() {
+  if (doNotTrack()) { return; }
+
   injectScript('https://cdn.ravenjs.com/3.22.3/console/raven.min.js', function (err) {
     if (err) {
       console.warn('Could not load Raven.js script:', err);
@@ -80,43 +92,72 @@ function startErrorLogging() {
       console.warn('Could not find `window.Raven` global');
       return;
     }
-    configureRaven();
+    startRaven();
   });
 
-  function configureRaven () {
-    console.log('Raven.js script loaded');
+  function startRaven () {
     Raven.config('https://e359be9fb9324addb0dc97b664cf5ee6@sentry.io/294878')
-         .install();
+          .install();
   }
 };
 
 function startAnalytics() {
-  var CURRENT_VERSION = '1.0.1';
-  var ga = telemetry.ga.create('UA-77033033-6', 'auto', 'mozillaResearch');
-  ga('set', 'dimension1', CURRENT_VERSION);
-  ga('send', 'pageview');
-  return ga;
+  var tracker = newTracker('UA-77033033-6', {
+    'groups': 'MozillaResearch',
+    'custom_map': {
+      'dimension1': 'version'
+    }
+  });
+  tracker('event', 'using_webvr_template', { version: CURRENT_VERSION });
+  return tracker;
 }
 
-function configurePerformanceAPI(ga) {
+function setupPerformanceAPI(tracker) {
   telemetry.performance = {
     mark: function (name) {
+      if (doNotTrack()) { return; }
+
       performance.mark(name);
     },
-  
+
     measure: function (name, start, end) {
-      if (navigator.doNotTrack === '1') {
-        return;
-      }
+      if (doNotTrack()) { return; }
+
       performance.measure(name, start, end);
       var performanceEntry = performance.getEntriesByName(name)[0];
       var duration = performanceEntry.duration;
-      ga('send', 'event', 'Performance', name, undefined, duration);
+      tracker('event', name, {
+        'event_category': 'Performance',
+        'value': Math.round(duration)
+      });
     }
   };
 }
 
-function injectScript (src, callback) {
+// Provides a convenient shortcut for named trackers by automatically adding the
+// name of the tracker to the command. The function accepts the same parameters
+// that follow `create` command. See:
+// https://developers.google.com/analytics/devguides/collection/analyticsjs/creating-trackers
+function newTracker(trackingId, options) {
+  if (doNotTrack()) { return NO_OP; }
+
+  options = options || {};
+  var groups = options.groups;
+  telemetry._gtag('config', trackingId, options);
+  return trackingFunction;
+
+  function trackingFunction(command, label, options) {
+    if (doNotTrack()) { return; }
+
+    options = options || {};
+    if (groups) {
+      options.send_to = groups;
+    }
+    telemetry._gtag(command, label, options);
+  };
+}
+
+function injectScript(src, callback) {
   var script = document.createElement('script');
   script.src = src;
   script.crossorigin = 'anonymous';
@@ -134,4 +175,13 @@ function injectScript (src, callback) {
   return script;
 }
 
-})(window);
+// IE9/IE10 uses a prefixed version while MS Edge sets the property in
+// `window` instead of `navigator`:
+// https://developer.mozilla.org/en-US/docs/Web/API/Navigator/doNotTrack#Browser_compatibility
+function doNotTrack() {
+  return navigator.doNotTrack === '1' ||
+          navigator.msDoNotTrack === '1' ||
+          window.doNotTrack === '1';
+}
+
+})(window);

docs/customization/adding-ga.md

@@ -18,53 +18,16 @@ When you finish, click on `Get Tracking ID` at the bottom of the page:
 
 ![Buttons Get Tracking ID and Cancel at the bottom of the page](./images/filled-2.png)
 
-This will redirect you to the configuration page where you find the HTML code you need to use in the template:
+This will redirect you to the configuration page where you find the HTML code you'd use in the template:
 
 ![The configuration page includes the instructions for setting up your site](./images/setup-done.png)
 
-**Don't use the snippet above**. Instead, with your favourite code editor, open the file at `Assets/WebGLTemplates/WebVR/index.html` and paste the following code after including the `telemetry.js` library, preferably at the bottom of the `<head>` tag:
-
-```html
-<script>
-  var ga = MozillaResearch.telemetry.ga.create('UA-XXXXXXX-Y');
-  ga('send', 'pageview');
-</script>
-```
-
-![The code provided by GA should be added after including the telemetry library](./images/add-to-index.png)
-
-### Template integration of Google Analytics
-
-If you have used Google Analytics before, the previous code should remind you of the familiar Analytics snippet:
-
-```js
-ga('create', 'UA-XXXXXX-Y', 'auto');
-ga('send', 'pageview');
-```
-
-When using Analytics inside the template, use the `create` method of `MozillaReasearch.telemetry.ga` instead of the `create` command. It will return a tracking function which can be used in the same way you would use it in the guide [Sending Data to Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/creating-trackers).
-
-```js
-var ga = MozillaResearch.telemetry.ga.create('UA-XXXXXX-Y', 'auto');
-ga('send', 'pageview');
-```
-
-If you want to customize the way you create the tracker, read [Creating Trackers](https://developers.google.com/analytics/devguides/collection/analyticsjs/creating-trackers) and remember that:
-
-```js
-ga('create', arg1, arg2, ...);
-``` 
-
-Is equivalent to:
-
-```js
-var ga = MozillaResearch.telemetry.ga.create(arg1, arg2, ...);
-```
+Add the snippet just after the `<head>` tag and you'll be ready to go.
 
 ## Using Google Analytics
 
-The amount of data in Google Analytics can be overwhelming to navigate and dissect. Fortunately, the folks at Google have developed a series of courses to explain you the main concepts of traffic analysis. We recommend you start at [Google Analytics Academy](https://analytics.google.com/analytics/academy/). 
+The amount of data in Google Analytics can be overwhelming to navigate and dissect. Fortunately, the folks at Google have developed a series of courses to explain you the main concepts of traffic analysis. We recommend you start at [Google Analytics Academy](https://analytics.google.com/analytics/academy/).
 
 ## Open-source alternatives
 
-There are a few [open-source alternatives](https://en.wikipedia.org/wiki/List_of_web_analytics_software#Free_/_Open_source_(FLOSS)) out there. Like Google Analytics, they are free although you need to host them yourself. We recommend [Matomo](https://matomo.org/) and [Open Web Analytics](http://www.openwebanalytics.com) (OWA). Both offer geolocation, click-heat maps, traffic by referrer, event tracking, etc. Which specifically depends on your needs but you can compare both side by side visiting the [demo pages for Matomo](https://demo.matomo.org) and [OWA](http://demo.openwebanalytics.com/owa/). 
+There are a few [open-source alternatives](https://en.wikipedia.org/wiki/List_of_web_analytics_software#Free_/_Open_source_(FLOSS)) out there. Like Google Analytics, they are free although you need to host them yourself. We recommend [Matomo](https://matomo.org/) and [Open Web Analytics](http://www.openwebanalytics.com) (OWA). Both offer geolocation, click-heat maps, traffic by referrer, event tracking, etc. Which specifically depends on your needs but you can compare both side by side visiting the [demo pages for Matomo](https://demo.matomo.org) and [OWA](http://demo.openwebanalytics.com/owa/).