@altertable/altertable-js

@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: 'john.doe@example.com',
  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
• Offline delivery – Persists unsent events and retries when the browser comes back online
• Event queuing – Queues events when 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',
});

Calling init again replaces configuration and discards any events still in the outbound batch buffer. If you need them sent first (for example before switching API keys), await altertable.flush() before calling init again.

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

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: 'john.doe@example.com',
  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 IDs
eventPersistence	StorageType or false	Same as persistence	The persistence strategy for unsent event payloads
trackingConsent	TrackingConsentType	"granted"	The tracking consent state
onError	(error: Error) => void	-	Optional handler for SDK errors
flushEventThreshold	number	20	Flush when combined buffered events reach this count
flushIntervalMs	number	150	Periodic batch flush interval (ms)
maxBatchSize	number	20	Max payloads per HTTP request

Offline Delivery

Altertable can persist unsent event payloads so they survive reloads and send when the browser comes back online. By default, event payloads use the same storage strategy as persistence, but cookie-backed strategies store event payloads in localStorage only.

If you do not want event payloads written to durable browser storage, set eventPersistence: false. Events will still batch in memory for the current page session, but they will not survive a reload.

altertable.init('YOUR_API_KEY', {
  eventPersistence: false,
});

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: 'john.doe@example.com',
  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