bastiankistner / react-tracktor

A React render prop to gradually build tracking data down the render tree.

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

or

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.

Props

Name	Type	Default	Description
pageViewData	object	required	An object with data that the dispatcher should be called with on page load.

Alternatives

react-tracking is what inspired this approach to tracking. Use it for more advanced use cases.

Development

This project was bootstrapped with TSDX.