Getting Started with Allem SDK Analytics: Provider-Agnostic Event Tracking for React

@allem-sdk/analytics provides provider-agnostic analytics hooks for React. Define adapters for any analytics provider — Mixpanel, PostHog, Segment, or your own — and every call to track(), page(), or identify() sends to all of them simultaneously.

Installation

npm install @allem-sdk/analytics

Or with the meta-package:

npm install allem-sdk

Core Concept: Adapters

An adapter is an object with three methods that map to your analytics provider's API:

interface AnalyticsAdapter {
  track: (event: string, properties?: Record<string, unknown>) => void;
  page: (name?: string, properties?: Record<string, unknown>) => void;
  identify: (userId: string, traits?: Record<string, unknown>) => void;
}

You can register multiple adapters. Every hook call dispatches to all of them.

Setup

1. Create Adapters

// adapters/mixpanel.ts
import mixpanel from "mixpanel-browser";

export const mixpanelAdapter = {
  track: (event, props) => mixpanel.track(event, props),
  page: (name, props) => mixpanel.track_pageview({ page: name, ...props }),
  identify: (userId) => mixpanel.identify(userId),
};

// adapters/posthog.ts
import posthog from "posthog-js";

export const posthogAdapter = {
  track: (event, props) => posthog.capture(event, props),
  page: (name, props) => posthog.capture("$pageview", { page: name, ...props }),
  identify: (userId, traits) => posthog.identify(userId, traits),
};

2. Wrap Your App

import { AnalyticsProvider } from "@allem-sdk/analytics";
import { mixpanelAdapter } from "./adapters/mixpanel";
import { posthogAdapter } from "./adapters/posthog";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <AnalyticsProvider adapters={[mixpanelAdapter, posthogAdapter]}>
      {children}
    </AnalyticsProvider>
  );
}

useTrack

Track custom events across all adapters:

import { useTrack } from "@allem-sdk/analytics";

function ProductCard({ product }) {
  const track = useTrack();

  return (
    <div>
      <h3>{product.name}</h3>
      <button
        onClick={() => {
          track("Add to Cart", {
            productId: product.id,
            price: product.price,
            category: product.category,
          });
          addToCart(product);
        }}
      >
        Add to Cart
      </button>
    </div>
  );
}

usePageView

Track page views on mount. Call it at the top of page components:

import { usePageView } from "@allem-sdk/analytics";

export default function ProductPage({ params }) {
  usePageView("Product Page", { productId: params.id });

  return <div>{/* page content */}</div>;
}

The page view fires once when the component mounts. It sends to all registered adapters.

useIdentify

Identify users after authentication:

import { useIdentify } from "@allem-sdk/analytics";

function LoginHandler() {
  const identify = useIdentify();

  const handleLogin = async (credentials) => {
    const user = await signIn(credentials);

    identify(user.id, {
      email: user.email,
      name: user.name,
      plan: user.plan,
      signupDate: user.createdAt,
    });
  };

  return <LoginForm onSubmit={handleLogin} />;
}

Console Adapter for Development

Create a simple adapter that logs events during development:

const consoleAdapter = {
  track: (event, props) => console.log("[analytics] track", event, props),
  page: (name, props) => console.log("[analytics] page", name, props),
  identify: (id, traits) => console.log("[analytics] identify", id, traits),
};

<AnalyticsProvider
  adapters={[
    ...(process.env.NODE_ENV === "production"
      ? [mixpanelAdapter, posthogAdapter]
      : [consoleAdapter]),
  ]}
>
  <App />
</AnalyticsProvider>

Complete Example

A checkout flow with full analytics instrumentation:

import { useTrack, usePageView, useIdentify } from "@allem-sdk/analytics";

export default function CheckoutPage() {
  usePageView("Checkout");
  const track = useTrack();

  const handlePurchase = async (order) => {
    track("Purchase Completed", {
      orderId: order.id,
      total: order.total,
      items: order.items.length,
      currency: order.currency,
    });
  };

  const handleCouponApplied = (code: string, discount: number) => {
    track("Coupon Applied", { code, discount });
  };

  const handleStepChanged = (step: string) => {
    track("Checkout Step", { step });
  };

  return (
    <CheckoutFlow
      onStepChange={handleStepChanged}
      onCouponApply={handleCouponApplied}
      onPurchase={handlePurchase}
    />
  );
}

Hooks Reference

Hook	Signature	Description
useTrack	() => (event, properties?) => void	Track custom events
usePageView	(name, properties?) => void	Track page view on mount
useIdentify	() => (userId, traits?) => void	Identify authenticated users

What's Next

• Explore Allem SDK Auth for authentication hooks
• Try Allem SDK Hooks for utility hooks
• Read the full analytics documentation