Identifying Users

User identification links events to specific users, enabling user-level analysis, cohort building, and cross-session tracking. When you identify a user, their events are associated with a consistent user ID.

Why Identify Users?

Identifying users allows you to:

• Track user journeys: Follow individual users across sessions and devices
• Build user profiles: Aggregate all events and properties for a specific user
• Create cohorts: Segment users based on behavior and attributes
• Analyze retention: Measure how users return over time (coming soon)

Using the SDK

See the SDKs guide for installation and setup instructions.

JavaScript SDK

Identifying Users

Use altertable.identify() to identify a user with their ID and optional traits:

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

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

// Identify a user with traits
altertable.identify('u_01jza857w4f23s1hf2s61befmw', {
  email: 'john.doe@example.com',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
  plan: 'premium',
  signup_date: '2025-01-15',
});

Updating User Traits

Use altertable.updateTraits() to update user traits without providing the user ID again:

// Update traits for the current user
altertable.updateTraits({
  onboarding_completed: true,
  plan: 'enterprise',
});

Session Management

Use altertable.reset() to reset the current identity context so future events are not associated with the previous user:

// Reset everything except device ID (default)
altertable.reset();

// Reset all IDs including device ID
altertable.reset({
  resetDeviceId: true,
});

When to reset:

• On logout: Reset the identity context so events aren't associated with the previous user
• Privacy compliance: Reset when users clear their data or revoke consent

React SDK

Identifying Users

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

altertable.init('YOUR_API_KEY');

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

function LoginPage() {
  const { identify, updateTraits, reset } = useAltertable();

  function handleLogin(userId: string, email: string, name: string) {
    // Identify the user after login
    identify(userId, {
      email,
      name,
      plan: 'free',
    });
  }

  function handleUpgrade() {
    // Update traits when user upgrades
    updateTraits({
      plan: 'premium',
      upgrade_date: new Date().toISOString(),
    });
  }

  function handleLogout() {
    // Reset session on logout
    reset();
  }

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

Using the API Directly

Endpoint

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

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Format

{
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "traits": {
    "email": "user@example.com",
    "name": "John Doe",
    "plan": "premium",
    "signup_date": "2025-01-01"
  }
}

Example Request

curl -X POST https://api.altertable.ai/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
    "traits": {
      "email": "user@example.com",
      "name": "John Doe",
      "plan": "premium"
    }
  }'

Response

The API returns 200 OK on successful identification:

User Traits

User traits (properties) are stored in the main.identities table and can be queried using SQL:

SELECT
  distinct_id,
  traits->>'email' as email,
  traits->>'plan' as plan,
  updated_at
FROM altertable.main.identities
WHERE distinct_id = 'u_01jza857w4f23s1hf2s61befmw';

Anonymous Users

You can track events without identifying users. Altertable automatically assigns a distinct_id (visitor ID format) to anonymous users:

// Track event without identifying - distinct_id is automatically assigned
altertable.track('Page Viewed', {
  page: '/home',
});

When you call identify(), the SDK automatically links the anonymous visitor ID to the user ID. The previous distinct_id becomes the anonymous_id in the identify payload, enabling you to connect pre-login behavior to the authenticated user.

Best Practices

• Identify on login: Call identify immediately after a user authenticates
• Use stable user IDs: Use your application's user ID, not email addresses or other changeable identifiers
• Include key traits: Add properties that are useful for segmentation (plan, signup date, etc.)
• Update traits regularly: Keep user properties up to date as they change
• Don't include sensitive data: Avoid storing passwords, credit card numbers, or other sensitive information in traits

Querying User Data

Combine events and identities to analyze user behavior:

-- Get all events for a specific user
SELECT
  e.event,
  e.properties,
  e.timestamp,
  i.traits->>'email' as email,
  i.traits->>'plan' as plan
FROM altertable.main.events e
LEFT JOIN altertable.main.identities i ON e.distinct_id = i.distinct_id
WHERE e.distinct_id = 'u_01jza857w4f23s1hf2s61befmw'
ORDER BY e.timestamp DESC;