React SDK

The React SDK leverages React Context Providers for mapping JSX Elements and Components to the open analytics taxonomy.

APIs

Tracking a Component means wrapping it in the correct Location Context and, if interactive, capturing its events.

There are three ways of doing so:

TrackedElements

High level Components designed to match HTML Semantic Elements. These components are the least effort to instrument; simply swap the original HTML Semantic Element with their Tracked Element counterparts.

// Basic HTML button tag
<button onClick={handleClick}>
Click Me!
</button>

// TrackedButton equivalent: a <button> wrapped in PressableContext tracking PressEvent on click
<TrackedButton onClick={handleClick}>
Click Me!
</TrackedButton>

TrackedContexts

The underlying building blocks of TrackedElements. While still providing automatic Location wrapping and event tracking, they allow specifying a Component to wrap around.

Much like Tracked Elements, swapping the original component, or HTML tag, with a Tracked Context is all that's needed to instrument it.

Currently, only HTML-like components are supported.

// A generic MenuItem component that renders an html-like component, eg a <li>, <button> 
<MenuItem onClick={handleMenuClick}>
Click Me!
</MenuItem>

// TrackedContext equivalent
<TrackedPressableContext Component={MenuItem} onClick={handleMenuClick}>
Do It!
</TrackedPressableContext>
info

Some TrackedContext may require more attributes. For example TrackedLinkContext requires a href to be specified.

Check out the How to track interactions with Links guide for more info and examples.

Location Wrappers

Wrap their children in a Location Context. Tracked Elements and Tracked Contexts internally use Location Wrappers automatically.

Location Wrappers don't track interactions, instead they are usually used to either enrich Locations or to instrument custom or generic components in combination with Event Trackers.

// The same interaction appears multiple times on the same page 
<div>
<Link to={'/contact'}>Contact us</Link>
...
<Link to={'/contact'}>Contact us</Link>
...
<Link to={'/contact'}>Contact us</Link>
</div>

// ContentContextWrapper can be used to enrich and deduplicate the location of these interactions
<div>
<ContentContextWrapper id={'hero'}>
<Link to={'/contact'}>Contact us</Link>
</ContentContextWrapper>
...
<ContentContextWrapper id={'body'}>
<Link to={'/contact'}>Contact us</Link>
</ContentContextWrapper>
...
<ContentContextWrapper id={'footer'}>
<Link to={'/contact'}>Contact us</Link>
</ContentContextWrapper>
</div>

Event Trackers

There are two ways of tracking events. Which one to use depends on how the target Component has been wrapped and whether we have access to its internals or not.

Hooks

Event tracking hooks can be invoked to generate a tracking callback that's already configured with the correct TrackingContext.

Functions

Event tracking functions are the lowest level APIs to track Events, and they require developers to specify the correct Tracking Context. This can be retrieved from LocationWrappers / TrackedContexts render-props, or by invoking the useTrackingContext hook.

info

Check out the Custom Components how to for more information and a practical example of how that works.

How-to Guides

To immediately jump into instrumenting your application, follow the step-by-step How-to Guides:

API Reference

Plugins

Core Concepts