Redux middleware for analytics and tracking with an awesome API. Comes with Google Analytics support, but it's very easy to write your own adoptions!
We want an easy and flexible way to add analytics to our Redux apps without
having to rewrite our action creators or add a lot of boilerplate to every
action. With redux-insights
you attach our middleware and use helper functions
to add rich analytics with minimal effort, and a tiny footprint.
yarn add redux-insights
or
npm install --save redux-insights
import { applyMiddleware, createStore } from "redux";
import { createInsightsMiddleware, plugins, presets } from "redux-insights";
const insightsMiddleware = createInsightsMiddleware([
plugins.googleAnalytics({ trackingID: "UA-XXXXXXXX-X" })
], [
presets.reactRouter
]);
const store = createStore(
reducer,
initialState,
applyMiddleware(insightsMiddleware)
);
Set up Redux store to use insights middleware with Google Analytics and
react-router-redux
actions.
import { track } from "redux-insights";
export const myAction = payload => ({
type: "MY_ACTION",
payload,
insights: track("my action was triggered")
});
Add event tracking to your own action by adding the insights
key to your
action creator.
Insights is an array of insight objects, or just a single insight object.
import { track, page } from "redux-insights";
const validInsights = track("single insight");
const alsoValidInsights = [
track("first insight"),
page("second insight")
];
An insight object consist of the following keys:
type
(String): The type of the insight. See types.event
(String): A string describing the event. E.g. "change user name".data
Optional: (Any): Data to pass with the insight. Can be of any type that is JSON-serializable. Defaults tonull
.
Creates a Redux middleware that passes all actions with an insights key and those defined in globalInsights through the plugins.
-
plugins
(Array): An array of plugins that parses the insights. The package includes the following plugins, that can be imported viaimport { plugins } from "redux-insights"
:- Google Analytics
-
globalInsights
Optional: (Array/Object): An array of insight maps, or just an insight map. An insight map is an object with keys being action types and values being insights, or insight creators. This is used to add insights to actions that are triggered from somewhere else - for examplereact-router-redux
actions. We actually provide apreset
forreact-router-redux
that you access like this:
import { createInsightsMiddleware, presets, track } from "redux-insights";
const plugins = [
// example: Google Analytics
];
const globalInsights = [
presets.reactRouter,
// custom insights map
{
MY_ACTION: track("my custom action")
}
];
const insightsMiddleware = createInsightsMiddleware([plugins], globalInsights);
You might find yourself in a spot where you have to select data from the action, to attach to the insight. In order to do this, you can supply an insight creator function. It will be called when the action is handled in the middleware.
import { track } from "redux-insights";
const globalInsights = [
{ MY_ACTION: (action, getState) => track("my event", action.payload.data) }
]
As props you receive the action itself, as well as the getState
function
provided by the store, in case you need to access other data.
Creates a factory for creating insights of the provided type. Is used internally
to create the track
, page
and identify
helpers.
type
(String): A unique identifier for the insight type. See standard types.
Creates an insight of the type INSIGHT_TRACK
/INSIGHT_PAGE
/INSIGHT_IDENTIFY
.
event
(String): A string describing the event you want an insight of, e.g. "created new support ticket" or "change" (for the page type).data
Optional: (Any): Data to pass with the insight. Can be of any type that is JSON-serializable. Defaults tonull
.
An object containing the default insight types which are:
INSIGHT_TRACK
INSIGHT_PAGE
INSIGHT_IDENTIFY
These are used when you want to create your own plugin.
A higher-order function you can use to wrap action creators and add insights to
the actions generated by them. This makes migrating to redux-insights
a bliss!
Takes insights or an insight creator as argument, see Insight creators above.
Plugins are used to parse the insights and actually send the data to your analytics provider.
The following plugins are included in redux-insights
and can be used out-of-the-box:
- Google Analytics
We provide a very intuitive Plugin API, so don't be afraid to write your own plugins!
Presets are suggested insight maps that makes it easy to use redux-insights
together with other libraries. Just add the preset to your globalInsights
array
and you're good to go!
redux-insights
uses jest
for testing.
Run yarn test
or npm test
to run tests.
ISC
- @alfredringstad - Main development
- @mrlundis - Ideas and feedback