Redux Segment

Segment.io analytics integration for redux.

npm install --save redux-segment

Features

• Send your data to over 100 apps with the flip of a switch (e.g. Google Analytics, Mixpanel, Optimizely, Facebook Ads, Slack, Sentry, and many more...).
  • You only need one snippet and you can turn integrations on and off whenever you want.
• Simultaneously load customer data into your data warehouse in minutes.
  • Query raw data with SQL
  • Analyze your products across web and mobile.
  • No API layer, no queue, no transform, no batch, no load...and no infrastructure maintenance costs
• Out-of-the-box support for popular routers:
  • react-router-redux ✝: >=2.1.0 < 5
  • redux-router: ^1.0.3
• Support for all key Segment specs:
  • Identify
  • Page
  • Track
  • Group
  • Alias

✝ Recommended router. You can also trigger page views manually.

Motivation

Redux Segment middleware allows you to draw deep and rich analytics from your Redux application with minimal configuration. You are already specifying the actions you care about:

export function addTodo(text) {
  return {
    type: types.ADD_TODO,
    payload: {
      text,
    },
  }
}

Just tell the middleware you also want it tracked:

export function addTodo(text) {
  return {
    type: types.ADD_TODO,
    payload: {
      text,
    },
    meta: {
      analytics: {
        eventType: EventTypes.track,
        eventPayload: {
          event: types.ADD_TODO,
          properties: {
            text
          },
        },
      },
    },
  }
}

Or if you want to save keystrokes:

export function addTodo(payload) {
  return {
    type: types.ADD_TODO,
    payload,
    meta: {
      analytics: EventTypes.track,
    },
  }
}

That's all! :smile:

What is Segment?

Segment is a platform that allows you to collect your analytics data with one API and send it to hundreds of tools (e.g. Google Analytics, Mixpanel, Slack, etc...) or data warehousing. Crucially, it also allows you to own your data in raw format.

Can I just write one line that tells the middleware to track everything?

No. This is tempting to do, especially in Redux where your application state is small and centralized and changes are explicit. You should, however, resist the temptation. This constraint is core to the design philosophy of Redux Segment.

Analytics is about learning

-- @segment

Tracking everything, in many cases, is equivalent to tracking nothing at all. In practice, we are forced to think about analytics differently.

The Lean Startup methodology advocates applying a scientific approach to product development. The rationale, as it goes, is that the faster a team learns, the more likely they are to succeed. The process occurs in roughly three phases:

1. Build (idea -> code)

   In phase 1, the team builds something they think their users want. The result is an experimental feature.

2. Measure (code -> data/analytics)

   In phase 2, the team collects data on how users are reacting to the feature. This is the experiment.

3. Learn (data/analytics -> ideas)

   In phase 3, the team uses the data collected to determine if the experiment was a success or not. They can then use what they learned to drive more ideas.

And so the cycle continues...

Redux Segment is designed to allow you to measure faster. First, choose what you want to learn. Build it. Then, determine how you're going to measure it. And finally, collect the result.

You can, of course, still track all actions if you want by explictly marking each one.

Installation

npm install --save redux-segment

1. Create and apply the tracker

import { applyMiddleware, createStore, compose } from 'redux';
import { reduxReactRouter } from 'redux-router'
import createHistory from 'history/lib/createBrowserHistory'
import routes from '../routes'
import thunk from 'redux-thunk'
import api from '../middleware/api'
import rootReducer from '../reducers'
import { createTracker } from 'redux-segment';

const tracker = createTracker();                                   // Create the tracker...

const finalCreateStore = compose(
  applyMiddleware(thunk, api, tracker),                            // and then apply it!
  reduxReactRouter({ routes, createHistory })
)(createStore)

export default function configureStore(initialState) {
  return finalCreateStore(rootReducer, initialState)
}

Note: Make sure to include the tracker after thunk or promise middleware so that it sees actual actions.

2. Optional, Access Third Party Redux Libraries Provide an optional config object to createTracker(customMapper) to map third party Redux library ActionTypes to Segment EventTypes and replace out-of-the-box support (if necessary). Note that the mappings can be either simple EventTypes, or mappings to functions if access to state and action is required, that should return single or array of a state information and EventType object(s).

import { EventTypes } from 'redux-segment'
const customMapper = {
  mapper: {
    '@@router/CALL_HISTORY_LOCATION': EventTypes.page,
    '@@router/UPDATE_LOCATION': EventTypes.page,
    '@@reduxReactRouter/replaceRoutes': (getState, action) => {
      return {
        eventType: EventTypes.page,
        eventPayload: {
            name: ActionType.ADD_TODO,
            text: getState().text,
        }
      }
    },
    'CUSTOM_LOGOUT_ACTION': (getState, action) => {
      return [{
        eventType: EventTypes.reset,
      }, {
        eventType: EventTypes.page,
      }]
    }
  }
}

