iron-router-ga

Google analytics (universal edition) for Meteor with some Iron Router sugar for tracking page views and doing A/B testing with Content Experiments.

Installation

$ meteor add reywood:iron-router-ga

Meteor Settings

Configure analytics by adding a ga section to the public section of your Meteor settings. The only required property is id which is your Google Analytics tracking ID.

1{
2    "public": {
3        "ga": {
4            "id": "UA-XXXX-Y"
5        }
6    }
7}

Advanced configuration options:

For more info on possible values for the configuration options below, check out Google's Advanced Configuration page.

• create -- object literal

  Options you would like to pass to ga("create", "UA-XXXX-Y", ...). Should have any of cookieDomain, cookieName, cookieExpires, etc as properties.

• set -- object literal

  Settings to apply to the tracker with ga("set", ...). These include forceSSL, anonymizeIp, etc.

• require -- object literal

  Additional tracking options to require with ga("require", ...) such as Display Advertising Features or Enhanced Link Attribution. For features like displayfeatures that don't have a corresponding *.js parameter (as linkid does), simply set the property value to true.

• trackUserId -- boolean

  If set to true, the currently logged in user's ID will be sent with all pageviews, events, etc. Learn more about user ID tracking. Defaults to false.

Advanced configuration example:

1{
2    "public": {
3        "ga": {
4            "id": "UA-XXXX-Y",
5            "create": {
6                "cookieDomain": "example.com",
7                "cookieName": "my_ga_cookie",
8                "cookieExpires": 3600
9            },
10            "set": {
11                "forceSSL": true,
12                "anonymizeIp": true
13            },
14            "require": {
15                "displayfeatures": true,
16                "linkid": "linkid.js"
17            },
18            "trackUserId": true
19        }
20    }
21}

Usage

Once you have installed this package and added the required configuration, you will have access to the ga function anywhere in your client-side Meteor code. You can use it just as you would on any other site.

To enable page view tracking and content experiments (discussed below), you will need to add the plugin to your router.

1if (Meteor.isClient) {
2    Router.plugin('reywood:iron-router-ga');
3}

Event Tracking

Tracking events is the same as always:

1ga("send", "event", category, action, label, value);

Page View Tracking

Tracking page views is accomplished by adding configuration options to Iron Router. You can enable page view tracking for every route site-wide by configuring the router like so:

1Router.configure({
2    trackPageView: true
3});

Alternately, you can enable tracking for certain routes individually like so:

1Router.route("routeName", {
2    // ...
3    trackPageView: true
4    // ...
5});
6
7// ** or **
8
9Router.map(function() {
10    this.route("routeName", {
11        // ...
12        trackPageView: true
13        // ...
14    });
15});

If you have enabled site-wide page view tracking but want to disable it for a certain route:

1Router.route("routeName", {
2    // ...
3    trackPageView: false
4    // ...
5});

A/B Testing with Content Experiments

Each route in your app can be configured with an experiment ID and a list of templates to show for each variation. First, you must set up the experiment in your Google Analytics dashboard. Once that's done, add a contentExperiment configuration option to the route you want to experiment on (see snippet below for details). The number of templates specified in the variationTemplates array property must match the number of variations (including the original) configured for the experiment.

All visitors to the site are assigned to one of the variations according to the settings for your experiment (multi-arm bandit, percentage of traffic to experiment, etc). These settings are configured in your Google Analytics dashboard or via Google's API. Returning visitors will see the same variation they saw the first time they visited.

Any route with an experiment assigned to it will also track an event. This event will show up in your analytics dashboard under the category "iron-router-ga". This is a requirement for experiments in order to record a user's chosen variation.

1Router.route("routeName", {
2    // ...
3    contentExperiment: {
4        id: "YOUR_EXPERIMENT_ID",
5        variationTemplates: [ "original", "variation1", "variation2" ]
6    }
7    // ...
8});

<template name="original">
    Original
</template>

<template name="variation1">
    Variation 1
</template>

<template name="variation2">
    Variation 2
</template>

Cordova settings

If you are building a Cordova app, you will need to allow your app to access the Google Analytics servers. Add the following snippet to your mobile-config.js file.

1App.accessRule('*.google-analytics.com/*');

Known Issues

Route dispatch never rendered

If you are using content experiments, you may see the following message in your browser's JavaScript console.

Route dispatch never rendered. Did you forget to call this.next() in an onBeforeAction?

When a route with an experiment is triggered, a JS file specific to your experiment must be loaded from Google in order to select the appropriate variant to show. While this file is loading, iron-router-ga will show your "loading" template and effectively pause the route by not calling this.next() in onBeforeNext. In practice, this pause is barely noticeable, but will cause the above message to appear. Once the file is loaded, your route will unpause and continue loading. This behavior appears to be by design in iron-router. If you know different, please set me straight.

---

If you find a bug or would like to see an improvement made, please file an issue or submit a pull request on GitHub.