SDKs

Altertable provides JavaScript and React SDKs that make it easy to track events, identify users, and manage sessions in your application. The SDKs handle event queuing, session management, and privacy compliance automatically.

Available SDKs

• JavaScript SDK (@altertable/altertable-js) - Works with any JavaScript framework or vanilla JavaScript
• React SDK (@altertable/altertable-react) - React Hooks and components with type-safe funnel tracking

JavaScript SDK

The JavaScript SDK works with any JavaScript framework or vanilla JavaScript. Browse source code on GitHub.

Installation

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

Quick Start

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

// Initialize with your API key
altertable.init('YOUR_API_KEY');

// Track an event
altertable.track('Step Completed', {
  step: 1,
});

// Identify a user
altertable.identify('u_01jza857w4f23s1hf2s61befmw', {
  email: '[email protected]',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
});

Initialization

altertable.init(apiKey, config?)

Initializes the Altertable SDK with your API key and optional configuration.

Parameters:

Example:

altertable.init('YOUR_API_KEY', {
  environment: 'development',
  debug: true,
});

Configuration

The SDK supports various configuration options:

Storage Options

The SDK supports multiple storage strategies for persisting device and session IDs:

Example:

altertable.init('YOUR_API_KEY', {
  persistence: 'localStorage+cookie', // Default: localStorage with cookie fallback
});

Privacy & Consent

The SDK includes built-in tracking consent management to help you comply with privacy regulations.

Consent States

Managing Consent

// Get current consent state
const consent = altertable.getTrackingConsent();

// Update consent state
altertable.configure({
  trackingConsent: 'granted',
});

When consent is "pending" or "denied", events are queued and sent once consent is granted.

Updating Configuration

You can update the configuration after initialization:

altertable.configure({
  trackingConsent: 'granted',
  debug: true,
});

React SDK

The React SDK provides Hooks and components with type-safe funnel tracking. Browse source code on GitHub.

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' });
  }

  return <button onClick={handleStart}>Start Signup</button>;
}

Server-Side Rendering (SSR)

For server-side rendering, initialize the SDK 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}>
      <YourApp />
    </AltertableProvider>
  );
}

Type-Safe Funnel Tracking

The React SDK provides type-safe funnel tracking to ensure compile-time safety for your funnel definitions:

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>
  );
}

Features

Both SDKs provide:

• Automatic page view tracking – Captures page views automatically
• Identity management – Handles device, distinct, 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
• TypeScript support – Full TypeScript definitions included
• Lightweight – Minimal bundle size with no external dependencies

Next Steps

• Track Events: Learn how to track product events
• Identify Users: Set up user identification
• API Reference: Direct API access when needed