npm install 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.
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.
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 WithTrekkerContext to add variables to your context.
Using the hook useTrekker 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.
``