@okgrow/auto-analytics

Auto Analytics

Complete Google Analytics, Mixpanel, KISSmetrics (and more) integration for JavaScript applications.

Use one API, thanks to Segment.io's analytics.js, to easily and automatically record and send data from your JavaScript application to your analytics platforms.

NOTE: The @okgrow/auto-analytics package replaces the now deprecated okgrow-auto-analytics package.

Table of Contents

• Install
• Currently Supported Analytic Services
• Ad-blocker
• Configuration
  • Page views
  • Event tracking
  • Debugging
  • Example React Router Application
• Maintainers
• Contributing
• License

Background

Auto Analytics 2.0+

With version 2.X we are removing the embedded Segment analytics.js module. With version 2.0.0 and beyond you will need to build your own Segment analytics.js module manually.

NOTE: We have not added the package Segment analytics.js as an explicit dependency because some developers will prefer to add only individual integrations or create a customized analytics.js module in order to keep the weight of the package to a minimum.

Auto Analytics 1.0+

With the first version of this package we basically extracted code from our more Meteor-specific Atmosphere package to create a more generally usable package for the whole JavaScript community.

Quick Start

npm install --save @okgrow/auto-analytics

import { initAnalytics } from '@okgrow/auto-analytics';
// NOTE: You must build your own analytics.js, see Creating Segment's analytics.js for details.
import analytics from './your-custom-build/analytics.min.js';

// Add your analytics integrations and their tracking ids + config options here.
const settings = {
  analytics,
  integrations: {
    'Google Analytics': { 'trackingId': 'Your tracking ID' },
    'Mixpanel': { 'token': '...', 'people': true },
  },
  options: {
    // Segment options to be passed to initialize() from analytics.js-core
  },
  autorun: true, // Defaults to true if not provided.
};

initAnalytics(settings);

Creating Segment's analytics.js

Recommended process

1. Clone this example repo down git clone https://github.com/okgrow/analytics.js.git
2. cd analytics.js
3. npm install && npm run build
4. The build will output these two files: analytics.js and analytics.min.js

Too reduce the final bundle size, remove any integrations that you are not using. To do that:

1. Open up the lib/integrations.js file and remove all the integrations that you will not use.
2. Now re-run npm run build
3. Your analytics.js and analytics.min.js will only contain the integrations you are using.
4. Copy the analytics.min.js file to your project so that @okgrow/auto-analytics can use it.

Not Recommended: Use Segment's example analytics.js Package

Segment's analytics.js package offers a large number of integrations with various analytics providers. Installing their example package will give you all of their supported integrations(very large bundle size):

npm install --save analytics.js

However it is recommend that you build your own analytics.js with only the integrations you need. You can see all possible analytics.js-integrations here.

Settings Configuration

The service names and API key-names provided in the integrations section are specific to each platform. Make sure to use the correct service name and key shown for the platform you're adding.

There are other options which are not documented in the example above. To find them search for your specific integration in this file and look at the options and their defaults that are set with .option(...).

Ad-blocker

If you, or your users, are running an ad blocker in their browser and the analytics package is not bundled into a single JavaScript file to the browser (i.e., downloads as analytics.js or something similar) the browser's ad blocker may prevent analytics tracking. This can happen during development mode when all JavaScript files are typically not bundled together.

To solve this problem with a Meteor application, for example, you can run the application in production mode like this:

meteor run --production --settings settings.json

NOTE: If an Ad-blocker is enabled the expected behaviour is that your analytic events will not be received. You will see an error message in your console reporting the events being blocked.

Page views

Compatible with any router, this package will log page views automatically. Each page is logged with the follow parameters:

• path: path part of the URL
• title: the page's title
• url: hostname + path
• search: the URL's query string, if provided. blank otherwise
• referrer: hostname + old path, if coming from a previous route

To disable automatic page view tracking add autorun: false to your settings object when configuring then manually log a page view by calling analytics.page('page name'):

Event tracking

Track any event by simply calling the analytics.track() function:

analytics.track("Bought Ticket", {
  eventName: "Wine Tasting",
  couponValue: 50,
});

Check Segment.io's analytics.js track documentation for a full description of track() and all the other functions available in this package.

Debugging

When adding your platforms and setting events to track you may want to keep debug on locally. This will log all the analytics package's activity to the console.

To turn on debugging, in the console:

> analytics.debug()

Turn debugging off, in the console:

> analytics.debug(false)

Example React Router Application

This package includes an examples directory containing a simple (Meteor) application using react-router with a analytics.min.js containing only the Google Analytics and Mixpanel integrations. This is just an example with a common router and doesn't imply this plugin only works with this router or only with Meteor. This application can be run from its directory with:

meteor --settings settings.json --production.

Maintainers

This is an open source package. We hope to deal with contributions in a timely manner, but that's not always the case. The main maintainers are:

@okgrow

Feel free to ping if there are open issues or pull requests which are taking a while to be dealt with!

Contributing

Issues and Pull Requests are always welcome.

Please read our contribution guidelines.

If you are interested in becoming a maintainer, get in touch with us by sending an email or opening an issue. You should already have code merged into the project. Active contributors are encouraged to get in touch.

Please note that all interactions in @okgrow's repos should follow our Code of Conduct.

License

Released under the MIT license © 2017 OK GROW!.