@altertable/altertable-js

JavaScript SDK for capturing and sending analytics events to Altertable.

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

// Update user traits
altertable.updateTraits({
  onboarding_completed: true,
});

// Link a new ID to the current identity
altertable.alias('new_user_id-019aca6a-1e42-71af-81a0-1e14bbe2ccbd');

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
• TypeScript support – Full TypeScript definitions included
• Lightweight – Minimal bundle size with no external dependencies

API Reference

Initialization

altertable.init(apiKey, config?)

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

Parameters:

| Parameter | Type | Required | Description | | --------- | --------------------------------------- | -------- | ----------------------- | | apiKey | string | Yes | Your Altertable API key | | config | AltertableConfig | No | Configuration options |

Example:

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

Event Tracking

altertable.track(event, properties?)

Tracks a custom event with optional properties.

Parameters:

| Parameter | Type | Required | Default | Description | | ------------ | ------------------------------------- | -------- | ------- | ----------------------- | | event | string | Yes | - | The event name | | properties | EventProperties | No | {} | Custom event properties |

Example:

altertable.track('Purchase Completed', {
  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
  amount: 29.99,
  currency: 'USD',
});

altertable.page(url)

Tracks a page view event.

When autoCapture is enabled, this method is automatically called when the page URL changes.

Parameters:

| Parameter | Type | Required | Description | | --------- | -------- | -------- | ------------ | | url | string | Yes | The page URL |

Example:

altertable.page('https://example.com/products');

[!NOTE]

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

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

User Identification

altertable.identify(userId, traits?)

Identifies a user with their ID and optional traits. It flags the identity as being a identitied user.

Parameters:

| Parameter | Type | Required | Default | Description | | --------- | --------------------------- | -------- | ------- | ---------------------------- | | userId | string | Yes | - | The user's unique identifier | | traits | UserTraits | No | {} | User properties |

Example:

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

altertable.updateTraits(traits)

Updates user traits for the current user.

Parameters:

| Parameter | Type | Required | Description | | --------- | --------------------------- | -------- | ------------------------- | | traits | UserTraits | Yes | User properties to update |

Example:

altertable.updateTraits({
  onboarding_completed: true,
});

altertable.alias(newUserId)

Links a new ID to the current identity.

Parameters:

| Parameter | Type | Required | Default | Description | | ----------- | -------- | -------- | ------- | -------------------------------------- | | newUserId | string | Yes | ------- | New ID to link to the current identity |

Example:

altertable.alias("new_user_id-019aca6a-1e42-71af-81a0-1e14bbe2ccbd");

Session Management

altertable.reset(options?)

Resets the current identity context so future events are not associated with the previous user.

Parameters:

| Parameter | Type | Required | Default | Description | | ------------------------ | --------- | -------- | ------- | --------------------------- | | options | object | No | {} | Reset options | | options.resetDeviceId | boolean | No | false | Whether to reset device ID |

Example:

// Reset everything except device ID
altertable.reset();

// Reset all IDs
altertable.reset({
  resetDeviceId: true,
});

Configuration

altertable.configure(updates)

Updates the configuration after initialization.

Parameters:

| Parameter | Type | Required | Description | | --------- | ------------------------------------------------ | -------- | --------------------- | | updates | Partial<AltertableConfig> | Yes | Configuration updates |

Example:

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

Privacy & Consent

altertable.getTrackingConsent()

Returns the current tracking consent state.

Returns: TrackingConsentType

Example:

const consent = altertable.getTrackingConsent();
if (consent === 'granted') {
  // Tracking is allowed
}

Types

AltertableConfig

Configuration options for the Altertable SDK.

| Property | Type | Default | Description | | ----------------- | --------------------------------------------- | ----------------------------- | ------------------------------------------------------ | | baseUrl | string | "https://api.altertable.ai" | The base URL of the Altertable API | | environment | string | "production" | The environment of the application | | autoCapture | boolean | true | Whether to automatically capture page views and events | | release | string | - | The release ID of the application | | debug | boolean | false | Whether to log events to the console | | persistence | StorageType | "localStorage+cookie" | The persistence strategy for storing IDs | | trackingConsent | TrackingConsentType | "granted" | The tracking consent state |

EventProperties

Custom properties for events.

type EventProperties = Record<string, unknown>;

Example:

{
  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
  amount: 29.99,
  currency: 'USD',
  category: 'electronics',
  user_type: 'premium'
}

UserTraits

User properties for identification.

type UserTraits = Record<string, unknown>;

Example:

{
  email: '[email protected]',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
  plan: 'premium',
  signup_date: '2024-01-15'
}

StorageType

Available storage strategies.

| Value | Description | | ----------------------- | ------------------------------------- | | "localStorage" | Use localStorage only | | "sessionStorage" | Use sessionStorage only | | "cookie" | Use cookies only | | "memory" | Use in-memory storage (not persisted) | | "localStorage+cookie" | Use localStorage with cookie fallback |

TrackingConsentType

Available tracking consent states.

| Value | Description | | ------------- | ------------------------------------- | | "granted" | User has granted consent for tracking | | "denied" | User has denied consent for tracking | | "pending" | User hasn't made a decision yet | | "dismissed" | User dismissed the consent prompt |

License

MIT