Tracking events

The implementation strategy for each analytics provider varies depending on whether it's designed for client-side or server-side use. We'll explore both approaches, as they are crucial for ensuring accurate and comprehensive analytics data in your web SaaS application.

Client-side tracking

The client strategy for tracking events, which every provider must implement, is straightforward:

export type AllowedPropertyValues = string | number | boolean;

type TrackFunction = (
  event: string,
  data?: Record<string, AllowedPropertyValues>,
) => void;

export interface AnalyticsProviderClientStrategy {
  Provider: ({ children }: { children: React.ReactNode }) => React.ReactNode;
  track: TrackFunction;
}

As shown above, each provider must supply two key elements:

1. Provider - a component that wraps your app.
2. track - a function responsible for sending event data to the provider.

To track an event, you simply need to invoke the track method, passing the event name and an optional data object:

import { track } from "@turbostarter/analytics-web";

export const MyComponent = () => {
  return (
    <button onClick={() => track("button.click", { country: "US" })}>
      Track event
    </button>
  );
};

Identifying users

Linking events to specific users enables you to build a full picture of how they're using your product across different sessions, devices, and platforms.

For identification purposes, the client strategy can also expose identify and reset methods. They are optional and only needed if you want to identify users in your app and associate their actions with a specific user ID.

Not all analytics providers support user identification (for example, Vercel Analytics and Plausible), so make sure your chosen provider exposes these methods before using them.

type IdentifyFunction = (
  userId: string,
  traits?: Record<string, AllowedPropertyValues>,
) => void;

export interface AnalyticsProviderClientStrategy {
  identify: IdentifyFunction;
  reset: () => void;
}

To identify users on the client, call the identify function, passing the user's ID and an optional traits object:

import { identify } from "@turbostarter/analytics-web";

identify("user-123", { name: "John Doe" });

This will associate all future events with the user's ID, allowing you to track user behavior and gain valuable insights into your application's usage patterns.

Server-side tracking

The server strategy for tracking events that every provider has to implement is even simpler:

export interface AnalyticsProviderServerStrategy {
  track: TrackFunction;
}

This server-side strategy allows you to track events outside of the browser environment, which is particularly useful for scenarios involving server actions or React Server Components.

To track an event on the server side, simply call the track method, providing the event name and an optional data object:

import { track } from "@turbostarter/analytics-web/server";

track("button.click", {
  country: "US",
  region: "California",
});

import { track } from "@turbostarter/analytics-web";

import { track } from "@turbostarter/analytics-web/server";

Congratulations! You've now mastered event tracking in your TurboStarter web app. With this knowledge, you're well-equipped to analyze user behaviors and gain valuable insights into your application's usage patterns. Happy analyzing! 📊