An Ember add-on to work with Keen.IO
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
addon
app
blueprints/ember-keen
config
docs
tests
vendor
.editorconfig
.ember-cli
.eslintignore
.eslintrc.js
.gitignore
.npmignore
.npmrc
.template-lintrc.js
.travis.yml
.watchmanconfig
.yarnrc
CHANGELOG.md
LICENSE.md
README.md
ember-cli-build.js
index.js
package.json
testem.js
yarn.lock

README.md

ember-keen

Build Status Ember Observer Score

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.

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'
  }
}

In the route you want to track:

import Route from '@ember/routing/route';
import KeenTrackPageviewMixin from 'ember-keen/mixins/keen-track-pageview';

export default Route.extend(KeenTrackPageviewMixin, {});

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

Fetch configuration

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