Skip to main content
Identity calls link anonymous visitors to known users, enabling cross-device attribution and complete customer journey tracking.

​
What is identify()

The identify() method associates a user ID with an anonymous visitor, creating a permanent link between all their activity before and after login. Web: 
datalyr.identify('user_123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'pro'
});
iOS: 
await DatalyrSDK.shared.identify("user_123", properties: [
    "email": "[email protected]",
    "name": "John Doe",
    "plan": "pro"
])
React Native: 
await Datalyr.identify('user_123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'pro'
});

​
When to Call identify()

Call identify() whenever you learn who the user is: After Signup 
// User completes registration
datalyr.identify(newUser.id, {
  email: newUser.email,
  name: newUser.name,
  signup_date: new Date().toISOString()
});
After Login 
// User logs in
datalyr.identify(user.id, {
  email: user.email,
  name: user.name,
  last_login: new Date().toISOString()
});
After Email Capture 
// User subscribes to newsletter
datalyr.identify(user.email, {
  email: user.email,
  subscribed: true,
  subscription_source: 'footer_signup'
});
On Page Load (Logged-In Users) 
// Restore identity on page load
if (currentUser) {
  datalyr.identify(currentUser.id, {
    email: currentUser.email,
    plan: currentUser.plan
  });
}

​
User ID Format

The user ID can be any string that uniquely identifies the user: Database ID: 
datalyr.identify('12345');
UUID: 
datalyr.identify('f47ac10b-58cc-4372-a567-0e02b2c3d479');
Email Address: 
datalyr.identify('[email protected]');
Custom Format: 
datalyr.identify('cus_abc123xyz');
Requirements:
  • Must be unique per user
  • Must be consistent across sessions and devices
  • Recommended: Use your database primary key
  • Max length: 255 characters

​
User Traits

Traits are optional properties that describe the user.

​
Standard Traits

Contact Information: 
datalyr.identify('user_123', {
  email: '[email protected]',
  phone: '+1-555-123-4567',
  name: 'John Doe',
  first_name: 'John',
  last_name: 'Doe'
});
Account Information: 
datalyr.identify('user_123', {
  plan: 'pro',
  mrr: 99,
  status: 'active',
  created_at: '2025-01-15T10:30:00Z',
  trial_end: '2025-02-15T10:30:00Z'
});
Company Information: 
datalyr.identify('user_123', {
  company: 'Acme Inc',
  company_size: '50-100',
  industry: 'SaaS',
  role: 'Engineering Manager'
});

​
Custom Traits

Add any traits relevant to your business: 
datalyr.identify('user_123', {
  // E-commerce
  lifetime_value: 1250.00,
  order_count: 12,
  favorite_category: 'Electronics',

  // SaaS
  seats: 25,
  integrations_enabled: ['slack', 'github'],
  onboarding_completed: true,

  // Media
  subscription_tier: 'premium',
  content_preferences: ['tech', 'business'],
  watch_time_minutes: 1250
});
Best Practices:
  • Use snake_case for trait names
  • Keep trait names consistent
  • Don’t include sensitive data (passwords, SSNs, credit cards)
  • Limit to 50 traits per call

​
Identity Resolution

When you call identify(), DATALYR creates a permanent link between the anonymous ID and user ID.

​
Before identify()

{
  "anonymous_id": "anon_abc123",
  "user_id": null,
  "distinct_id": "anon_abc123"
}
Events: 
Day 1, 10:00 AM - Page view (anon_abc123)
Day 1, 10:05 AM - Product viewed (anon_abc123)
Day 1, 10:10 AM - Add to cart (anon_abc123)

​
Call identify()

datalyr.identify('user_456', {
  email: '[email protected]'
});

​
After identify()

{
  "anonymous_id": "anon_abc123",
  "user_id": "user_456",
  "distinct_id": "user_456"
}
$identify Event Sent: 
{
  "event_name": "$identify",
  "anonymous_id": "anon_abc123",
  "user_id": "user_456",
  "previous_id": null,
  "traits": {
    "email": "[email protected]"
  },
  "identified_at": "2025-09-29T10:15:00.123Z"
}
All Events Now Linked: 
Day 1, 10:00 AM - Page view (user_456, was anon_abc123)
Day 1, 10:05 AM - Product viewed (user_456, was anon_abc123)
Day 1, 10:10 AM - Add to cart (user_456, was anon_abc123)
Day 1, 10:15 AM - Signup (user_456)
DATALYR retroactively links all past anonymous events to the user ID.

​
Cross-Device Attribution

Identity calls enable attribution across devices and browsers.

​
Example: Multi-Device Purchase Journey

Mobile Phone (Day 1): 
// User clicks Meta ad on phone
// anonymous_id: anon_mobile_123
// fbclid captured: abc123

// Browse products
datalyr.track('view_item', { product_id: 'SKU123' });

// Add to cart
datalyr.track('add_to_cart', { product_id: 'SKU123' });