const tracker = createTracker(customMapper);

Note: You can skip the default mapping by setting the skipDefaultMapping property as true in the config object you pass to createTracker(customMapper).

const customMapper = {
  skipDefaultMapping: true,
  mapper: {
    ... // add custom mappings
  }
};

const tracker = createTracker(customMapper);

2. Copy the segment snippet into the header of your site

<head>
  <title>My amazing app</title>
  ...
  <script type="text/javascript">
    !function(){var
  analytics=window.analytics=window.analytics||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;
  analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","page","once","off","on"];analytics.factory=function(t){return
  function(){var
  e=Array.prototype.slice.call(arguments);e.unshift(t);analytics.push(e);return
  analytics}};for(var t=0;t<analytics.methods.length;t++){var
  e=analytics.methods[t];analytics[e]=analytics.factory(e)}analytics.load=function(t){var
  e=document.createElement("script");e.type="text/javascript";e.async=!0;e.src=("https:"===document.location.protocol?"https://":"http://")+"cdn.segment.com/analytics.js/v1/"+t+"/analytics.min.js";var
  n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n)};analytics.SNIPPET_VERSION="3.1.0";
    analytics.load("YOUR_WRITE_KEY");
    // Make sure to remove any calls to `analytics.page()`!
    }}();
  </script>
</head>

3. You're done! You can now start specifying events at your heart's content.

Usage

Spec API

• Identify
• Page
• Track
• Alias
• Group

Overview

In Redux Segment, events are declared on the action they represent. For example:

import { EventTypes } from 'redux-segment';

function buy(cart, subtotal, tax, total) {
  return {
    type: 'CHECKOUT',
    payload: {
      cart,
      subtotal,
      tax,
      total,
    },
    meta: {
      analytics: {
        eventType: EventTypes.track,
      },
    },
  };
}

// or the short form...

function openCart() {
  return {
    type: 'OPEN_CART',
    meta: {
      analytics: EventTypes.track,
    },
  };
}

Event specifications are attached to the analytics property of the action's meta key. When using the short-hand, required keys are inferred.

Common Properties:

eventType <string> (required) – The type of event to emit. Each type represents some distinct semantic information about your customer. Available types:

• EventTypes.identify: who is the customer?
• EventTypes.page: what web page are they on?
• EventTypes.track: what are they doing?
• EventTypes.group: what account or organization are they part of?
• EventTypes.alias: what was their past identity?

See the Segment Spec for more details.

eventPayload <Object> – The fields associated with the event. Each event has a few common fields. The rest are covered below, on a type-by-type basis.

Identify

The identify call ties a customer and their actions to a recognizable ID and traits like their email, name, etc. Spec: Identify

Note: You don't need an identify action for anonymous visits. It will be inferred for you so you can ahead and use page or track without worry.

Type: EventTypes.identify

Payload Fields:

userId <string> – The database ID of the user. For anonymous visitors, an anonymousId will be automatically generated so this field can be omitted.

traits <Object> – A map of attributes about the user. These are completely at your discretion but common ones include email and name. If you don't provide a userId, the traits will be attributed to the currently identified users (whether anonymous or not). The following traits are reserved and have standardized meaning:

• address <Object>
• age <number>
• avatar <string>
• birthday <Date>
• createdAt <Date>
• description <string>
• email <string>
• firstName <string>
• gender <string>
• id <string>
• lastName <string>
• name <string>
• phone <string>
• title <string>
• username <string>
• website <string>

Traits are also useful for such things as marking users as having seen a particular A/B test variation.

options <Object> – A map of common fields. This can be used to selectively enable or disable certain integrations or set anonymousId or userId on an ad-hoc basis.

Page

The page call lets you record whenever a user sees a page of your website, along with any properties about the page. Spec: Page

Type: EventTypes.page

Payload Fields:

name <string> – The name of the page (e.g. 'Home').

category <string> – The category of the page. This is used where page names live under a broader category (e.g. 'Products'). Note: If you specify a category, you must also provide a name.

properties <Object> – A map of page properties. The following properties are reserved and have standardized meaning:

• url
• title
• referrer
• path
• name
• search

If not explicitly specified, the above properties are implied. You can also provide your own custom properties, if you want.

options <Object> – A map of common fields. This can be used to selectively enable or disable certain intergrations or set anonymousId or userId on an ad-hoc basis. More routinely, it is used to "backdate" events by setting the timestamp key to when the event actually occurred (as opposed to when the action was dispatched). This is useful for cases where an action may be triggered after a significant wait (e.g. setTimeout, callback, animations, etc...) and you want to capture the time of human action instead of, say, the time at which that action was confirmed or some data was persisted.

Track

The track call is how you record any actions your users perform, along with any properties that describe the action. Spec: Track

Type: EventTypes.track

