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
- [Page views](#page-views)
- [Event tracking](#event-tracking)
- Debugging
- Example React Router ApplicationBackground
Auto Analytics 2.0+
With version 2.X we are removing the embedded Segmentanalytics.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
- Clone this example repo down
git clone https://github.com/okgrow/analytics.js.git
cd analytics.js
npm install && npm run build
- The build will output these two files:
analytics.js
andanalytics.min.js
Too reduce the final bundle size, remove any integrations that you are not using. To do that:
- Open up the
lib/integrations.js
file and remove all the integrations that you will not use. - Now re-run
npm run build
- Your
analytics.js
andanalytics.min.js
will only contain the integrations you are using. - 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 theintegrations
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 asanalytics.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 routeTo 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 theanalytics.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 anexamples
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.