Tracking Product Events

Track product events to understand user behavior, measure feature adoption, and analyze user journeys. Altertable provides both an SDK and a direct API for capturing events.

Using the SDK

The recommended way to track events is using an Altertable SDK, which provides helper functions for tracking events, identifying users, and more on top of the Altertable API.

See the SDKs guide for installation and setup instructions.

JavaScript SDK

Tracking Events

Use altertable.track() to track custom events:

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

// Initialize the SDK
altertable.init('YOUR_API_KEY');

// Track an event with properties
altertable.track('Purchase Completed', {
  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
  amount: 29.99,
  currency: 'USD',
});

Page View Tracking

By default, Altertable automatically captures page views when the URL changes. The SDK handles browser navigation events (popstate, hashchange) automatically.

Why use auto-capture (default)?

• No manual tracking required
• Handles browser navigation events automatically
• Consistent tracking across all page changes

When to use manual page() tracking:

• 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

To manually track a page view:

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

To disable auto-capture:

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

React SDK

Basic Event Tracking

import {
  AltertableProvider,
  useAltertable,
} from '@altertable/altertable-react';
import { altertable } from '@altertable/altertable-js';

// Initialize the SDK
altertable.init('YOUR_API_KEY');

function App() {
  return (
    <AltertableProvider client={altertable}>
      <ProductPage />
    </AltertableProvider>
  );
}

function ProductPage() {
  const { track } = useAltertable();

  function handlePurchase(productId: string, amount: number) {
    track('Purchase Completed', {
      product_id: productId,
      amount,
      currency: 'USD',
    });
  }

  return (
    <button onClick={() => handlePurchase('p_123', 29.99)}>
      Buy Now
    </button>
  );
}

Type-Safe Funnel Tracking

The React SDK provides type-safe funnel tracking for compile-time safety:

import {
  type FunnelMapping,
  useAltertable,
} from '@altertable/altertable-react';

interface CheckoutFunnelMapping extends FunnelMapping {
  checkout: [
    { name: 'Cart Viewed'; properties: { itemCount: number } },
    { name: 'Checkout Started'; properties: { cartValue: number } },
    { name: 'Purchase Completed'; properties: { orderId: string; amount: number } },
  ];
}

function CheckoutPage() {
  const { selectFunnel } = useAltertable<CheckoutFunnelMapping>();
  const { trackStep } = selectFunnel('checkout');

  function handleCartView(itemCount: number) {
    trackStep('Cart Viewed', { itemCount });
  }

  function handleCheckoutStart(cartValue: number) {
    trackStep('Checkout Started', { cartValue });
  }

  function handlePurchaseComplete(orderId: string, amount: number) {
    trackStep('Purchase Completed', { orderId, amount });
  }

  return (
    <div>
      {/* Your checkout UI */}
    </div>
  );
}

This ensures that:

• Funnel step names are validated at compile time
• Required properties are type-checked
• You get autocomplete for step names and properties

Using the API Directly

You can also send events directly to the API using HTTP requests.

Endpoint

POST https://api.altertable.ai/track

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Format

{
  "event": "Button Clicked",
  "properties": {
    "button_name": "Sign Up",
    "location": "header"
  },
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "timestamp": "2025-01-15T10:30:00Z"
}

Example Request

curl -X POST https://api.altertable.ai/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Purchase Completed",
    "properties": {
      "product_id": "prod_123",
      "amount": 99.99,
      "currency": "USD"
    },
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw"
  }'

Response

The API returns 200 OK on successful event tracking:

{
  "success": true
}

Event Properties

Event properties are stored as JSON in the main.events table and can be queried using SQL:

SELECT
  event,
  properties->>'button_name' as button_name,
  COUNT(*) as count
FROM altertable.main.events
WHERE event = 'Button Clicked'
GROUP BY ALL;

Best Practices

• Use descriptive event names: Use clear, consistent naming like Button Clicked or Purchase Completed
• Identify users for better tracking: Use identify() to set user context in client-side code, or include distinct_id when tracking from server-side contexts
• Add relevant properties: Include properties that will be useful for filtering and analysis later
• Track key user actions: Focus on events that represent meaningful user actions (clicks, purchases, signups, etc.)
• Be consistent: Use the same event names and property keys across your application