@sellics/react-tracking v0.0.5

react-tracking

This project was bootstrapped with Create React App.

• react-tracking
• Usage
  • Choose which Provider is right for your application
    • 1. With Router
    • 2. Without a Router
  • Initialization
  • Understanding the config object
  • [WIP] Event Tracking
  • Pageview Tracking
  • User Properties
  • Opt-Out
  • Available Scripts
    • yarn start
    • yarn docs

Usage

There are essentially two steps to setting up the react-tracking package in your project:

1. Initialize the TrackingProvider or RouteTrackingProvider
2. Wrap components to be tracked in the TrackingComponent

Choose which Provider is right for your application

There are two different Tracking Provider components depending on your application's route configuration. The difference between them is how page views are tracked internally.

1. With Router

The RouteTrackingProvider can be used to track route changes in applications using react-router. Route changes inside of the RouteTrackingProvider component will be tracked automatically in all initialized tools. The RouteTrackingProvider should be inside a Router component like the following example:

<BrowserRouter>
  <RouteTrackingProvider
    init={({ mixpanel, ga }) => {
      mixpanel.init({ token: MIXPANEL_TOKEN });
      ga.init({ id: GA_ID, options: { debug: true } });
    }}
  >
    ...
  </RouteTrackingProvider>
</BrowserRouter>

2. Without a Router

For applications which do not use react-router, route changes can be tracked using the TrackingProvider component. Route changes inside of the TrackingProvider will be tracked automatically in all initialized tools.

<TrackingProvider
  init={({ mixpanel, ga }) => {
    mixpanel.init({ token: MIXPANEL_TOKEN });
    ga.init({ id: GA_ID, options: { debug: true } });
  }}
>
  ...
</TrackingProvider>

Initialization

To initialize tracking in an application, the init property will need to be set in the root Tracking Provider. This is a react higher order component that defines tracking information about its child application. This is where the tracking tools are initialized and configuration is set.

Note: you only need to pass the necessary information for the type of tracking you want to enable.

It takes the following props:

• init: the initialization method containing tools to be used.
• config: A default configuration is already built into this package and explained more in the Understanding the config object section. The default configuration can be overwritten if needed.
• disableDefaultTracking: an optional flag that can be used to disable tracking events without explicit event names by default

 const MIXPANEL_TOKEN = process.env.MIXPANEL_TOKEN;
 const GA_ID = process.env.GA_ID;

 <TrackingProvider
    init={({ mixpanel, ga }) => {
      mixpanel.init({ token: MIXPANEL_TOKEN });
      ga.init({ id: GA_ID });
    }}
 >
  <Nav />
 </TrackingProvider>

Understanding the config object

The default config object contains most of the methods you will need for event tracking. These methods are used internally to perform actions in the correct format for each platform. When not in a production environment, events are logged to the console for debugging instead of being sent to either Mixpanel or Google Analytics.

This object can be overwritten by passing a new object into the config parameter of the TrackingProvider.

As of now the default config contains the following methods for both Mixpanel and Google Analytics:

• init: used to initialize the tracking platform of your choice. Depending on the tracking you're initializing, you'll need to pass either a token or account id.
• optOut: can be implemented to allow the user to opt out of the given tracking (see the Opt-Out section for more details)
• trackEvent: used to track an event along with an optional payload to the tracking platform
• trackRoute: can be used to manually track a page view by passing in the page route
• setUser: can be used to set user-specific properties (see the User Properties section for more details)

WIP Event Tracking

The TrackingComponent is a wrapper component that defines tracking information about its child. It expects an event parameter. This can be either an object or a function. If no event name is provided, the component will attempt to use the name of the child component as well as its position in the DOM (i.e. Buy|BUTTON|DIV|DIV|DIV|BODY) unless default tracking is disabled.

Additional properties of the event can be used to pass a payload to the tracking platform. Events are tracked internally using the trackEvent method defined in the config object.

Example:

<TrackingComponent
  event={(component) => ({
  name: `Clicked on ${component.props.children}`,
  category: 'transaction',
  action: 'click',
  value: 129301930,
})}
>
  <button>Buy</button>
</TrackingComponent>

The property event also receives a Function, which is expected to return an Object. The function receives two arguments, as described below:

1. Event Payload (Array) - Receives an array with the arguments passed to the event handler.

   • Example: If you wrap a Dropdown component that returns the selected item to the handler, that will be passed as well to the event payload in the event prop.

2. Event Info (Object) - Receives metadata from the tracked component.

   • Example: { props: ReactElement.props, type: ReactElement.type, action: 'onClick' }

Pageview Tracking

Routes that are wrapped in the RouteTrackingProvider or TrackingProvider will be automatically tracked. Routes are tracked internally using the trackRoute method.

User Properties

Properties specific to the user which will be set in local storage and therefore available across hits and sessions can be set using the setUser method. This will contain data such as account or permission level, company, or current logged in/out status of the user.

const { mixpanel, ga } = getTool(['mixpanel', 'ga']);

mixpanel.setUser({ userId: 'abc123', company: 'amazon' });
ga.setUser({ userId: 'abc123', company: 'amazon' });

Opt-Out

The optOut method can be called to prevent the user from being tracked by our third party user tracking.

const { mixpanel, ga } = getTool(['mixpanel', 'ga']);
const GA_ID = 'UA-000000-2';

mixpanel.optOut();
ga.optOut({ id: GA_ID });

Available Scripts

In the project directory, you can run:

yarn start

Runs the example app in the development mode. Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits. You will also see any lint errors in the console.

yarn docs

Generates the JSDdocs documentation in HTML form.