Home User activities Integrate User Identification with Crowd

Integrate User Identification with Crowd

Last updated on May 27, 2025

Discover personalized insights with Crowd’s user identification! Transform anonymous clicks into a rich, unified user profile that powers your app’s analytics.
This article will walk you through seamlessly integrating Crowd’s identification into your application or website, connecting every visit, event, session recording, and heatmap to a single, actionable profile, starting the moment a user signs up, logs in, or is recognized.

1. Why Identify Users?

Integrating user identification links pre-login (anonymous) activities to post-login (identified) profiles in your app, enabling:

  • A unified view of user behavior in funnels, cohorts, and dashboards.

  • Accurate session recordings and heatmaps tied to a single user.

2. Methods to Integrate Identification

2.1 Identify with JavaScript

Use the crowd.identify() method to identify users dynamically in your application.

crowd.identify("user_123", {
  email: "jane@acme.com",
  plan: "pro",           // String
  is_admin: false,       // Boolean
  signup_at: 1704067200000,  // Number (epoch ms)
  name: "Janet Jackson"
});

  • When to Call: Once per session, ideally after login or signup.

  • Key Notes:

    • Crowd automatically deduplicates multiple calls.

    • Pass stable traits (e.g., plan, is_admin). Volatile data should be tracked as events.

  • Logout or Account Switch:

    crowd.reset();

    • crowd.reset() clears the Crowd cookie and assigns a new anonymous ID (anon_), preventing profile merging on shared devices.

    • Always call reset() on logout to avoid mixing events between accounts.

2.2 Identify with HTML Attribute (No JavaScript Build)

For static sites without JavaScript builds, use the data-crowd-user attribute.

<meta data-crowd-user='{"id":"user_123","email":"jane@acme.com"}'>

  • How It Works: The Crowd SDK automatically detects this attribute on page load and runs identify() for you.

  • Use Case: Ideal for basic identification on simple websites.

2.3 Identify with Server-Side / cURL

Use this method when a backend process (e.g., OAuth callback) identifies the user first.

curl -X POST https://api.crowd.com/identify \
  -H "Content-Type: application/json" \
  -H "X-Crowd-Key: YOUR_SERVER_KEY" \
  -d '{
        "website": "YOUR_PUBLIC_ID",
        "user_id": "user_123",
        "traits": {"plan": "pro"},
        "timestamp": "2025-05-20T14:16:00Z"
      }'

  • How It Works: Crowd merges existing anonymous sessions (same browser fingerprint) into the identified profile (user_123).

  • Use Case: Useful for server-side user identification in your app.

3. Verify Identification in Crowd

To confirm the integration worked:

  1. Go to User activities > Users in the Crowd dashboard.

  2. Refresh and search for the user ID (e.g., user_123).

  3. The user profile should now include pre-login events merged from its former anonymous identity (anon_).

4. Best Practices

  • Use a Durable Key: Use a stable identifier (e.g., database ID or UUID) as the user_id, not an email, which may change.

  • Always Reset on Logout: Call crowd.reset() on logout or account switch to prevent cross-account mixing on shared devices.

  • Send Key Traits Consistently: Include essential traits (e.g., plan, country) in every identify() call—Crowd will upsert them.

  • Avoid Unnecessary PII: Don’t send sensitive data (e.g., full addresses); hash data if required for compliance.

5. Next Steps

After integrating identification, set up events to track user actions and create funnels. Refer to the Track an Event in Crowd - Quick Start Guide and the Creating Funnels on Crowd guide for details.

For further assistance, check the full API reference or contact support via the in-app chat.

6. Troubleshooting

  • No user appears after identify().
    Symptom: No user appears after calling identify().
    Likely cause: This might be due to a wrong projectId or an ad-blocker blocking the endpoint.
    Fix: Check the snippet ID and whitelist api.crowd.com.

  • Two accounts merged.
    Symptom: Two accounts are merged.
    Likely cause: This is likely because reset() was not called on logout.
    Fix: Add crowd.reset() before redirecting to the login page.

  • Traits missing.
    Symptom: Traits are missing.
    Likely cause: This could be caused by mixed types across calls (e.g., plan as string then number).
    Fix: Keep trait types consistent, as the last write wins.

  • 401 on API call.
    Symptom: You get a 401 on an API call.
    Likely cause: It’s probably because the X-Crowd-Key header is missing.
    Fix: Use a server key for backend requests.

5. Glossary

  • anon_xxx: Temporary ID assigned to a user on their first visit.

  • user_: Stable ID you provide during identification.*

  • crowd.reset(): Clears the cookie and starts a new anonymous ID—use on logout or account switch.