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:

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.

Transform events in JavaScript

Use the JavaScript SDK's transformEvent option when every track or page-view event needs the same enrichment or filtering. The transformer receives the complete payload after the SDK adds context, identifiers, defaults, and a timestamp, but before the event is queued, persisted, or sent.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
altertable.init('YOUR_API_KEY', {
  transformEvent(event) {
    if (event.properties.internal_traffic === true) {
      return null;
    }

    return {
      ...event,
      properties: {
        ...event.properties,
        release: APP_RELEASE,
      },
    };
  },
});

Return null to discard an event. The transformer runs synchronously for manual and automatically captured track and page-view events; it does not transform identify or alias payloads. If it throws, the SDK discards the event and sends the error to onError when configured. Replace it later with altertable.configure({ transformEvent }).

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.