analytics-proxy

A small analytics dispatching library that proxies common events to multiple providers. Currently includes Mixpanel, Intercom and Snowplow.

Installation

The package is hosted on Gemfury under @streemau/analytics-proxy. You will need to set up an Gemfury token via an environment variable, which can be found in your Gemfury account: export GEMFURY_TOKEN="..."

Then, you will need a .npmrc that contains the following, so you can install the private packages as well as public NPM packages:

@streemau:registry=https://npm.fury.io/streem/
//npm.fury.io/streem/:_authToken=${GEMFURY_TOKEN}
always-auth=true
registry="https://registry.npmjs.com/"

Usage

Ensure the script tags for each provider are loaded in the head of your app. Then simply import/require the analytics-proxy and configure with your analytics providers:

import AnalyticsProxy from 'analytics-proxy';

// configuration
const config = {
  // includes keys of the providers with their own config e.g. keys, settings, etc.
  mixpanel: { token: "<MIXPANEL_TOKEN>", ...other_config },
  intercom: { app_id: "<INTERCOM_APP_ID>", ...other_config },
  snowplow: { url: "<SNOWPLOW_URL>", options: <SNOWPLOW_OPTIONS> }
};

// create an instance to dispatch events
const analytics = new AnalyticsProxy(config);

// Initialize the providers to start tracking
analytics.init();

// track the currently logged in user, optionally with some metadata about the user
const userId = 123;
const metadata = { email: '[email protected]', first_name: 'Jackson' , last_name: 'Gross' };
analytics.identify(userId, metadata);

// stop tracking the user
analytics.reset();

// record a page view for the current page
analytics.pageView();

// record an event with some optional metadata describing the event
const event = 'Generated Report';
const eventMetadata = { type: 'pdf', title: 'My awesome report' };
analytics.trackEvent(event, eventMetadata);

Getting started

1. Install dependencies

• Run yarn install (recommended) or npm install to get the project's dependencies
• Run yarn build or npm run build to produce minified version of the library.

2. Development mode

• Having all the dependencies installed run yarn dev or npm run dev. This command will generate an non-minified version of the library and will run a watcher so you get the compilation on file change.

3. Running the tests

• Run yarn test or npm run test. Can also run in watch mode with yarn test:watch or npm run test:watch

Releases

Ensure all new features have adequate test coverage before making a release. Once ready, ensure the package.json version number has been incremented following semver. Then authenticate to Gemfury through npm (see https://gemfury.com/help/npm-registry#npm-config) with npm login. Then simply run npm publish and the changes will be available from Gemfury!

Scripts

• yarn build or npm run build - produces production version of the library under the lib folder
• yarn dev or npm run dev - produces development version of the library and runs a watcher
• yarn test or npm run test - runs the tests
• yarn test:watch or npm run test:watch - same as above but in a watch mode
• npm publish - publishes a new version of the package to Gemfury.