Skip to main content
Associates SDK activity with your own user IDs. Call this method when you have a user’s identity (after login, signup, or session restoration).

​
Signature

function identify(userId: string, attributes?: UserAttributes): void

​
Parameters

​
userId
string
required
Your application’s unique identifier for this user. This replaces the anonymous ID.
userId: 'user-123'
​
attributes
UserAttributes
Optional user attributes for targeting and personalization. See setUserAttributes() for complete list.
attributes: {
  email: 'user@example.com',
  subscriptionTier: 'free'
}

​
Return Value

Type: void The method doesn’t return a value.

​
Behavior

When you call identify():
  1. Replaces the anonymous ID with your provided user ID
  2. Optionally sets user attributes in the same call
  3. Clears cached entitlements when user ID changes
  4. Updates all internal managers with the new user ID

​
Examples

​
Basic Identification

import Encore from '@encore/web-sdk';

// After user logs in
Encore.identify('user-123');

​
Identify with Attributes

import Encore from '@encore/web-sdk';

Encore.identify('user-123', {
  email: 'user@example.com',
  subscriptionTier: 'free',
  firstName: 'John',
  lastName: 'Doe'
});

​
After Login

async function handleLogin(credentials) {
  try {
    const user = await loginUser(credentials);
    
    // Identify user with Encore
    Encore.identify(user.id, {
      email: user.email,
      subscriptionTier: user.subscription.tier
    });
    
    return user;
  } catch (error) {
    console.error('Login failed:', error);
  }
}

​
After Signup

async function handleSignup(userData) {
  try {
    const user = await createUser(userData);
    
    // Identify new user
    Encore.identify(user.id, {
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      subscriptionTier: 'free'
    });
    
    return user;
  } catch (error) {
    console.error('Signup failed:', error);
  }
}

​
On Page Load (Session Restoration)

import Encore from '@encore/web-sdk';

// Check if user is already logged in
const currentUser = getCurrentUserFromSession();

if (currentUser) {
  Encore.identify(currentUser.id, {
    email: currentUser.email,
    subscriptionTier: currentUser.subscription
  });
}

​
Framework Integration

  • React
  • Vue
  • Angular
import { useEffect } from 'react';
import Encore from '@encore/web-sdk';
import { useAuth } from './hooks/useAuth';

function App() {
  const { user } = useAuth();
  
  useEffect(() => {
    if (user) {
      Encore.identify(user.id, {
        email: user.email,
        subscriptionTier: user.subscriptionTier
      });
    }
  }, [user]);
  
  return <YourApp />;
}

​
When to Call identify()

1

After Login

When a user successfully authenticates:
async function login(email, password) {
  const user = await authenticateUser(email, password);
  Encore.identify(user.id);
  return user;
}
2

After Signup

When a new user creates an account:
async function signup(userData) {
  const user = await createAccount(userData);
  Encore.identify(user.id, {
    email: user.email,
    firstName: user.firstName
  });
  return user;
}
3

On App Initialization

If you already have the user’s session:
document.addEventListener('DOMContentLoaded', () => {
  const user = getSessionUser();
  if (user) {
    Encore.identify(user.id);
  }
});
4

After OAuth/SSO

When a user logs in via OAuth or SSO:
async function handleOAuthCallback(code) {
  const user = await exchangeCodeForUser(code);
  Encore.identify(user.id, {
    email: user.email,
    custom: { authProvider: 'google' }
  });
  return user;
}

​
Best Practices

​
1. Identify Early

Identify users as soon as you have their ID: 
// Good
async function handleLogin(credentials) {
  const user = await login(credentials);
  Encore.identify(user.id); // ✅ Immediate
  return user;
}

​
2. Include Useful Attributes

Set helpful attributes during identification: 
// Better
Encore.identify('user-123', {
  email: 'user@example.com',
  subscriptionTier: 'free',
  custom: {
    signupDate: user.createdAt,
    referralSource: user.source
  }
});

// vs Basic
Encore.identify('user-123'); // ✓ Works, but less useful

​
3. Don’t Call Multiple Times

Only identify when the user changes: 
// Good
if (currentUserId !== newUserId) {
  Encore.identify(newUserId);
}

// Avoid
Encore.identify(userId); // On every render

​
4. Handle User Switching

Reset before identifying a different user: 
async function switchAccount(newUserId) {
  // Clear previous user
  Encore.reset();
  
  // Identify new user
  const user = await loadUserData(newUserId);
  Encore.identify(user.id, {
    email: user.email
  });
}

​
Utility Methods

​
getCurrentUserId()

Get the current user ID (identified or anonymous): 
const userId = Encore.getCurrentUserId();
console.log('Current user:', userId);
// "user-123" or auto-generated UUID
This returns:
  • Your custom user ID if identify() was called
  • Auto-generated anonymous UUID otherwise
  • null if SDK hasn’t initialized yet

​
Complete Example

import Encore from '@encore/web-sdk';

class AuthManager {
  async login(email, password) {
    try {
      // Authenticate user
      const user = await this.authenticateUser(email, password);
      
      // Store session
      this.storeSession(user);
      
      // Identify with Encore
      Encore.identify(user.id, {
        email: user.email,
        subscriptionTier: user.subscription.tier,
        firstName: user.firstName,
        lastName: user.lastName,
        custom: {
          loginMethod: 'password',
          lastLogin: new Date().toISOString()
        }
      });
      
      return user;
    } catch (error) {
      console.error('Login failed:', error);
      throw error;
    }
  }
  
  async signup(userData) {
    try {
      // Create user account
      const user = await this.createUser(userData);
      
      // Store session
      this.storeSession(user);
      
      // Identify with Encore
      Encore.identify(user.id, {
        email: user.email,
        firstName: userData.firstName,
        lastName: userData.lastName,
        subscriptionTier: 'free',
        custom: {
          signupDate: new Date().toISOString(),
          signupMethod: 'email'
        }
      });
      
      return user;
    } catch (error) {
      console.error('Signup failed:', error);
      throw error;
    }
  }
  
  logout() {
    // Clear app session
    this.clearSession();
    
    // Reset Encore
    Encore.reset();
    
    // Redirect
    window.location.href = '/login';
  }
  
  restoreSession() {
    const user = this.getSessionUser();
    
    if (user) {
      Encore.identify(user.id, {
        email: user.email,
        subscriptionTier: user.subscription.tier
      });
    }
  }
}

// Usage
const auth = new AuthManager();

// On app load
auth.restoreSession();

// On login
await auth.login('user@example.com', 'password');

// On signup
await auth.signup({ email: 'new@example.com', ... });

// On logout
auth.logout();

​
Next Steps

After identifying users: