Skip to content

SpirentOrion/react-ga

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

60 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

react-ga

React Google Analytics Module

Build Status

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

About

React Google Analytics Module

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%