# 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:

### TypeScript

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

### React

```tsx
function CheckoutButton() {
  const { track } = useAltertable();

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

  return <button onClick={handleCheckout}>Complete checkout</button>;
}
```

### Python

```python
client.track(
    event="checkout_completed",
    distinct_id="user_abc123",
    properties={
        "revenue": 49.99,
        "plan": "pro",
        "currency": "USD",
    },
)
```

### Ruby

```ruby
Altertable.track('checkout_completed', 'user_abc123', properties: {
  revenue: 49.99,
  plan: 'pro',
  currency: 'USD'
})
```

### Swift

```swift
client.track(
    event: "checkout_completed",
    properties: [
        "revenue": 49.99,
        "plan": "pro",
        "currency": "USD"
    ]
)
```

### Kotlin

```kotlin
Altertable.shared?.track(
    event = "checkout_completed",
    properties = mapOf(
        "revenue" to 49.99,
        "plan" to "pro",
        "currency" to "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()`](/docs/product-analytics/ingest-data/identify.md) when you know who the user is, so anonymous and authenticated activity can be analyzed together.

## API reference

For HTTP request details, batching behavior, response shape, and error codes, see [`POST /track`](/docs/api-references/product-analytics.md#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.