ember-keen

This add-on allows working with Keen.IO without requiring the Keen.IO SDK. It provides a service to send events. In the future, reading events will also be supported. The service also auto-combines your events to avoid multiple unnecessary requests.

Compatibility

• Ember.js v2.18 or above (3.6 or above if using the automated pageview tracking)
• Ember CLI v2.13 or above
• Node.js v8 or above

Installation

This add-on was inspired by ember-keen-tracking, and the fact that it should not be necessary to include a library just to make a few Ajax-requests.

Installation

• ember install ember-keen

Quick Start

For a quick start with tracking page views, you'll need (as a minimum) the following:

In your config/environment.js:

let ENV = {
  /* ... */
  keen: {
    projectId: 'MY-ID',
    writeKey: 'MY-WRITE-KEY'
  }
}

Now in your application route, add the following code:

import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';

export default Route.extend({
  keen: service(),
  
  init() {
    this._super(...arguments);
    this.keen.trackAllPageViews();
  }
})

That's it! You'll now track each page view, together with key performance indicators (model load time & render time) & query params, for that route. In addition to this, you can easily track custom events, like when a user clicks on a specific button.

For more details on how to configure ember-keen & how to send custom events, as well as for customization options of the page view tracking, see the following in-depth documentation.

Configuration

You will need to specify your Keen.IO project id and write/read key. You only need the write key if you want to record data, and the read key if you want to analyse data. The recommended way to do this is via ember-cli-dotenv:

Then, you can specify the keys in your config/environment.js:

let ENV = {
  /* ... */
  keen: {
    projectId: process.env.KEEN_PROJECT_ID,
    writeKey: process.env.KEEN_WRITE_KEY,
    readKey: process.env.KEEN_READ_KEY
  }
}

Also, normally you will not want to have actual logging (to the Keen API) in your development environment. For this purpose, you can enable logging requests to your console in your config/environment.js:

ENV.keen = {
  logRequests: true
};

The service will then log all requests to the console, but only if environment === 'development'.

Usage

You can manually track events with methods provided by the keen-service:

sendEvent(eventName, data)

export default Route.extend({
  keen: service(),
  
  actions: {
    buttonClicked() {
      this.get('keen').sendEvent('button-click', {
        otherData: 1,
        somethingElse: 'foobar'
      });  
    }
  }
});

sendEvent will debounce sending a request to the Keen.IO API by 5 seconds. This means that if you send 10 events in 7 seconds via sendEvent, only one actual request will be made to the Keen.IO API.

You can also overwrite mergeData to return an object which will be merged with the data provided for every event sent via sendEvent:

import KeenService from 'ember-keen/services/keen';

export default KeenService.extend({
  mergeData: computed('userSession', function() {
    return {
      currentUser: this.get('userSession.userId')
    };
  })
});

With this configuration, the above request would result in the following data object sent to Keen.IO:

{
  otherData: 1,
  somethingElse: 'foobar',
  currentUser: 193
}

sendEventImmediately(event, data)

This will send an event immediately and return a promise, which resolves when the event has been successfully sent, or rejects if an error occurs. This can be used to check if a message has actually been sent to the server. It takes the same options as sendEvent().

query(action, event, data)

Query data from Keen.io. This will make a GET request and return a promise, which resolves with the data returned form the API.

• action is the action to perform. This can be a simple action like count or something more complex like funnel.
• event is the event collection to query. If this is set, data.event_collection will be set to this value.
• data is other data that will be included in the query. This should include things like timeframe, target_property or anything else required by Keen.

For more information about actions & the required data, see the Keen.IO API Docs. You can also do things like multi analyses, funnel analyses or extractions with this method.

Note that this will return a promise that resolves with a POJO. The actual response data is available under result, e.g.:

this.get('keen').query('count', 'page-views').then(function(data) {
  console.log(`There have been ${data.result} page views.`); 
});

Further information

• More about the page view tracking

Fetch configuration

ember-keen uses ember-fetch to talk to the Keen.IO API. Other than that, there are no dependencies.

• More information about customizing the API requests