My amazing app

# Redux Segment

_Segment.io analytics integration for redux._ [![CircleCI](https://img.shields.io/circleci/project/rangle/redux-segment.svg)](https://circleci.com/gh/rangle/redux-segment) [![npm](https://img.shields.io/npm/v/redux-segment.svg)](https://www.npmjs.com/package/redux-segment) [![GitHub license](https://img.shields.io/github/license/rangle/redux-segment.svg)](https://github.com/rangle/redux-segment/blob/master/LICENSE) ``` 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](https://github.com/rackt/react-router-redux) ✝: >=2.1.0 < 5 - [redux-router](https://github.com/acdlite/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](https://github.com/rackt/redux/blob/master/docs/basics/Actions.md) you care about: ```js export function addTodo(text) { return { type: types.ADD_TODO, payload: { text, }, } } ``` Just tell the middleware you also want it tracked: ```js 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: ```js export function addTodo(payload) { return { type: types.ADD_TODO, payload, meta: { analytics: EventTypes.track, }, } } ``` That's all! :smile: ### What is Segment? [Segment](https://segment.com) 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](https://twitter.com/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** ```js 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). ```js 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); ``` **2. Copy the segment snippet into the header of your site** ```html My amazing app ... ``` **3. You're done! You can now start specifying events at your heart's content.** ## Usage ### Spec API - [**Identify**](#identify) - [**Page**](#page) - [**Track**](#track) - [**Alias**](#alias) - [**Group**](#group) ### Overview In Redux Segment, events are declared on the action they represent. For example: ```js 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 \* (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](https://segment.com/docs/spec/) for more details. *eventPayload \* – The fields associated with the event. Each event has a few [common fields](https://segment.com/docs/spec/common/#structure). 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](https://segment.com/docs/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 \* – The database ID of the user. For anonymous visitors, an `anonymousId` will be automatically generated so this field can be omitted. *traits \* – 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` \ - `age` \ - `avatar` \ - `birthday` \ - `createdAt` \ - `description` \ - `email` \ - `firstName` \ - `gender` \ - `id` \ - `lastName` \ - `name` \ - `phone` \ - `title` \ - `username` \ - `website` \ Traits are also useful for such things as marking users as having seen a particular A/B test variation. *options \* – A map of [common fields](https://segment.com/docs/spec/common/#structure). 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](https://segment.com/docs/spec/page/) **Type:** `EventTypes.page` **Payload Fields:** *name \* – The name of the page (e.g. 'Home'). *category \* – 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 \* – 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 \* – A map of [common fields](https://segment.com/docs/spec/common/#structure). 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](https://segment.com/docs/spec/track/) **Type:** `EventTypes.track` **Payload Fields:** *event \* – 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](https://segment.com/docs/spec/ab-testing) - `Experiment Viewed` > This event should be sent every time a customer sees a variation of an > active A/B Test. [Ecommerce Events](https://segment.com/docs/spec/ecommerce) - `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](https://github.com/acdlite/flux-standard-action). *properties \* – 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` \ (reserved for future use) - `revenue` \ - `currency` \ - `value` \ (useful for events with intrinsic, but not monetary, value) [A/B Testing Events](https://segment.com/docs/spec/ab-testing) `Experiment Viewed` - `experiment_id` \ - `experiment_name` \ - `variation_id` \ - `variation_name` \ [Ecommerce Events](https://segment.com/docs/spec/ecommerce) `Viewed Product Category` - `category` \ `Viewed Product` - `id`\* \ - `sku`\* \ - `name` \ - `price` \ - `category` \ * `id` and `sku` don't have to be different, but they can. `Added Product` / `Removed Product` - `id` \ - `sku` \ - `name` \ - `price` \ - `quantity` \ - `category` \ `Completed Order` - `orderId` \ - `total` \ - `revenue` \ - `shipping` \ - `tax` \ - `discount` \ - `coupon` \ - `currency` \ - `products` \ 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 \* – A map of [common fields](https://segment.com/docs/spec/common/#structure). 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](https://segment.com/docs/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](https://segment.com/docs/integrations/kissmetrics#alias), [Mixpanel](https://segment.com/docs/integrations/mixpanel#alias), [Trak](https://segment.com/docs/integrations/trak.io/#alias) and [Vero](https://segment.com/docs/integrations/vero#alias).** **Type:** `EventTypes.alias` **Payload Fields:** *userId \* (required) – The new database ID you want associated with the user. *previousId \* (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 \* – A map of [common fields](https://segment.com/docs/spec/common/#structure). 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](https://segment.com/docs/spec/group) **Type:** `EventTypes.group` **Payload Fields:** *groupId \* (required) – The new database ID of the group you want associated with the (identified or anonymous) user. *traits \* – 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` \ - `avatar` \ - `createdAt` \ - `description` \ - `email` \ - `employees` \ - `id` \ - `industry` \ - `name` \ - `phone` \ - `website` \ *options \* – A map of [common fields](https://segment.com/docs/spec/common/#structure). 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](https://segment.com/docs/sources/website/analytics.js/#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`: ```js 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](https://github.com/rangle/redux-segment/issues/new). ## License Code and documentation copyright 2015-2016 Rangle.io. Code released under the [MIT license](./LICENSE). Docs released under Creative Commons.

redux-segment

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past