// User leaves without purchasing
Desktop (Day 2): 
// User types URL directly on desktop
// anonymous_id: anon_desktop_456
// source: direct

// User logs in
datalyr.identify('user_789', {
  email: '[email protected]'
});
// DATALYR links anon_desktop_456 → user_789

// Complete purchase
datalyr.track('purchase', {
  order_id: 'ORDER123',
  revenue: 99.99
});
Mobile Phone (Day 3): 
// User opens app on phone again
// anonymous_id: anon_mobile_123

// User logs in
datalyr.identify('user_789');
// DATALYR links anon_mobile_123 → user_789
Result: DATALYR now knows all three anonymous IDs belong to user_789 and attributes the purchase to the original Meta ad (fbclid from Day 1).

​
Updating User Traits

Call identify() multiple times to update user traits: Initial Signup: 
datalyr.identify('user_123', {
  email: '[email protected]',
  plan: 'free',
  signup_date: '2025-09-01'
});
Upgrade to Pro: 
datalyr.identify('user_123', {
  plan: 'pro',
  upgrade_date: '2025-09-15',
  mrr: 99
});
Add Company Info: 
datalyr.identify('user_123', {
  company: 'Acme Inc',
  company_size: '50-100',
  role: 'Manager'
});
Traits are merged (new traits added, existing traits updated).

​
Reset Identity

Call reset() when a user logs out: Web: 
// User logs out
datalyr.reset();
iOS: 
await DatalyrSDK.shared.reset()
React Native: 
await Datalyr.reset();
What reset() does:
  • Clears user ID from storage
  • Keeps anonymous ID (device/browser still tracked)
  • Next events tracked as anonymous until next identify()
When to call reset():
  • User logs out
  • User switches accounts
  • Session ends

​
Server-Side Identification

Identify users from your backend: 
// Node.js
await fetch('https://ingest.datalyr.com/events', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    workspaceId: 'ws_123',
    events: [{
      event_name: '$identify',
      anonymous_id: 'anon_abc123', // From client
      user_id: 'user_456',
      properties: {
        email: '[email protected]',
        plan: 'pro',
        mrr: 99
      },
      timestamp: new Date().toISOString()
    }]
  })
});
Getting anonymous_id: 
// Client sends anonymous_id to server
const anonymousId = datalyr.getAnonymousId();

await fetch('/api/signup', {
  method: 'POST',
  body: JSON.stringify({
    email: '[email protected]',
    anonymous_id: anonymousId // Send to server
  })
});

// Server receives and uses it
app.post('/api/signup', async (req, res) => {
  const { email, anonymous_id } = req.body;

  // Create user in database
  const user = await createUser(email);

  // Send identify event to DATALYR
  await identifyUser(user.id, anonymous_id, {
    email: user.email
  });
});

​
Identity Best Practices

Call identify() early and often 
// Good: Call on every page for logged-in users
if (currentUser) {
  datalyr.identify(currentUser.id);
}

// Bad: Only calling once during signup
// (Users will be anonymous after page reload)
Use consistent user IDs 
// Good: Same ID across all platforms
datalyr.identify('user_123');        // Web
DatalyrSDK.shared.identify("user_123") // iOS
Datalyr.identify('user_123');        // React Native

// Bad: Different IDs per platform
// (DATALYR won't link them together)
Include email in traits 
// Good: Email helps with Meta/Google enhanced matching
datalyr.identify('user_123', {
  email: '[email protected]'
});

// OK: Works but no enhanced matching
datalyr.identify('user_123');
Don’t identify anonymous users 
// Bad: Don't call identify() without a real user ID
datalyr.identify(anonymousId); // NO!

// Good: Only call when you know who the user is
if (userId) {
  datalyr.identify(userId);
}
Hash sensitive data 
// Bad: Don't send passwords or SSNs
datalyr.identify('user_123', {
  password: 'secret123' // DON'T DO THIS
});

// Good: Only send safe user attributes
datalyr.identify('user_123', {
  email: '[email protected]',
  plan: 'pro'
});

​
Troubleshooting

identify() not working? Check:
  • User ID is non-empty string
  • localStorage is available
  • No errors in console
  • Events appear in dashboard
Users not linked across devices? Ensure:
  • Same user ID used on all devices
  • identify() called after login on each device
  • User ID is consistent (not session-specific)
Traits not updating? Verify:
  • identify() called with new traits
  • Traits are valid JSON types (string, number, boolean, array)
  • Not exceeding 50 traits per call
Previous events not linked? This is expected. DATALYR links:
  • All events from same anonymous_id → user_id
  • Does NOT link events from different anonymous IDs unless both are identified with same user_id

​
Next Steps

Visitor Identification

Understand anonymous IDs

Events Overview

Learn about event tracking

Properties and Metadata

Add context to events

Cross-Domain Tracking

Track across domains

​
Need Help?

Questions about identity calls? Check our troubleshooting guide or contact support.