Identify Users

Link anonymous visitors to known users so every event, from first page view to final purchase, is attributed to a single person.

Overview

Kitbase tracks users with two identifiers:

Before identification, all events are linked to the auto-generated anonymous ID. After identify() is called, the SDK sends a request to POST /sdk/v1/identify (authenticated with your SDK key), and subsequent events are attributed to the real user. The server also backfills past anonymous events so nothing is lost.

How It Works

1. User visits site      anonymous_id generated (UUID, stored in localStorage)
2. User browses          events tracked with anonymous_id only
3. User logs in          identify(userId, traits) called
4. SDK sends request     server links anonymous_id to user_id
5. Server backfills      previous anonymous events now attributed to user
6. Subsequent events     include both anonymous_id and user_id

Basic Usage

Call identify() immediately after the user authenticates:

// After user logs in
await kitbase.identify({
  userId: 'user_123',
  traits: {
    email: 'jane@example.com',
    name: 'Jane Doe',
    plan: 'premium',
    company: 'Acme Inc'
  }
});

Identify Options

interface IdentifyOptions {
  userId: string;                       // Required: your unique user identifier
  traits?: Record<string, unknown>;     // Optional: user properties
}

Traits can include any key-value pairs. Common examples:

When to Call identify()

Call identify() immediately after any of these events:

• After login (email/password, OAuth, magic link)
• After signup (new account creation)
• After OAuth callback (Google, GitHub, etc.)
• On app load when the user is already authenticated (check your auth state)

// After OAuth login
async function handleOAuthCallback(user) {
  await kitbase.identify({
    userId: user.id,
    traits: {
      email: user.email,
      name: user.name,
      provider: 'google'
    }
  });
}

// On app load if already authenticated
if (currentUser) {
  await kitbase.identify({
    userId: currentUser.id,
    traits: {
      email: currentUser.email,
      plan: currentUser.plan
    }
  });
}

Anonymous ID Management

Retrieve the current identifiers at any time:

kitbase.getAnonymousId();  // Returns current anonymous UUID
kitbase.getUserId();       // Returns user_id if identified, null otherwise

Storage Options

The anonymous ID is persisted across page reloads. You can configure how and where it is stored:

// Default: localStorage
const kitbase = init({
  sdkKey: '<YOUR_SDK_KEY>',
  storage: localStorage
});

// Custom storage (must implement getItem / setItem / removeItem)
const kitbase = init({
  sdkKey: '<YOUR_SDK_KEY>',
  storage: myCustomStorage
});

// No persistence (new anonymous ID generated each session)
const kitbase = init({
  sdkKey: '<YOUR_SDK_KEY>',
  storage: null
});

Reset Identity

Clear the current user and start a fresh anonymous session:

kitbase.reset();
// Clears user_id, generates a new anonymous_id, starts a new session

Use reset() when:

• The user logs out
• The user switches accounts

async function handleLogout() {
  await authService.logout();
  kitbase.reset(); // Start tracking as a new anonymous user
}

Multi-Device Support

When the same person uses your app on multiple devices:

• Each device generates its own anonymous_id
• Calling identify() with the same userId on each device links all activity to one user
• Events from every device are attributed to the same user profile

// Device A: anonymous_id = "aaa-111"
await kitbase.identify({ userId: 'user_123' });
// -> aaa-111 linked to user_123

// Device B: anonymous_id = "bbb-222"
await kitbase.identify({ userId: 'user_123' });
// -> bbb-222 also linked to user_123

// All events from both devices are now attributed to user_123

Server-Side Behavior

When identify() is called, the following happens on the server:

1. The SDK sends POST /sdk/v1/identify with { userId, anonymousId, traits }
2. The server creates a link between the anonymous_id and the user_id
3. The server backfills user_id on all past events matching that anonymous_id in ClickHouse
4. The server responds with:

{
  "success": true,
  "userId": "user_123",
  "previouslyLinked": false
}

REST API (Direct)

You can call the identify endpoint directly without the SDK:

curl -X POST https://ingest.kitbase.dev/sdk/v1/identify \
  -H "x-sdk-key: YOUR_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "anonymous_id": "550e8400-e29b-41d4-a716-446655440000",
    "traits": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    }
  }'

Best Practices

Use consistent user IDs

Always use the same identifier format for a given user. Database IDs or UUIDs work well:

// Good: consistent database ID
await kitbase.identify({ userId: user.id });

// Bad: mixing formats across your app
await kitbase.identify({ userId: user.email });   // email in one place
await kitbase.identify({ userId: String(user.id) }); // numeric ID elsewhere

Avoid PII as user IDs

Do not use personally identifiable information (email addresses, phone numbers) as the userId. Use opaque database IDs instead, and pass PII as traits:

// Good
await kitbase.identify({
  userId: 'usr_8f3a2b',
  traits: { email: 'jane@example.com' }
});

// Bad
await kitbase.identify({
  userId: 'jane@example.com'
});

Update traits when the profile changes

Call identify() again whenever user properties change (plan upgrade, name update, etc.) to keep traits current:

async function handlePlanUpgrade(newPlan: string) {
  await billingService.upgrade(newPlan);

  await kitbase.identify({
    userId: currentUser.id,
    traits: {
      plan: newPlan,
      upgraded_at: new Date().toISOString()
    }
  });
}

Call reset() on logout

Always call reset() when a user logs out to prevent the next user on a shared device from inheriting the previous identity:

async function handleLogout() {
  await authService.logout();
  kitbase.reset();
}

Identify as early as possible

Place your identify() call at the earliest point after authentication. The longer you wait, the more events are tracked without a user_id.

Next steps

• Users dashboard guide profiles, traits, and identity resolution in the dashboard.
• Track Events send custom events for your identified users.
• JavaScript SDK identity API identify(), getAnonymousId(), reset().