@xtreamsrl/react-analytics

This package exposes a collections of hooks and utilities to track user interactions events.

Installation

npm install @xtreamsrl/react-analytics

Usage

Define the app pages you want to track by augmenting the Paths interface; Then assign the page view identifier (defined in the chosen analytics platform) to the corresponding key within the PageViewMap.

// paths.d.ts
import { Paths } from '@xtreamsrl/react-analytics'
declare module '@xtreamsrl/react-analytics' {
  interface Paths {
    /*
    * Here you can list your app paths.
    * This interface will define the keys of the page view map.
    *
    * Login: string;
    *
    */
  }
}

// pageViewMap.ts
import { PageViewMap } from "@xtreamsrl/react-analytics";
export const pageViewMap: PageViewMap = {
  /*
  * Here you can map your app paths (defined in paths.d.ts)
  * to the according page view keys (defined in the chosen analytics platform)
  *
  * Login: 'loginPage';
  *
  */
}

Set up the analytics manager tool to use with configureAnalytics and wrap the main app with the AnalyticsProvider.

// app.tsx
import { AnalyticsProvider  } from '@xtreamsrl/react-analytics';
import { DummyAnalyticsManager } from '@xtreamsrl/react-analytics-dummy';
import { pageViewMap } from '../shared/analytics';

configureAnalytics(new DummyAnalyticsManager());

export function App() {
  return (
    <AnalyticsProvider value={{ pageViewMap }}>
      <MainApp />
    </AnalyticsProvider>
  );
}

Domain tracking

Inside the folder of the feature to track, define the analytics events and the map of corresponding metadata builder functions.

// events.ts
export enum HomeEvents {
  Welcome = 'WelcomeOpen',
  Exit = 'ExitOpen',
  EventWithProps = 'EventWithProps',
}

// mapping.ts
import { AnalyticsEvent } from '@xtreamsrl/react-analytics';
import { HomeEvents } from './events';

interface EventProps {
  prop1: string;
  prop2: number;
}

const homeEventsMapping = {
  [HomeEvents.Welcome]: () => ({
    type: 'homepage'
  }),
  [HomeEvents.Exit]: () => ({
    type: 'exit'
  }),
  [HomeEvents.EventWithProps]: (props: EventProps) => ({
    type: 'eventWithProps',
    props
  }),
} satisfies Record<HomeEvents, (...props: any[]) => AnalyticsEvent>;;

Use createDomainTracker by passing it as a parameter the feature's event map previously defined. It generates a feature-specific hook useTracker, which exposes functions to track basic events like page changing trackPageView.

// index.ts
import { createDomainTracker  } from '@xtreamsrl/react-analytics';
import { homeEventsMapping } from './mapping';

export const { hook: useTracker } = createDomainTracker(homeEventsMapping);
export { HomeEvents } from './events';

Basic usage of the hook:

// Welcome.tsx
import { useTracker } from '../analytics';
import { useEffect } from "react";

export function Welcome() {
  const { track } = useTracker();

  useEffect(() => {
    track(HomeEvents.Welcome);
  }, [])
  
  return (
    <Body/>
  );
}

In case you need to track events with properties, you can pass them as second argument to the track function.

NOTE WELL: the exploit of 'useEffect' is only an example, you can and must use the track function wherever you need to track an event.

// EventWithProps.tsx
import { useTracker } from '../analytics';
import { useEffect } from "react";

export function Component() {
  const { track } = useTracker();

  useEffect(() => {
    track(HomeEvents.EventWithProps, { prop1: 'value1', prop2: 'value2' });
  }, [])
  
  return (
    <Body/>
  );
}

Who we are