React-tracktor NPM

react-tracktor 🚜

<Tracktor /> is a React render prop, inspired by react-tracking, to gradually build tracking data down the render tree. At each level, all data is available from "above" while also passing it "down". It provides several ways to trigger tracking events.

Documentation

https://react-tracktor.netlify.com/

Caveats

This library only works with React versions that support hooks. That means 16.8.0 and up.
This library uses the IntersectionObserver Browser API under the hood. This feature might not work without a polyfill for older browsers.

Installation

yarn add react-tracktor

npm install react-tracktor

Example

import { Tracktor, TracktorProvider } from 'react-tracktor';

<TracktorProvider dispatcher={trackingData => console.log(trackingData)}>
  <Tracktor trackingData={{ page: 'README.md' }}>
    <main>
      <h2>README.md</h2>

      <Tracktor trackingData={{ section: 'example' }}>
        {({ trackEvent }) => (
          <section>
            <h3>
              <code>trackEvent</code>
            </h3>

            <button onClick={() => trackEvent({ button: 'hello' })}>Hello</button>

            <button onClick={() => trackEvent({ button: 'goodbye' })}>Goodbye</button>
          </section>
        )}
      </Tracktor>
    </main>
  </Tracktor>
</TracktorProvider>;

API

`<TracktorProvider />`

<TracktorProvider /> is required for <Tracktor /> to work. Every render-tree requires one <TracktorProvider />. This is also where the dispatcher, the callback that is called whenever a tracking event occurs, is defined.

Props

Name	Type	Default	Description
`dispatcher`	`(trackingData: object) => void`	`(trackingData) => console.log(trackingData)`	The `dispatcher` is a callback that is called on every tracking event and is responsible to process and forward the data for and to any analytics solution.

`<Tracktor />`

The <Tracktor /> render prop enables the consumer to gradually build tracking data. At each point at the render tree data from all <Tracktor /> render props above is available without the data "underneath".

Props

`<Tracktor />` Props

Name	Type	Default	Description
`children`	ReactNode \| `(value: TracktorRenderProp) => ReactNode`	required	If `children` is a function, it will act as a render prop that will be called with the content of `TracktorRenderProp`. If it's not a function, it will render the children.
`eventData`	object	`{}`	An object with tracking data that should be provided to the `dispatcher` when the `onClickWrapper` is fired or (when using the `intersectionRef` or `intersectionWrapper`) the component scrolls into view.
`intersectionOptions`	object	`{ triggerOnce: true }`	Options passed to the IntersectionObserver. See: https://github.com/thebuilder/react-intersection-observer#options
`trackingData`	object	`{}`	An object with data that should be used when tracking events from this component and all components further down the render tree.

`render` Props

Name	Type	Description
`createTrackEvent`	`(trackEventData: object) => () => void`	Higher-order-function to create a `trackEvent` function. Normally used in `onClick` props. Example: `<button onClick={createTrackEvent({ hello: 'world' })}>Click Me</button>}>`
`intersectionRef`	ReactRef	If used as a ref for a DOM element, a `trackEvent` will be fired with the the provided `eventData` when the refed element scrolls into view.
`intersectionWrapper`	`(WrappedComponent: ReactNode) => ReactNode)`	Can be used to wrap a component to inject an invisibile `<div />` which will have the `intersectionRef` and track on intersection.
`onClickWrapper`	`(trackEventData: object) => () => void`	Can be used to wrap a component's `onClick` prop, the returning function, also fires an `trackEvent`.
`trackEvent`	`(trackEventData: object) => void`	Function which fires an `trackEvent` with the provided data, merged with all previously provided `trackingData`.

`useTracktor()` 🎣

Since hooks can't provide context, useTracktor() is not a complete alternative to <Tracktor />, but provides the same functions as <Tracktor />'s render prop. It can also be provided with pageViewData to track page views. See <Tracktor /> & <PageView /> for more information.

Props

Name	Type	Default	Description
`eventData`	object	`{}`	An object with tracking data that should be provided to the `dispatcher` when the `onClickWrapper` is fired or (when using the `intersectionRef` or `intersectionWrapper`) the component scrolls into view.
`intersectionOptions`	object	`{ triggerOnce: true }`	Options passed to the IntersectionObserver. See: https://github.com/thebuilder/react-intersection-observer#options
`pageViewData`	object	`undefined`	An object with data that the `dispatcher` should be called with on page load.
`trackingData`	object	`{}`	An object with data that should be used when tracking events from this component and all components further down the render tree.

Returns

Name	Type	Description
`createTrackEvent`	`(trackEventData: object) => () => void`	Higher-order-function to create a `trackEvent` function. Normally used in `onClick` props. Example: `<button onClick={createTrackEvent({ hello: 'world' })}>Click Me</button>}>`
`intersectionRef`	ReactRef	If used as a ref for a DOM element, a `trackEvent` will be fired with the the provided `eventData` when the refed element scrolls into view.
`intersectionWrapper`	`(WrappedComponent: ReactNode) => ReactNode)`	Can be used to wrap a component to inject an invisibile `<div />` which will have the `intersectionRef` and track on intersection.
`onClickWrapper`	`(trackEventData: object) => () => void`	Can be used to wrap a component's `onClick` prop, the returning function, also fires an `trackEvent`.
`trackEvent`	`(trackEventData: object) => void`	Function which fires an `trackEvent` with the provided data, merged with all previously provided `trackingData`.

`<PageView />`

<PageView /> is used to fire an tracking event when the page loads. It needs to be wrapped in one top-level <TracktorProvider /> per render-tree which defines a dispatcher function that recieves the provided pageViewData and does something with it. See the <TracktorProvider /> section for details.