Skip to main content
Identifying users, setting attributes, and managing identity in your web application.

​
Overview

Encore requires user identification to track entitlements and prevent abuse across devices. You can also set user attributes to enable targeted offers and personalization.

​
Anonymous Users

Encore automatically generates a random user ID that persists in localStorage until the user clears their browser data or you call reset(). This anonymous ID allows entitlement tracking to work immediately without requiring explicit user identification. The auto-generated ID is a standard UUID (e.g., 550e8400-e29b-41d4-a716-446655440000). 
import Encore from '@encore/web-sdk';

// Configure SDK
Encore.configure({ apiKey: 'pk_your_api_key_here' });

// Get auto-generated user ID
const userId = Encore.getCurrentUserId();
console.log('User ID:', userId); // UUID format
The anonymous ID is stored in localStorage with a fallback to sessionStorage if localStorage is unavailable.

​
Identified Users

If you use your own user management system, call identify() when you have a user’s identity: 
// After user logs in or signs up
Encore.identify('user-123');

​
When to Identify Users

Call identify() at these key moments:
  • After login - When a user successfully authenticates
  • After signup - When a new user creates an account
  • On page load - If you already have the user’s ID from session/cookies
  • After authentication check - When restoring a user session
  • React
  • Vue
  • Angular
  • Svelte
  • Vanilla JS
import { useEffect } from 'react';
import Encore from '@encorekit/web-sdk';

function App() {
  useEffect(() => {
    // Check if user is logged in
    const user = getCurrentUser(); // Your auth function
    
    if (user) {
      Encore.identify(user.id, {
        email: user.email,
        subscriptionTier: user.tier
      });
    }
  }, []);
  
  return <YourApp />;
}

​
Identify with Attributes

You can set user attributes while identifying: 
Encore.identify('user-123', {
  email: 'user@example.com',
  subscriptionTier: 'free',
  firstName: 'John',
  lastName: 'Doe'
});
Identifying users enables cross-device entitlement tracking and allows for more targeted offer personalization.

​
User Attributes

Set user attributes for offer targeting and personalization. Attributes are merged with existing ones, not replaced.

​
Setting Attributes

Encore.setUserAttributes({
  // Identity
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  phoneNumber: '+1-555-0123',
  
  // Location
  city: 'San Francisco',
  state: 'CA',
  postalCode: '94102',
  countryCode: 'US',
  
  // Subscription
  subscriptionTier: 'free',
  monthsSubscribed: '6',
  billingCycle: 'monthly',
  
  // Custom attributes
  custom: {
    accountType: 'business',
    referralSource: 'google'
  }
});

​
Supported Attributes

{
  email?: string
  firstName?: string
  lastName?: string
  phoneNumber?: string
}
Example:
Encore.setUserAttributes({
  email: 'john@example.com',
  firstName: 'John',
  lastName: 'Doe'
});

{
  postalCode?: string
  city?: string
  state?: string
  countryCode?: string
  latitude?: string
  longitude?: string
}
Example:
Encore.setUserAttributes({
  city: 'New York',
  state: 'NY',
  countryCode: 'US',
  postalCode: '10001'
});

{
  dateOfBirth?: string  // ISO 8601 format
  gender?: string
  language?: string
}
Example:
Encore.setUserAttributes({
  dateOfBirth: '1990-01-15',
  gender: 'male',
  language: 'en'
});

{
  subscriptionTier?: string
  monthsSubscribed?: string
  billingCycle?: string
  lastPaymentAmount?: string
}
Example:
Encore.setUserAttributes({
  subscriptionTier: 'premium',
  monthsSubscribed: '12',
  billingCycle: 'annual',
  lastPaymentAmount: '99.99'
});

{
  lastActiveDate?: string  // ISO 8601 format
  totalSessions?: string
}
Example:
Encore.setUserAttributes({
  lastActiveDate: new Date().toISOString(),
  totalSessions: '150'
});

{
  custom?: Record<string, string>
}
Example:
Encore.setUserAttributes({
  custom: {
    accountType: 'business',
    referralSource: 'google',
    betaTester: 'true',
    preferredLanguage: 'es'
  }
});

