Identify Users

Rybbit allows you to identify logged-in users and associate their activity with a persistent identity across devices and sessions. This enables powerful user-level analytics, including tracking user journeys, understanding retention, and personalizing experiences.

How It Works

By default, Rybbit assigns an anonymous ID to each visitor based on their device fingerprint. When you call identify(), you link this anonymous visitor to a known user ID, allowing you to:

• Track the same user across multiple devices
• Associate pre-login activity with the logged-in user
• Store user metadata (traits) like email, name, and custom fields
• View identified users in your dashboard with their real names

When a new alias is created (i.e., the first time identify() is called for a given device), Rybbit retroactively updates all past anonymous events from that device to include the identified user ID. This means pre-login pageviews and events are attributed to the user once they identify themselves.

Special Trait Fields

When identifying users, certain trait fields are treated specially by Rybbit:

You can also include any custom fields you need for segmentation and analysis.

Limits

• Traits size: Maximum 2KB per identify call. Traits are stored as JSON, so keep payloads concise.
• User ID length: Maximum 255 characters.

API Reference

window.rybbit.identify(userId, traits?)

Sets a custom user ID for tracking logged-in users across devices and sessions, with optional user traits (metadata).

• userId (String): The unique identifier for the user. This will be stored in localStorage and persist across browser sessions. Note: Custom user IDs are stored exactly as provided without any hashing or modification.
• traits (Object, Optional): An object containing user metadata like email, name, username, or any custom fields. This data is stored in Rybbit and can be used to identify users in the dashboard. Setting a trait to null removes it from the user's profile.

// Identify a user when they log in (without traits)
window.rybbit.identify("user_12345");

// Identify a user with traits (recommended)
window.rybbit.identify("user_12345", {
  username: "johndoe",           // Primary display name
  name: "John Doe",              // Fallback display name
  email: "john@example.com",
  plan: "premium",
  company: "Acme Inc"
});

// All subsequent events and pageviews will be associated with this user ID

window.rybbit.setTraits(traits)

Updates the traits for the currently identified user without re-identifying them. Useful for updating user properties after initial identification.

• traits (Object): An object containing user metadata. New traits are merged with existing traits. Setting a trait to null removes it from the user's profile.

// Update user traits after they upgrade their plan
window.rybbit.setTraits({
  plan: "enterprise",
  upgraded_at: "2024-01-15"
});

// Remove a trait by setting it to null
window.rybbit.setTraits({
  temporary_flag: null  // This trait will be removed
});

Note: You must call identify() before using setTraits(). If no user is identified, this will log a warning.

window.rybbit.clearUserId()

Clears the stored user ID. Useful when a user logs out.

// Clear user identification when user logs out
window.rybbit.clearUserId();

window.rybbit.getUserId()

Returns the currently set user ID, or null if none is set.

// Check if a user is identified
const currentUserId = window.rybbit.getUserId();
if (currentUserId) {
  console.log('Current user:', currentUserId);
} else {
  console.log('No user identified');
}

Important Notes

• Shared devices: If multiple users log in from the same device (same IP address and user agent), calling identify() with a new user ID updates the alias to point to the new user. Future events will be attributed to the most recently identified user. Past events that were already backfilled retain their original attribution.
• Cross-device tracking: Identifying the same user on different devices creates separate aliases. Events from each device are linked to the user independently via the identified_user_id field.
• Retroactive backfill: The backfill runs asynchronously when a new alias is first created. ClickHouse mutations may take a short time to propagate depending on table size. Subsequent identify() calls from the same device (even with a different user ID) do not re-backfill old events.
• clearUserId() behavior: Calling clearUserId() removes the user ID from localStorage so future events are anonymous. It does not delete the alias in the database or modify previously attributed events.

Complete Example

Here's a typical workflow for user identification:

// When user logs in
function handleLogin(userData) {
  // Set user identification with traits
  window.rybbit.identify(userData.id, {
    username: userData.username,
    name: userData.fullName,
    email: userData.email,
    plan: userData.plan
  });

  // Track login event
  window.rybbit.event("User Login", {
    method: "email"
  });
}

// When user upgrades their plan
function handlePlanUpgrade(newPlan) {
  // Update traits without re-identifying
  window.rybbit.setTraits({
    plan: newPlan,
    upgraded_at: new Date().toISOString()
  });

  // Track upgrade event
  window.rybbit.event("Plan Upgraded", {
    new_plan: newPlan
  });
}

// When user logs out
function handleLogout() {
  // Track logout event
  window.rybbit.event("User Logout");

  // Clear user identification
  window.rybbit.clearUserId();
}

// Check identification status
function checkUserStatus() {
  const userId = window.rybbit.getUserId();
  if (userId) {
    console.log("User is identified:", userId);
  } else {
    console.log("Anonymous user");
  }
}

Related Documentation:

• Track Events
• Behavior Analytics - Users Tab
• API - Sending Events