Skip to content

README.md

Latest commit

 

History

History
396 lines (308 loc) · 16.9 KB

README.md

File metadata and controls

396 lines (308 loc) · 16.9 KB
Raw

@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 view tracking – Track screen and component views without Strict Mode duplicates
  • 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) => { trackStep: (...) => void } 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>
  );
}

useScreenView(name, options?)

Tracks a screen view when the component mounts.

Sends a $screen event with $view_name, $view_type, and $view_id when an id is provided.

Use this hook for virtual screens that are not already represented by a page URL, such as app tabs, modal routes, embedded flows, or entity-specific screens. For full-page navigation, prefer Altertable's automatic pageview capture, which is enabled by default in the core SDK.

Example:

import { useScreenView } from '@altertable/altertable-react';

function DashboardScreen({ dashboard }: { dashboard: Dashboard }) {
  useScreenView('Dashboard', {
    id: dashboard.id,
    properties: { dashboardId: dashboard.id },
  });

  return <DashboardBody />;
}

The hook sends once per screen identity. Properties are captured from the first render where tracking is eligible; later property changes for the same name and id do not send another event. The hook also prevents React Strict Mode effect replay from sending duplicate screen events in development.

Options:

Property Type Description
id string Stable identifier for this screen instance within name. Use when multiple screens share the same name — typically the entity id, e.g. id: dashboard.id for each dashboard using the screen name Dashboard.
properties Record<string, unknown> Additional properties to include with the screen event.
disabled boolean Prevents the screen event from being sent.

useView(name, options?)

Tracks a view when the referenced element becomes visible.

Returns { viewRef }, a callback ref to attach to the root element of the view to track.

Sends a $view event with $view_name, $view_type, and $view_id when an id is provided.

Use this hook for meaningful parts of a screen, such as cards, sections, dashboard insights, or embedded panels. It is not a replacement for full-page pageview capture.

Example:

import { useView } from '@altertable/altertable-react';

function InsightCard({ insight }: { insight: Insight }) {
  const { viewRef } = useView<HTMLDivElement>('Insight', {
    id: insight.id,
    properties: { insightId: insight.id, kind: insight.kind },
  });

  return <div ref={viewRef}>{insight.title}</div>;
}

The hook sends once per view identity when the element becomes visible. Properties are captured from the latest render before the first visible event; later property changes for the same name and id do not send another event. The hook also prevents React Strict Mode effect replay from sending duplicate view events in development.

Options:

Property Type Description
id string Stable identifier for this view instance within name. Use when multiple views share the same name — typically the entity id, e.g. id: insight.id for each insight card using the view name Insight.
properties Record<string, unknown> Additional properties to include with the view event.
disabled boolean Prevents the view event from being sent.
visibility ViewVisibilityOptions Visibility settings for the underlying IntersectionObserver.
visibility.root Element | Document | null The element used as the viewport for checking visibility of the target. Defaults to null. See IntersectionObserver: root.
visibility.rootMargin string Offsets applied to the root's bounding box before intersection tests, using the same syntax as the CSS margin property. See IntersectionObserver: rootMargin.
visibility.threshold number | number[] One or more visibility ratios at which the observer callback runs. A value of 0 fires when any pixel becomes visible; 1.0 fires when the target is fully visible. Defaults to 0. See IntersectionObserver: threshold.

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

License

MIT