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 ... 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(optionalIni)`

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

`interface PublicTrekker{ get context():Readonly 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{ dispatchEvent(event:PrivateTrekkerEvent):boolean

addCatchAllEventListener(handler: TrekkerEventHandler):void removeCatchAllEventListener(handler:TrekkerEventHandler):void

addEventListener(name:E, handler: TrekkerEventHandler):void removeEventListener(name:E, handler:TrekkerEventHandler):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(()=>({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 () }

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

const component = renderer.create(


      Root
      
        
           { / this button will klik with id:abc / }
        

        
          
            
               { / this button will klik with id:dfe, position:123 / }

,
  );


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.``