Identity Calls

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.

Introduction

Getting Started

Installation

Container & Tag Management

Understanding Your Data

Integrations

Features

Account & Billing

SDKs & Developer Tools

Troubleshooting

What is identify()

When to Call identify()

User ID Format

User Traits

Standard Traits

Custom Traits

Identity Resolution

Before identify()

Call identify()

After identify()

Cross-Device Attribution

Example: Multi-Device Purchase Journey

Updating User Traits

Reset Identity

Server-Side Identification

Identity Best Practices

Troubleshooting

Next Steps

Visitor Identification

Events Overview

Properties and Metadata

Cross-Domain Tracking

Need Help?

Introduction

Getting Started

Installation

Container & Tag Management

Understanding Your Data

Integrations

Features

Account & Billing

SDKs & Developer Tools

Troubleshooting

Documentation Index

​What is identify()

​When to Call identify()

​User ID Format

​User Traits

​Standard Traits

​Custom Traits

​Identity Resolution

​Before identify()

​Call identify()

​After identify()

​Cross-Device Attribution

​Example: Multi-Device Purchase Journey

​Updating User Traits

​Reset Identity

​Server-Side Identification

​Identity Best Practices

​Troubleshooting

​Next Steps

Visitor Identification

Events Overview

Properties and Metadata

Cross-Domain Tracking

​Need Help?

What is identify()

When to Call identify()

User ID Format

User Traits

Standard Traits

Custom Traits

Identity Resolution

Before identify()

Call identify()

After identify()

Cross-Device Attribution

Example: Multi-Device Purchase Journey

Updating User Traits

Reset Identity

Server-Side Identification

Identity Best Practices

Troubleshooting

Next Steps

Need Help?