​
Getting Attributes

Retrieve currently set user attributes: 
const attributes = Encore.getUserAttributes();
console.log('User attributes:', attributes);

​
Updating Attributes

Attributes are merged, so you can update them incrementally: 
// Set initial attributes
Encore.setUserAttributes({
  subscriptionTier: 'free',
  monthsSubscribed: '0'
});

// Later, update specific attributes
Encore.setUserAttributes({
  monthsSubscribed: '6',
  custom: { featureUsage: 'high' }
});

// Previous subscriptionTier is still set

​
Reset SDK

Clear user identity, attributes, cached entitlements, and signal queue. This generates a new anonymous ID. 
Encore.reset();

​
When to Reset

Call reset() when:
  • User logs out - Clear all user-specific data
  • Switching accounts - When a different user logs in
  • Testing - To start fresh during development
  • React
  • Vue
  • Vanilla JS
import Encore from '@encore/web-sdk';

function LogoutButton() {
  const handleLogout = async () => {
    // Clear your app's session
    await logoutUser();
    
    // Reset Encore SDK
    Encore.reset();
    
    // Redirect to login
    window.location.href = '/login';
  };
  
  return <button onClick={handleLogout}>Logout</button>;
}
reset() clears all cached entitlements, queued signals, and user data. The user will lose any provisional entitlements that haven’t been verified.

​
Best Practices

​
1. Identify Early

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

​
2. Set Attributes Incrementally

You don’t need to set all attributes at once: 
// During signup
Encore.identify(user.id, {
  email: user.email,
  subscriptionTier: 'free'
});

// Later, after onboarding
Encore.setUserAttributes({
  firstName: user.firstName,
  lastName: user.lastName
});

// After subscription purchase
Encore.setUserAttributes({
  subscriptionTier: 'premium',
  billingCycle: 'monthly'
});

​
3. Keep Attributes Updated

Update attributes when they change: 
// When user upgrades subscription
function handleSubscriptionUpgrade(newTier) {
  Encore.setUserAttributes({
    subscriptionTier: newTier,
    lastPaymentAmount: getSubscriptionPrice(newTier)
  });
}

​
4. Use Custom Attributes

Leverage custom attributes for app-specific data: 
Encore.setUserAttributes({
  custom: {
    accountAge: calculateAccountAge(user.createdAt),
    lifetimeValue: calculateLTV(user),
    churnRisk: predictChurnRisk(user)
  }
});

​
Complete Example

Here’s a complete user management flow: 
import Encore from '@encore/web-sdk';

// Initialize SDK
Encore.configure({ apiKey: 'pk_your_api_key_here' });

// After user signup
async function handleSignup(userData) {
  const user = await createUser(userData);
  
  // Identify user with initial attributes
  Encore.identify(user.id, {
    email: user.email,
    subscriptionTier: 'free',
    firstName: user.firstName,
    lastName: user.lastName
  });
}

// After user login
async function handleLogin(credentials) {
  const user = await authenticateUser(credentials);
  
  // Identify returning user
  Encore.identify(user.id);
  
  // Update engagement attributes
  Encore.setUserAttributes({
    lastActiveDate: new Date().toISOString(),
    totalSessions: String(user.sessionCount + 1)
  });
}

// When user updates profile
function handleProfileUpdate(updates) {
  Encore.setUserAttributes({
    firstName: updates.firstName,
    lastName: updates.lastName,
    city: updates.city,
    state: updates.state
  });
}

// When user upgrades subscription
function handleSubscriptionUpgrade(plan) {
  Encore.setUserAttributes({
    subscriptionTier: plan.tier,
    billingCycle: plan.cycle,
    monthsSubscribed: '0' // Just upgraded
  });
}

// When user logs out
function handleLogout() {
  // Clear your session
  clearAppSession();
  
  // Reset Encore
  Encore.reset();
  
  // Redirect
  window.location.href = '/login';
}

​
Next Steps

Now that you understand user management, you’re ready to: For complete API documentation, see the SDK Reference.