Introduction

Welcome to the Event Tracker documentation.

What is Event Tracker?

Event Tracker is a declarative React library that simplifies the process of implementing complex event tracking, allowing developers to focus more on business logic. It is designed to make event tracking easy and efficient for applications of any scale.


import { createTracker } from "@offlegacy/event-tracker";
 
// Create a tracker instance
const [Track, useTracker] = createTracker({
  DOMEvents: {
    onClick: (params, context) => {
      log("Click event:", params, context);
    },
  },
});
 
// Usage in the app
function App() {
  return (
    <Track.Provider initialContext={{ userId: "userId-123" }}>
      <Track.Click params={{ buttonId: "event-click" }}>
        <button>Event Click!</button>
      </Track.Click>
    </Track.Provider>
  );
}

Key Features

Event Tracker provides a wide range of features focused on both developer experience and application performance.

Feature	Description
Declarative API	Easily declare tracking as components without additional setup or complex code.
Analytics Tool Agnostic	Integrate with any tool such as Google Analytics or Amplitude without modifying existing infrastructure.
Clear Separation of Concerns	Keep tracking logic completely separate from business code, improving readability, testability, and maintainability.
Optimized Performance	Built-in strategies like batching, debouncing, and throttling minimize network requests, enabling stable tracking without performance degradation.
Guaranteed Execution Order	Ensures events are processed in the intended order even in asynchronous scenarios, enabling accurate tracking in complex user flows.
Data Validation	Built-in static schema validation with Zod prevents build-time errors and ensures the reliability of collected event data.

Core Concepts

To use Event Tracker effectively, there are several key concepts to understand.

Instance (`createTracker`)

This is the fundamental starting point of the library. Using the createTracker function, you create a tracker instance (a collection of Track components and the useTracker hook). Here, you define event tracking by configuring DOM event handlers, impression handlers, and schemas.

You can create multiple tracker instances for different purposes (for example, one for Google Analytics and another for Amplitude).

Provider (`Track.Provider`)

Implemented based on React’s Context API. Wrap the top level of your application or a specific component tree with Track.Provider to supply common data (context) needed for tracking to child components. For example, passing userId or pageName as context allows these values to be used during event tracking.

Event Components (`Track.Click`, `Track.PageView`, etc.)

These are special components that enable declarative event tracking. They are provided as the first element in the array returned by createTracker.

Track.Click: Tracks when a click event occurs on child elements.
Track.Impression: Tracks when child elements are displayed on screen.
Track.PageView: Tracks a page view event when the component mounts.

You can use the provided components or create custom ones to handle various user interactions and lifecycle events. Each component accepts context and params props to pass specific data relevant to the event.

Custom Hook

Use when you need more complex or conditional event tracking that is not directly tied to component lifecycle or DOM events. The hook allows you to access context from Track.Provider and execute defined tracking logic imperatively.

Next Steps

These core concepts work together to create a powerful and flexible event tracking environment with Event Tracker. For more detailed usage and in-depth information on each feature, see the following documentation:

Why Event Tracker?: Learn the necessity and main features of Event Tracker.
createTracker: Learn how to create and configure a tracker instance.
Components: Explore all available tracking components with usage examples.
Hook: Learn how to implement custom tracking with the hook.
Batching: Optimize performance through event batching strategies.
Data Validation: Ensure data integrity with Zod schema validation.