Ember CLI Segment provides an easy way to integrate your Ember application with Segment.com.
ember install ember-cli-segment
For compatibility with Ember v1.13, use version 2.1.0
Configuration options can be placed in your config/environment.js
under the segment
key.
You must provide your segment write key in order to correctly send events to segment.
ENV.segment = {
WRITE_KEY: 'your_segment_write_key'
};
ENV.segment = {
proxyDomain: 'https://segmentproxy.mydomain.com/'
};
To get logs when events are fired to segment, you must enable it. Default value is false
.
ENV.segment = {
LOG_EVENT_TRACKING: true
};
You can disable segment integration with enabled
option, however, segment scripts will still be inserted in your page. Default value is true
.
ENV.segment = {
enabled: false
};
When disabled, you can call tracking methods of segment
service but they will not call methods of
analytics.js
. In this way you can disable segment for development builds, for example. It can be
enabled later by calling enable()
method of segment
service. Segment's script still will be loaded
on startup. More about the enable()
method below.
There is an option available to disable the default page tracking on the application.didTransition event. If you do not disable this option then tracking events will by default be sent to Segment.
ENV.segment = {
defaultPageTrack: false
};
There is an option available to disable the default identify function on the application.didTransition event. If you do not disable this option then identify events will by default be sent to Segment.
ENV.segment = {
defaultIdentifyUser: false
};
The addon exposes a service that you can inject in routes, components and more.
// app/components/some-awesome-component.js
import Component from '@ember/component';
import { inject as service } from '@ember/service';
export default Component.extend({
segment: service()
});
You can wait for segment readyness:
// app/components/some-awesome-component.js
import Component from '@glimmer/component';
import { inject as service } from '@ember/service';
export default class MyComponent extends Component {
@service segment;
constructor() {
super(...arguments);
this.segment.ready(() => {
console.log('segment is ready');
});
}
}
Your router will automatically send a page view event to Segment using the method page
under window.analytics
everytime the URL changes.
If you want to include page category and name or modify some properties, you can define trackPageView
method
in application controller, like this:
// File: app/routes/application.js
import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
segment: service(),
trackPageView: function() {
this.get('segment').trackPageView(this.controller.currentPath);
}
});
If you need to call page tracking manually for some reason, you can do it using the following method in the service.
this.get('segment').trackPageView();
The method trackPageView
can receive a parameter that's the page url, if not provided it will fetch from window.location
.
You will probably need to track other events manually as well. We got you covered! Since we have the service, 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 Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
segment: service(),
actions: {
submit: function() {
this.get('segment').trackEvent('Creates a new post');
}
}
});
trackEvent
can receive additional properties as well:
this.get('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.
We will automatically call identifyUser
method from your application
route everytime the URL changes. Inside this method, you should call this.get('segment').identifyUser
passing the parameters that you want to send to Segment.
// File: app/routes/application.js
import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
segment: service(),
identifyUser: function() {
this.get('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 Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
segment: service(),
identifyUser: function() {
if (this.get('currentUser')) {
this.get('segment').identifyUser(
this.get('currentUser.id'),
this.get('currentUser')
);
}
}
});
All the parameters you can provide are: userId
, traits
, options
, callback
in this order.
Additionally we have an aliasUser
method avaliable on this.get('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.
You can add a user to groups manually.
// File: app/routes/application.js
import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
segment: service(),
identifyUser: function() {
this.get('segment').identifyUser(1, { name: 'Josemar Luedke' });
this.get('segment').group(2, {
name: 'Josemar Luedke Corp'
});
}
});
Middlewares allow developers to extend Analytics.js with custom code which runs on every event. This code has full access to the DOM and Browser API, and helps customers enrich and transform event payloads.
Analytics.js can be extended using two functions:
addSourceMiddleware(middleware)
addDestinationMiddleware(targetIntegration, [middleware1, middleware2, ...])
Source Middleware
allows you to manipulate the payload and filter events on a per-source basis, while Destination Middleware
allows this on a per destination basis. Middlewares run in the browser.
Using source middleware
var SMW1 = function({ payload, next, integrations }) {
payload.obj.pageTitle = document.title;
next(payload);
};
this.segment.addSourceMiddleware(SMW1);
Using destination middleware
var DMW1 = function({ payload, integration, next }) {
delete payload.obj.pageTitle;
next(payload);
};
analytics.addDestinationMiddleware('integrationA', [DMW1]);
You can disable/enable segment completely by calling disable()
/enable()
. In this case any calls to
tracking methods (like tracking events, page views, identifying users) will be ignored. These methods
have the same effect as enabled
option in configuration. Segment script still will be loaded on
startup.
You can disable or enable default page tracking (disableDefaultPageTrack()
/enableDefaultPageTrack()
) and
default identify calls (disableDefaultIdentifyUser()
/enableDefaultIdentifyUser()
)
This addon will not break fastBoot, however, it will only execute in the browser. Since we use window.analytics
to call segment and we don't have it in fastboot land, the addon will not be executed in fastboot.
ember test
ember test --server
See the Contributing guide for details.
Licensed under the MIT license.