davincho/react-tracking

Agnostic tracking primitives for your React Application

Purpose

This library provides tracking primitives for your React Applcation. It is agnostic to which tracking library you are using.

Installation

1. Run yarn add @dvnch/react-tracking

Usage

1. Wrap you application with a provider:

import { TrackingProvider } from '@dvnch/react-tracking';

const App = () => {
  return (
    <TrackingProvider
      onEventTracked={(eventData) => {
        // Consume event data
      }}
    >
      <App />
    </TrackingProvider>
  );
};

2. In a component you want to trigger an event, use the provded hook:

import { useTracking } from '@dvnch/react-tracking';

const Button = () => {
  const { trackEvent } = useTracking();

  return (
    <button
      onClick={() => {
        trackEvent({
          label: 'button'
        });
      }}
    >
      ClickMe
    </button>
  );
};

3. If you want to add a specific value to all tracked events happening within the child tree, you can leverage the TrackingSection component:

import {
  TrackingSection,
  TrackingProvider,
  useTracking
} from '@dvnch/react-tracking';

const App = () => {
  return (
    <TrackingProvider
      onEventTracked={(eventData) => {
        // Prints { category: 'foo', label: 'button' }
        console.log(eventData);
      }}
    >
      <TrackingSection category="foo">
        <Button />
      </TrackingSection>
    </TrackingProvider>
  );
};

const Button = () => {
  const { trackEvent } = useTracking();

  return (
    <button
      onClick={() => {
        trackEvent({
          label: 'button'
        });
      }}
    >
      ClickMe
    </button>
  );
};

TypeScript

If you want to specify the shape of events you want to allow through your application you can use the factory function which is used internally as well.

Create a new file (for instance Tracking.tsx) and paste the following:

// Tracking.tsx
interface YourCustomEventyPayload {
  label: string;
  category: string;
}

export const {
  useTracking,
  TrackingProvider,
  TrackingSection
} = createTrackingProvider<YourCustomEventyPayload>();

In your consuming components, instead of referencing the library directly you consume the primitives provided by Tracking.tsx:

import { useTracking, TrackingSection, TrackingProvider } from './Tracking';

const App = () => {
  return (
    <TrackingProvider
      onEventTracked={() => {
        // Consume event
      }}
    >
      {/* Will throw a Typescript error  */}
      <TrackingSection foor="bar">
        <Button />
      </TrackingSection>
    </TrackingProvider>
  );
};

const Button = () => {
  const { trackEvent } = useTracking();

  return (
    <div>
      <button
        onClick={() => {
          trackEvent({
            label: 'TrackMe!'
          });

          // Will throw a typescript error!
          trackEvent({
            someting: 'foo'
          });
        }}
      >
        TrackMe!
      </button>
    </div>
  );
};