Ember CLI segment

Ember CLI addons that provides a clean and easy way to integrate your Ember application with Segment.com.

Installation

ember install ember-cli-segment

Configuration/Logging

Add your Segment WRITE_KEY to the segment config object for Analytics.js to be loaded and configured automatically.

There is an option available to configure the events log tracking, the default value is false. This option is optional, but recommended.

In your config/environment.js

ENV['segment'] = {
  WRITE_KEY: 'your_segment_write_key',
  LOG_EVENT_TRACKING: true
};

Version 0.1.x is compatible with ember > 1.13.x

Usage

The addon will add following elements to your CLI project:

an initializer that will inject an segment object as a wrapper around Segment JS methods on controllers, routes and router.
a didTransition method on the router calling segment.trackPageView and applicationRoute.identifyUser if it exists.
a mixin that you can use where else you need.
a service that you can inject in components (or anything): segment: Ember.inject.service()

Tracking Page Views

Your router will automatically send a page view event to Segment using the method page under window.analytics everytime the URL changes.

If you need to call it manually for some reason, you can do it using the following method on controllers and routes.

this.segment.trackPageView();

The method trackPageView can receive a parameter that's the page url, if not provided it will fetch from window.location.

Additionally you can use the mixin in order to use this method where outside controllers and routes.

Importing the mixin is really simple:

import segmentMixin from 'ember-cli-segment/mixin';

The mixin can be applied to any Ember object.

Tracking Other Events

You will probabily need to track other events manually as well. We got you covered! Since we have an object called segment in your controllers and routes, it's really straightforward to do it.

Let's say that you need to track an event when the user submits an form in your router.

// File: app/routes/posts/new.js
import Ember from 'ember'

export default Ember.Route.extend({
  actions: {
    submit: function() {
      this.segment.trackEvent('Creates a new post');
    }
  }
});

trackEvent can receive additional properties as well:

this.segment.trackEvent('Creates a new post', { title: "Creating a Ember CLI application" });

All the parameters you can provide are: event, properties, options, callback in this order.

Identifying the User

We will automatically call identifyUser method from your application route everytime the URL changes. Inside this method, you should call segment.identifyUser passing the parameters that you want to send to Segment.

// File: app/routes/application.js
import Ember from 'ember';

export default Ember.Route.extend({
  identifyUser: function() {
    this.segment.identifyUser(1, { name: 'Josemar Luedke' });
  }
});

You should have in mind that you should make a conditional validation to check if the user is currently logged in. For example:

import Ember from 'ember';

export default Ember.Route.extend({
  identifyUser: function() {
    if (this.get('currentUser')) {
      this.segment.identifyUser(this.get('currentUser.id'), this.get('currentUser')));
    }
  }
});

All the parameters you can provide are: userId, traits, options, callback in this order.

aliasUser

Additionally we have an aliasUser method avaliable on segment.aliasUser that you can use when the user logs in in your application.

All the parameters you can provide are: userId, previousId, options, callback in this order.

Running Tests

ember test
ember test --server

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

Licensed under the MIT license.

acostajohn/ember-cli-segment