monsoonco / ember-insights Goto Github PK

Hey, listen! This is alpha-level software with planned future changes (check out CHANGELOG each time after releasing MINOR milestone). Users's metrics are extensive, and not trivial to implement. ember-insights.js is heavily based on Google Analytics (with ability to add others).

$ ember install:addon ember-insights

Use blueprint for generating configs and initializer.

$ ember generate ember-insights-initializer ember-insights

Or just drop an initializer manually.

import EmberInsights from 'ember-insights';

export default {
  name: 'ember-insights',
  initialize: function(/*container, application*/) {
    EmberInsights.configure().track().start();
  }
};

In additional, there is available an AMD module and Bower component, find more details here ember-insights.amd.js.

The easiest way to find out more details is checking live demo and their sources.

This section describes how-to tweak configuration for what you need.

import EmberInsights from 'ember-insights';

There are a couple of separate steps for specifying tracking such as configure, track and finally start and stop.

The simplest way to start tracking by default:

EmberInsights.configure().track().start();

Defines a default environment with ConsoleTracker and sends all transitions and actions to Ember.Logger.log.

Defines environment-specific trackers and their options.

• name - Specifies name, sets default name by default.
• settings - Defines options such as:
  • debug:boolean - Pushes messages into Ember.debug, sets true by default.
  • trackerFactory:function - Tracker, uses an EmberInsights.ConsoleTracker by default.
  • trackTransitionsAs:string - Defines how to track transitions (available options are pageview and event), uses a pageview by default.

Here is a configure/2 example:

EmberInsights.configure('default', {
  debug: true,
  trackerFactory: EmberInsights.ConsoleTracker.factory,
  trackTransitionsAs: 'pageview'
});

Which is the same as available by default:

EmberInsights.configure();

Tips: Trackers wiki has more specific details.

Defines what exactly should be tracked and what kind of things should be ignored at all.

Here is a track/1 example:

EmberInsights.configure().track({
  insights: { ALL_TRANSITIONS: true, ALL_ACTIONS: true }
});

Which is the same as available by default:

EmberInsights.configure().track();

Keep in mind that track/1 could be used for specifying particular piece of application that should(not) be tracked. You are able to call the track/1 in chain.

}).track({
  insights: { /*specific part of application that should(not) be tracked */ }
}).track({
  insights: { /*specific part of application that should(not) be tracked */ }
});

Each insights definition could provide its own dispatcher function and overwrite default dispatcher. The dispatch/3 enables you to submit a custom insight other that sends by default in context of specific track/1 definition.

}).track({
  insights: { /*specific part of application that should(not) be tracked */ },
  dispatch: function(type, context, tracker) {
    tracker.sendEvent(/*specific event*/);
    tracker.sendEvent(/*specific event*/);
  }
}).track({
  insights: { /*specific part of application that should(not) be tracked */ }
});

Tips: Tracking mappings page has more specific details.

Defines ability to send a timing report. This feature is based on HTML5: User Timing API and works just only for particular browsers.

.track({ timing: { transitions: true } });

Runtime management. So that, you are be able to start by environment name and stop tracking at all.

var emberInsights = EmberInsights.configure(/*options*/).track(/*mappings*/);
// ...
emberInsights.start();
// ...
emberInsights.stop();

This one provides you a bit different way for specifying environments as described before. The main purpose is ability to specify environments and apply all further tracks for all environments recursively.

Here is a short example:

EmberInsights.configure({
  'development': { trackerFactory: EmberInsights.ConsoleTracker.factory },
  'production':  { trackerFactory: EmberInsights.GoogleTracker.factory },
}).track({
  insights: { /*specific part of application that should(not) be tracked */ }
}).track({
  insights: { /*specific part of application that should(not) be tracked */ }
});

It provides ability to drop a message to Ember.Logger.log console for development and sends insights into the Google Analytics in production mode.

Check out the wiki. If you feel like porting or fixing something, please drop a pull request or issue tracker at GitHub! Check out the CONTRIBUTING.md for more details.

I believe that with the help of everyone we can bring this to Ember in a modular and robust way.

Project's HEAD repository is https://github.com/ember-insights/ember-insights.