Migration Guide (v1 to v2)

For the most part most of your existing setup shouldn't have to change. There are breaking changes to the way targets, utils, and extensions are imported (and installed), and some breaking changes to the way targets are registered with createMiddleware and createMetaReducer. But, once that's sorted, you can enjoy all other enhancements incrementally at your own pace.
Everything's a Package
Redux Beacon has been split up into thirteen different npm packages! Each package is self contained and versioned in isolation.
Before
import { createMiddleware, createMetaReducer } from 'redux-beacon';
​
import { GoogleAnalytics } from 'redux-beacon/targets/google-analytics';
import { GoogleTagManager } from 'redux-beacon/targets/google-tag-manager';
import { Segment } from 'redux-beacon/targets/segment';
import { GoogleAnalytics, GoogleTagManager } from 'redux-beacon/targets/react-native';
import { CordovaGoogleAnalytics } from 'redux-beacon/targets/cordova-google-analytics';
​
import { logger } from 'redux-beacon/extensions/logger';
import { offlineWeb } from 'redux-beacon/extensions/offline-web';
import { offlineReactNative } from 'redux-beacon/extensions/offline-react-native';
import { ensure } from 'redux-beaocn/utils';
Now
import { createMiddleware, createMetaReducer } from 'redux-beacon';
​
import Amplitude from '@redux-beacon/amplitude';
import GoogleAnalytics from '@redux-beacon/google-analytics';
import GoogleAnalyticsGtag from '@redux-beacon/google-analytics-gtag';
import GoogleTagManager from '@redux-beacon/google-tag-manager';
import RnGoogleAnalytics from '@redux-beacon/react-native-google-analytics';
import RnGoogleTagManager from '@redux-beacon/react-native-google-tag-manager';
import Segment from '@redux-beacon/segment';
​
import logger from '@redux-beacon/logger';
import OfflineReactNative from '@redux-beacon/offline-react-native';
import OfflineWeb from '@redux-beacon/offline-web';
​
import combineEvents from '@redux-beacon/combine-events';
import ensure from '@redux-beacon/ensure';
Before, a breaking change to a single target, extension, or util would result in a major version bump for the entire package. Since most users stick to one target this could lead to confusion as there might be many version bumps without any real impact to a user.
Another hope for this change is continuous frequent releases. Going forward, the goal is to have an npm release with each new commit to master. Contributors should no longer have to wait for weeks or months for another major release to see their changes.
All Targets Must Be Invoked
You now have to invoke each target before passing them to createMiddleware or createMetaReducer. Some targets already behaved this way but now it's standard across all targets.
Before
import { MyTarget } from 'redux-beacon/targets/my-target';
​
const middleware = createMiddleware(eventsMap, MyTarget);
const metaReducer = createMetaReducer(eventsMap, MyTarget);
Now
import MyTarget from '@redux-beacon/my-target';
​
const middleware = createMiddleware(eventsMap, MyTarget());
const metaReducer = createMetaReducer(eventsMap, MyTarget());
This allows for targets to introduce settings or options without the need for a major version bump.
New Docs Site
There's a new Examples & Recipes page, revised Targets docs, revised Getting Started docs (Redux & ngrx), two new runnable examples (Redux & ngrx), and more. Take a look around!
Event Helpers
In v1 it wasn't always clear what you could and couldn't track. Now, each target's docs has an Event Definitions section that lists out all the events you can track.
Each time you want to track something, you:
Find the event definition for the thing you want to track.
Match the event definition to an action then fill in the event
definition.
Before
const event = action => ({
  hitType: 'event',
  customTrackerId: 'MY_CUSTOM_ID',
  eventCategory: 'Videos',
  eventAction: action.type,
}),
Now
import { trackEvent } from '@redux-beacon/google-analytics';
​
const event = trackEvent((action) => ({
  category: 'Videos',
  action: action.type,
}), 'MY_CUSTOM_ID');
Async Event Definitions
You can now return a Promise from an event definition. Here's an example of one way you could use this feature with the new debounceEvent util:
const videoSearched = debounceEvent(300,
 trackEvent(action => ({
   category: 'Videos',
   action: 'search',
   label: action.payload.searchTerm,
  }))
);
Events Mapper
Now you have the option to pass createMiddleware and createMetaReducer a function instead of an object to map action types to event definitions. Here's an example:
const pageView = trackPageView(action => ({
  page: action.payload.routerState.url,
}));
​
const videoLoadTime = trackTiming(action => ({
   category: 'Videos',
   action: 'load',
   value: action.payload.loadTime,
}));
​
const videoPlayed = trackEvent(() => ({
  category: 'Videos',
  action: 'play'
}));
​
const eventsMapper = (action) => {
  switch(action.type) {
    case 'ROUTE_CHANGED':
      return pageView;
    case 'VIDEO_PLAYED':
      return [videoLoadTime, videoPlayed]
    default:
      return [];
  }
}
And More...
There's a new target: Google Analytics (gtag.js) (#157)
The Google Analytics target now supports the enhanced eCommerce plugin (#139)
The Amplitude target now supports the amplitude-js (#160)
Events that are saved offline, are now purged as soon as the app regains connection (#168)
The React Native Google Analytics target now supports custom dimensions (#181)
The React Native Google Analytics target now supports purchase events (#189)
The Cordova Google Analytics target is no longer being maintained (#192)
FAQ
Notes on Offline Events
Last updated 1 year ago