Skip to content

README.md

Latest commit

 

History

History
336 lines (268 loc) · 11.1 KB

README.md

File metadata and controls

336 lines (268 loc) · 11.1 KB

@altertable/altertable-react

React SDK for capturing and sending analytics events to Altertable with type-safe funnel tracking.

Installation

npm install @altertable/altertable-js @altertable/altertable-react
# or
pnpm add @altertable/altertable-js @altertable/altertable-react
# or
yarn add @altertable/altertable-js @altertable/altertable-react
# or
bun add @altertable/altertable-js @altertable/altertable-react

Quick Start

import {
  AltertableProvider,
  useAltertable,
} from '@altertable/altertable-react';
import { altertable } from '@altertable/altertable-js';

// Initialize the core SDK
altertable.init('YOUR_API_KEY');

function App() {
  return (
    <AltertableProvider client={altertable}>
      <SignupPage />
    </AltertableProvider>
  );
}

function SignupPage() {
  const { track } = useAltertable();

  function handleStart() {
    track('Signup Started', { source: 'homepage' });
  }

  function handleSubmit(email: string) {
    track('Signup Submitted', { email });
  }

  return (
    <div>
      <button onClick={() => handleStart()}>Start Signup</button>
      <button onClick={() => handleSubmit('john.doe@example.com')}>
        Submit
      </button>
    </div>
  );
}

Note

For server-side rendering (SSR), initialize in a useEffect():

import { useEffect } from 'react';
import { altertable } from '@altertable/altertable-js';
import { AltertableProvider } from '@altertable/altertable-react';

function App() {
  useEffect(() => {
    altertable.init('YOUR_API_KEY');
  }, []);

  return (
    <AltertableProvider client={altertable}>
      <SignupPage />
    </AltertableProvider>
  );
}

Features

  • Automatic page view tracking – Captures page views automatically
  • Session management – Handles anonymous and session IDs automatically
  • Event queuing – Queues events when offline or consent is pending
  • Privacy compliance – Built-in tracking consent management
  • Multiple storage options – localStorage, cookies, or both
  • Type-safe funnel tracking – Define funnel steps with TypeScript for compile-time safety
  • React Hooks – Easy-to-use Hooks for tracking events and managing funnels
  • Context provider – Share Altertable instance across your React component tree
  • Zero dependencies – Only depends on React and the core Altertable SDK

API Reference

Components

<AltertableProvider>

Provides the Altertable client to the React component tree.

Props:

Parameter Type Required Description
client Altertable Yes The Altertable client instance (see core SDK API Reference)
children ReactNode Yes React children

Example:

import { AltertableProvider } from '@altertable/altertable-react';
import { altertable } from '@altertable/altertable-js';

altertable.init('YOUR_API_KEY');

function App() {
  return (
    <AltertableProvider client={altertable}>
      <YourApp />
    </AltertableProvider>
  );
}

Hooks

useAltertable<TFunnelMapping>()

Returns an object with tracking methods and funnel utilities.

Type Parameters:

Parameter Type Required Description
TFunnelMapping FunnelMapping No Type mapping of funnel names to their step definitions

Returns:

Property Type Description
identify (userId: string, traits?: UserTraits) => void Identify a user
page (url: string) => void Manually track a page view (use only when autoCapture is false)
reset (options?: { resetDeviceId?: boolean }) => void Resets the current identity context so future events are not associated with the previous user
alias (newUserId: string) => void Link a new ID to the current identity
updateTraits (traits: UserTraits) => void Update user traits
configure (updates: Partial<AltertableConfig>) => void Update configuration
getTrackingConsent () => TrackingConsentType Get current consent state
selectFunnel (funnelName: keyof TFunnelMapping) => { track: FunnelTracker } Get funnel-specific tracker

Example:

function MyComponent() {
  const { track, identify, selectFunnel } = useAltertable<MyFunnelMapping>();

  function handleClick() {
    track('Button Clicked', { button: 'signup' });
  }

  function handleLogin(userId: string) {
    identify(userId, { email: 'user@example.com' });
  }

  return <button onClick={handleClick}>Click me</button>;
}

Note

Page Tracking: By default, Altertable automatically captures page views. Only use page() when you've disabled auto-capture:

// Initialize with auto-capture disabled
altertable.init('YOUR_API_KEY', { autoCapture: false });

function MyComponent() {
  const { page } = useAltertable();

  // Now you must manually track page views
  function handleNavigation(nextUrl: string) {
    page(nextUrl);
  }
}

Why use auto-capture (default)?

  • No manual tracking required
  • Handles browser navigation events (popstate, hashchange)
  • Consistent tracking across all page changes

When to use page():

  • Custom routing that doesn't trigger browser events
  • Virtual page views that don't trigger URL changes (modals, step changes)
  • Server-side tracking where auto-capture isn't available

selectFunnel(funnelName)

Returns a type-safe tracker for a specific funnel.

Parameters:

Parameter Type Required Description
funnelName keyof TFunnelMapping Yes The name of the funnel to track

Returns:

Property Type Description
trackStep (stepName: FunnelStepName, properties?: FunnelStepProperties) => void Type-safe funnel step tracker

Example:

import {
  type FunnelMapping,
  useAltertable,
} from '@altertable/altertable-react';

interface SignupFunnelMapping extends FunnelMapping {
  signup: [
    { name: 'Signup Started'; properties: { source: string } },
    { name: 'Signup Completed'; properties: { userId: string } },
  ];
}

function SignupPage() {
  const { selectFunnel } = useAltertable<SignupFunnelMapping>();
  const { trackStep } = selectFunnel('signup');

  function handleStart() {
    trackStep('Signup Started', { source: 'homepage' });
  }

  function handleComplete(userId: string) {
    trackStep('Signup Completed', { userId });
  }

  return (
    <div>
      <button
        onClick={() => {
          handleStart();
        }}
      >
        Start
      </button>
      <button
        onClick={() => {
          handleComplete('u_01jza857w4f23s1hf2s61befmw');
        }}
      >
        Complete
      </button>
    </div>
  );
}

Types

AltertableConfig

Configuration options for the Altertable SDK. See the core SDK documentation for full details.

FunnelMapping

Type mapping of funnel names to their step definitions.

type FunnelMapping = Record<FunnelName, readonly FunnelStep[]>;

Example:

import { type FunnelMapping } from '@altertable/altertable-react';

interface MyFunnelMapping extends FunnelMapping {
  signup: [
    {
      name: 'Signup Started';
      properties: { source: string };
    },
    {
      name: 'Signup Completed';
      properties: { userId: string };
    },
  ];
  checkout: [
    {
      name: 'Cart Viewed';
      properties: { itemCount: number };
    },
    {
      name: 'Purchase Completed';
      properties: { orderId: string; amount: number };
    },
  ];
}

FunnelStep

Definition of a single funnel step.

type FunnelStep = {
  name: string;
  properties?: FunnelStepProperties;
};
Property Type Required Description
name string Yes The name of the funnel step
properties FunnelStepProperties No Expected properties for this step

FunnelTracker

Type-safe tracker for a specific funnel.

type FunnelTracker = {
  trackStep: (
    stepName: FunnelStepName,
    properties?: FunnelStepProperties
  ) => void;
};

License

MIT