ember-insights

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).

Getting started

$ 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.

Live demo

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

Getting more details

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.

#configure/2 and #configure/0 (as a default convinience)

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.

#track/1 and #track/0 (as a default convinience)

insights

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.

timing

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 } });

#start/1 and #stop/0

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();

Advanced #configure/1

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.

Ask for help

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.

Acknowledgement

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