Track

Track Events

Use track to record product actions such as signups, purchases, feature usage, page views, and activation milestones.

Track a small set of meaningful events first. A few stable event names with useful properties are easier to query than a large stream of low-signal UI clicks.

When to call it

Use track when something happened in your product and you want it available for segmentation, retention, funnel analysis, SQL, or AI agents.

Good first events often describe:

activation moments
conversion steps
recurring feature usage
billing or account lifecycle changes

SDK examples

Use track() where the product action happens:

altertable.track('checkout_completed', {
  revenue: 49.99,
  plan: 'pro',
  currency: 'USD',
});

distinct_id ties an event to a person, device, or session. Client-side SDKs can manage anonymous IDs automatically. Server-side SDKs and direct API clients should pass a stable ID on each call.

Call identify() when you know who the user is, so anonymous and authenticated activity can be analyzed together.

Batch events

Batching reduces request overhead when you track several events. JavaScript, React, Swift, and Kotlin batch queued calls automatically. Ruby accepts an array in one track call. Python sends one request per call; for an explicit batch, send an array to POST /track.

altertable.track('signup', { plan: 'pro' });
altertable.track('login');

Transform events

Where supported, add application context before events are sent. These examples label the product area from the page URL or screen name and record the surface that produced the event:

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

altertable.init('YOUR_API_KEY', {
  transformEvent(event) {
    const url = event.properties.$url;
    let pathname = globalThis.location?.pathname ?? '/';
    if (typeof url === 'string') {
      try {
        pathname = new URL(url, globalThis.location?.origin).pathname;
      } catch {
        pathname = globalThis.location?.pathname ?? '/';
      }
    }

    const title = globalThis.document?.title;
    const properties = { ...event.properties, surface: 'website' };

    if (pathname === '/shop' || pathname.startsWith('/shop/')) {
      properties.product = 'shop';
    }
    if (title) {
      properties.title = title;
    }

    return { ...event, properties };
  },
});

In JavaScript and React, transformEvent runs on track and page events after the SDK adds context and identifiers. It does not run on identify, alias, or events forwarded from PostHog. Configure the shared JavaScript client before rendering <AltertableProvider> in React.

API reference

For HTTP request details, batching behavior, response shape, and error codes, see POST /track.

Best practices

Use clear event names and keep them stable over time.
Track meaningful product actions, not every low-level interaction.
Include only properties you plan to filter, group, or query.
Avoid secrets and regulated sensitive data in event properties.