Payload Fields:

event <string> – The name of the event you’re tracking. This field is required but if you don't explicitly provide one, it will be populated by the type value of the action*. It's recommended that you make event names human-readable and (hopefully) instantly recognizable. It's further recommended that these names be built from a past-tense verb and a noun (e.g. 'Bought Merchandise', 'Opened Cart', 'Favorited Product', etc...). The following event names are reserved and have standardized meaning:

A/B Testing Events

• Experiment Viewed

This event should be sent every time a customer sees a variation of an active A/B Test.

Ecommerce Events

• Viewed Product Category

This event fires when a visitor views a product category. That view might happen on a page or modal.

• Viewed Product

This event fires when a visitor views a product. That view might happen on a page or preview modal.

• Added Product / Removed Product

Fire the 'Added Product' event when a visitor adds a product to their shopping cart and the 'Removed Product' event when a visitor removes a product from their shopping cart.

• Completed Order

The final step is to record a 'Completed Order' event when people complete your checkout process.

* As of Redux 3.x, all actions MUST define a type property as per FSA.

properties <Object> – A map of event properties. Properties are extra pieces of information tied to the event being tracked. They can help provide additional context later when analyzing the events, and in doing so, provide a more complete picture of what your users are doing. The following properties are reserved and have standardized meaning:

• name <string> (reserved for future use)
• revenue <number>
• currency <string>
• value <number> (useful for events with intrinsic, but not monetary, value)

A/B Testing Events

Experiment Viewed

• experiment_id <string>
• experiment_name <string>
• variation_id <string>
• variation_name <string>

Ecommerce Events

Viewed Product Category

• category <string>

Viewed Product

• id* <string>
• sku* <string>
• name <string>
• price <string>
• category <string>

• id and sku don't have to be different, but they can.

Added Product / Removed Product

• id <string>
• sku <string>
• name <string>
• price <string>
• quantity <string>
• category <string>

Completed Order

• orderId <string>
• total <number>
• revenue <number>
• shipping <number>
• tax <number>
• discount <number>
• coupon <string>
• currency <string>
• products <Array>

Be sure to include all products in the cart as event properties, with the same properties as listed above (id, sku, name, price, quantity and category)

options <Object> – A map of common fields. This can be used to selectively enable or disable certain integrations or set anonymousId or userId on an ad-hoc basis.

Alias

The alias method is used to merge two user identities, effectively connecting two sets of user data as one. Spec: Alias

It's important to note that most integrations will automatically alias anonymous visitors the first time you dispatch an EventTypes.identify action. As a result, this event is only needed to manage identities in some integrations (e.g. KISSmetrics, Mixpanel, Trak and Vero.

Type: EventTypes.alias

Payload Fields:

userId <string> (required) – The new database ID you want associated with the user.

previousId <string> (required) – The old ID of the user. If omitted, it's assumed to be the currently identified user’s ID (in the case of anonymous visitors, this is the auto-generated anonymousId).

options <Object> – A map of common fields. This can be used to selectively enable or disable certain integrations or set anonymousId or userId on an ad-hoc basis.

Group

The group API call is how you associate an individual user with a group—be it a company, organization, account, project, team or whatever other crazy name you came up with for the same concept! Spec: Group

Type: EventTypes.group

Payload Fields:

groupId <string> (required) – The new database ID of the group you want associated with the (identified or anonymous) user.

traits <Object> – A map of attributes about the group. These are completely at your discretion but common ones include employees and website. The following traits are reserved and have standardized meaning:

• address <Object>
• avatar <string>
• createdAt <Date>
• description <string>
• email <string>
• employees <string>
• id <string>
• industry <string>
• name <string>
• phone <string>
• website <string>

options <Object> – A map of common fields. This can be used to selectively enable or disable certain integrations or set anonymousId or userId on an ad-hoc basis.

Reset / Logout

Calling reset will reset the id, including anonymousId, and clear traits for the currently identified user and group. Docs: Reset / Logout

Type: EventTypes.reset

Payload Fields: The reset event takes no payload fields.

Emitting more than one event

If you want to emit more than one analytics events/calls from a single redux action, you can provide an array as the value of meta.analytics:

function buy(cart, subtotal, tax, total) {
  return {
    type: 'CHECKOUT',
    payload: {
      cart,
      subtotal,
      tax,
      total,
    },
    meta: {
      analytics: [
        {
          eventType: EventTypes.track,
        },
        {
          eventType: EventTypes.track,
          eventPayload: {
            event: 'Checked Out',
          },
        },
      ],
    },
  };
}

This will result in two calls to track with different event names, but you can use any combination of track/identify/group etc.

Support

We're always around to help. If you run into any issues, want advice or simply have a question, please open an issue.

License

Code and documentation copyright 2015-2016 Rangle.io. Code released under the MIT license. Docs released under Creative Commons.