React-Trekker

Strongly typed simple decoupled integration of trackers.

Two steps:

1. React components only register "contextual information" and emit events. No need to think about what GA dimensions to set, or what categories and labels. Just store context information like, "this is the search page body", "this is the 3rd card in a list" like this <WithTrekkerContext context={{card:13}}> ...</WithTrekkerContext> and all events coming from this part of the tree will have this context information.

2. Handle events At another place you register your event listeners to send the information to your trackers, Google Analytics, Facebook, whatever you have. Events contain all context information available to them, so you know the button clicked was inside a card on the search-page for product X and was the 3rd card in a row.

Warning

All top level fields in the context object that are arrays are merged instead of overriden. At NODE_ENV = development (or empty), warnings will be console.warn-logged for overrideing values. See unit test for details.

how to use

Step 1:

import {TrekkerProvider, useTrekker, WithTrekkerContext, TrekkerHoc, bus} from 'react-trekker'

// or using strong typing

import {trekkerFactory} from 'react-trekker'
const {TrekkerProvider, useTrekker, `WithTrekkerContext`, TrekkerHoc, bus} = trekkerFactory<CustomContext, CustomEventNames>(optionalIni)

Now start top level with your TrekkerProvider to initiate the context, and use WithTrekkerContext to add variables to your context. Using the hook useTrekker you can retrieve an instance of the Trekker:

 interface PublicTrekker<CustomContext,CustomEventTypes>{
    get context():Readonly<CustomContext>
    event(name:CustomEventTypes, extra?:CustomContext):void
  }

You can subscribe to these events to send them to your actual trackers using the bus of type TrekkerEventBus

interface TrekkerEventBus<CustomContext,CustomEventTypes>{
  dispatchEvent(event:PrivateTrekkerEvent<CustomContext, CustomEventTypes>):boolean

  addCatchAllEventListener(handler: TrekkerEventHandler<CustomContext, CustomEventTypes>):void
  removeCatchAllEventListener(handler:TrekkerEventHandler<CustomContext, CustomEventTypes>):void

  addEventListener(name:E, handler: TrekkerEventHandler<CustomContext, CustomEventTypes>):void
  removeEventListener(name:E, handler:TrekkerEventHandler<CustomContext, CustomEventTypes>):void
}

Philosophy

While building a UI you just want to think about the current components, not its place inside the entire tree. By implicitly passing along contextual information, simple components dont have to know their place inside the world, which means you can just focus on making a good and simple component.

In order to do tracking well you need to know what choices the user is making and what choices are not made, by adding context information about this to events, you can reason about the users behaviour.

For example, "component-in-view" events combined with "clicked-on-this" events, when combined in analytics provide information about what items the user had in view but did not click as well as what they did click.

By combining strong typing with decoupling of the trackers from your UI code, its a lot simpler to do analytics correct without worrying about it too much.

Example

This example here demos how to do strong typing, but you can also just straight up import {TrekkerProvider, useTrekker, WithTrekkerContext, TrekkerHoc, bus} from 'react-trekker' and skip the strong typing

test('Trekker adds context to events, with strong typing', async () => {
  const {TrekkerProvider, useTrekker, WithTrekkerContext, TrekkerHoc, bus} = trekkerFactory<CustomContext, CustomEventNames>(()=>({url: location.href}))

  const clicks:any[] = []
  // its recommended to do this part somwhere else in real life
  bus.addEventListener('klik',(evt) =>{
    clicks.push(evt)
  })
  const ButtonWithEvent = () =>{
    const trekker = useTrekker()
    return (<button className={"button"} onClick={() => trekker.event("klik")}>
      click
    </button>)
  }

  const HocComponent = TrekkerHoc({id:'abc'})(() => (<ButtonWithEvent />))

  const component = renderer.create(
    <div>
      Root
      <TrekkerProvider>
        <div>
          <HocComponent /> { /* this button will klik with id:abc */ }
        </div>
        <WithTrekkerContext context={{id:dfe}}>
          <div>
            <WithTrekkerContext context={{position:123}}>
              <ButtonWithEvent /> { /* this button will klik with id:dfe, position:123 */ }
            </WithTrekkerContext>
          </div>
        </WithTrekkerContext>
      </TrekkerProvider>
    </div>,
  );

test coverage

$ jest
 PASS  src/subscribers/__tests__/subscribers.test.ts
 PASS  src/__tests__/trekker-hooks-custom.test.tsx (5.061 s)
 PASS  src/__tests__/trekker-hooks.test.tsx (5.412 s)
 PASS  src/__tests__/bus.test.ts (6.045 s)
-----------------|---------|----------|---------|---------|-------------------
File             | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-----------------|---------|----------|---------|---------|-------------------
All files        |     100 |    71.42 |     100 |     100 |
 src             |     100 |       50 |     100 |     100 |
  bus.ts         |     100 |      100 |     100 |     100 |
  factory.tsx    |     100 |       50 |     100 |     100 | 23
  index.tsx      |     100 |      100 |     100 |     100 |
  trekker.ts     |     100 |       50 |     100 |     100 | 15
  types.ts       |     100 |      100 |     100 |     100 |
 src/subscribers |     100 |      100 |     100 |     100 |
  fbq.ts         |     100 |      100 |     100 |     100 |
  ga.ts          |     100 |      100 |     100 |     100 |
  gtag.ts        |     100 |      100 |     100 |     100 |
-----------------|---------|----------|---------|---------|-------------------

Test Suites: 4 passed, 4 total
Tests:       9 passed, 9 total
Snapshots:   0 total
Time:        10.946 s
Ran all test suites.