Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/okgrow/auto-analytics
UNMAINTAINED! - Complete Google Analytics, Mixpanel, KISSmetrics (and more) integration for JavaScript applications.
https://github.com/okgrow/auto-analytics
analytics auto-analytics google-analytics javascript kissmetrics meteor mixpanel segment
Last synced: about 1 month ago
JSON representation
UNMAINTAINED! - Complete Google Analytics, Mixpanel, KISSmetrics (and more) integration for JavaScript applications.
- Host: GitHub
- URL: https://github.com/okgrow/auto-analytics
- Owner: okgrow
- License: mit
- Created: 2017-02-03T15:56:35.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2019-01-22T22:02:33.000Z (almost 6 years ago)
- Last Synced: 2024-08-09T17:38:11.189Z (4 months ago)
- Topics: analytics, auto-analytics, google-analytics, javascript, kissmetrics, meteor, mixpanel, segment
- Language: JavaScript
- Homepage:
- Size: 251 KB
- Stars: 28
- Watchers: 4
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Auto Analytics
Automated page tracking (+ more!) with any Analytics service of your choice! :fire:
Use one API, thanks to Segment.io's [analytics.js](https://segment.com/docs/libraries/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.
**NOTE:** This pkg is **no longer being actively maintained**, if you'd like to maintain this pkg please express interest by opening an issue.
## Table of Contents
- [Quick Start](#quick-start)
- [Creating Segment's analytics.js](#creating-segments-analyticsjs)
- [Recommended Process](#recommended-process)
- [Not Recommended: Use Segment's example analytics.js Package](#not-recommended-use-segments-example-analyticsjs-package)
- [Integrations Config](#integrations-config)
- [Package Usage](#package-usage)
- [Page views](#page-views)
- [Event tracking](#event-tracking)
- [Debugging](#debugging)
- [Ad-blocker](#ad-blocker)
- [Example React Router Application](#example-react-router-application)
- [Maintainers](#maintainers)
- [Contributing](#contributing)
- [License](#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
```sh
npm install --save @okgrow/auto-analytics
```
```js
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
If you wish to keep using the same analytics.min.js bundle (file size: 244kb) from v1.0.6 you can find it [here](https://github.com/okgrow/analytics.js/blob/auto-analytics-v1.0.4/analytics.min.js). To reduce bundle size or to add Analytic integrations previously not supported then follow the below process.
### Recommended process
1. Clone this example repo down `git clone https://github.com/okgrow/analytics.js.git`
1. `cd analytics.js`
1. `npm install && npm run build`
1. 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.
1. Now re-run `npm run build`
1. Your `analytics.js` and `analytics.min.js` will only contain the integrations you are using.
1. 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):
```sh
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](https://github.com/segment-integrations?query=analytics.js-integration).
## Integrations Config
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](https://github.com/okgrow/analytics.js/blob/master/analytics.js) and look at the options and their defaults that are set with `.option(...)`.
## Package Usage
### 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:
```js
analytics.track("Bought Ticket", {
eventName: "Wine Tasting",
couponValue: 50,
});
```
Check Segment.io's [analytics.js track documentation](https://segment.com/docs/libraries/analytics.js/#track) 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)`
### 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.
### 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](https://github.com/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](https://github.com/okgrow/guides/blob/master/docs/OpenSource-Contributing.md).
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](https://github.com/okgrow/guides/blob/master/docs/OpenSource-CodeOfConduct.md).
## License
Released under the [MIT license](https://github.com/okgrow/analytics/blob/master/License.md) © 2017 OK GROW!.