react-ga

React Google Analytics Module

This is a JavaScript module that can be used to include Google Analytics tracking code in a website or app that uses React for its front-end codebase. It does not currently use any React code internally, but has been written for use with a number of Mozilla Foundation websites that are using React, as a way to standardize our GA Instrumentation across projects.

It is designed to work with the latest version of Google Analytics, Univeral Analytics. At this point, all Google Analytics projects are being upgraded to Universal Analytics, so this module will not support the older ga.js implementation.

This module is mildly opinionated in how we instrument tracking within our front-end code. Our API is slightly more verbose than the core Google Analytics library, in the hope that the code is easier to read and understand for our engineers. See examples below.

If you use react-ga too, we'd love your feedback. Feel free to file issues, ideas and pull requests against this repo.

Installation

npm install react-ga

Use

Initializing GA and Tracking Pageviews with react-router

var React = require('react');
var Router = require('react-router');
var Route = Router.Route;

...

var ga = require('react-ga');

...

exports.run = function(location, el) {
  ga.initialize(process.env.GA_TRACKING_ID);
  Router.run(routes, location, function(Handler, state) {
    ga.pageview(state.pathname);
    React.render(<Handler/>, el);
  });
};

API

ga.initialize(gaTrackingID, options)

GA must be initialized using this function before any of the other tracking functions will record any data.

Example

var options = { debug: true, gaOptions: {userId: 123} };
ga.initialize('UA-000000-01', options);

Value	Notes
gaTrackingID	String. GA Tracking ID like 'UA-000000-01'
options.debug	Boolean. Optional. If set to true, will output additional feedback to the console
options.gaOptions	Object. Optional. GA configurable fields.

See example above for use with react-router.

ga.pageview(path)

Example

ga.pageview('/about/contact-us', {'dimension0': 'blabla'});

Value	Notes
path	String. e.g. '/get-involved/other-ways-to-help'
fieldsObject	Object. see https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference

See example above for use with react-router.

ga.modalview(modalName)

A modal view is often an equivilent to a pageview in our UX, but without a change in URL that would record a standard GA pageview. For example, a 'contact us' modal may be accessible from any page in a site, even if we don't have a standalone 'contact us' page on it's own URL. In this scenario, the modalview should be recorded using this function.

Example

ga.modalview('/about/contact-us');

Value	Notes
modalName	String. E.g. 'login', 'read-terms-and-conditions'

ga.event(args)

Tracking in-page event interactions is key to understanding the use of any interactive web property. This is how we record user interactions that don't trigger a change in URL.

Examples

ga.event( { category: 'User',
            action: 'Created an Account' } );

ga.event( { category: 'Social',
            action: 'Rated an App',
            value: 3 } );

ga.event( { category: 'Editing',
            action: 'Deleted Component',
            label: 'Game Widget' } );

ga.event( { category: 'Promotion',
            action: 'Displayed Promotional Widget',
            label: 'Homepage Thing',
            nonInteraction: true } );

Value	Notes
args.category	String. Required. A top level category for these events. E.g. 'User', 'Navigation', 'App Editing', etc
args.action	String. Required. A description of the behaviour. E.g. 'Clicked Delete', 'Added a component', 'Deleted account', etc.
args.label	String. Optional. More precise labelling of the related action. E.g. alongside the 'Added a component' action, we could add the name of a component as the label. E.g. 'Survey', 'Heading', 'Button', etc.
args.value	Int. Optional. A means of recording a numerical value against an event. E.g. a rating, a score, etc.
args.nonInteraction	Boolean. If an event is not triggered by a user interaction, but instead by our code (e.g. on page load, it should be flagged as a nonInteraction event to avoid skewing bounce rate data.

ga.exception(args)

Exception tracking allows you to measure the number and type of crashes or errors that occur on your property.

Examples

try {
  // Runs code that may or may not work.
  window.possibiliyUndefinedFunction();
} catch(err) {
  ga.exception({
    description: err.message,
    fatal: false
  });
}

Value	Notes
args.description	String. Optional. A description of the exception.
args.fatal	Boolean. True if the exception was fatal.

ga.outboundLink(args, hitCallback)

Tracking links out to external URLs (including id.webmaker.org for oAuth2 login flow).

Examples

ga.outboundLink( { label: 'Clicked Create an Account' },
                    function () {
                      console.log('redirect here');
                    } );

Value	Notes
args.label	String. Required. Description of where the outbound link points to. Either as a URL, or a string
hitCallback	function. The react-ga implementation accounts for the possibility that GA servers are down, or GA is blocked, by using a fallback 250ms timeout. See notes in GA Dev Guide

ga.plugin.require(name)

Require GA plugins.

Example

ga.plugin.require('ecommerce');

ga.plugin.execute(pluginName, action, payload)

Execute the action for the pluginName with the payload.

Example

ga.plugin.execute('ecommerce', 'addTransaction', {
  'id': "jd38je31j",
  'revenue': "3.50"
});

ga.customtracker(key, value)

Custom dimensions and metrics are a powerful way to send custom data to Google Analytics. Web developers can use custom dimensions and metrics to segment and measure differences between: logged in and logged out users, authors of pages, levels in games, or any other business data you have on a page.

Example

ga.customtracker('dimension1', '10001');

Value	Notes
key	String. Custom dimension/metric name e.g. "dimension1"
value	`Number

---

Development

Prerequisites

• node.js
• npm
• npm install --global gulp

To Test

npm test

Submitting a PR

• Always work on a new branch
• Submit Pull Requests against master

1. Open a PR
2. Request code review
3. Complete code review with fixes
4. Merge the PR
5. Then, bump the version as below

The regenerated dist files should not be committed until the review has been R+'d and merged, since it's much easier to do the code review without the dist clutter getting in the way.

To Ship (i.e bump the version number)

git pull...
gulp build
mversion patch
git add .
git commit...
git push...
npm publish

---

Acknowledgements

• Quite a lot of the code in this repo, came from webmaker-analytics