identify()

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():

Replaces the anonymous ID with your provided user ID
Optionally sets user attributes in the same call
Clears cached entitlements when user ID changes
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'
});

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);
  }
}

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 />;
}

<script setup>
import { watch } from 'vue';
import Encore from '@encore/web-sdk';
import { useAuthStore } from './stores/auth';

const authStore = useAuthStore();

watch(
  () => authStore.user,
  (user) => {
    if (user) {
      Encore.identify(user.id, {
        email: user.email,
        subscriptionTier: user.subscriptionTier
      });
    }
  },
  { immediate: true }
);
</script>

import { Component, OnInit } from '@angular/core';
import { AuthService } from './services/auth.service';
import Encore from '@encore/web-sdk';

@Component({
  selector: 'app-root',
  template: '<router-outlet></router-outlet>'
})
export class AppComponent implements OnInit {
  constructor(private authService: AuthService) {}
  
  ngOnInit() {
    this.authService.user$.subscribe(user => {
      if (user) {
        Encore.identify(user.id, {
          email: user.email,
          subscriptionTier: user.subscriptionTier
        });
      }
    });
  }
}

When to Call identify()

After Login

When a user successfully authenticates:

async function login(email, password) {
  const user = await authenticateUser(email, password);
  Encore.identify(user.id);
  return user;
}

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;
}

On App Initialization

If you already have the user’s session:

document.addEventListener('DOMContentLoaded', () => {
  const user = getSessionUser();
  if (user) {
    Encore.identify(user.id);
  }
});

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
  });
}

getCurrentUserId() - Get the current user ID
setUserAttributes() - Update attributes later
reset() - Clear user identity

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:

setUserAttributes() - Update attributes over time
presentOffer() - Show targeted offers
isActive() - Check entitlements

Getting Started

iOS SDK

Web SDK

Signature

Parameters

Return Value

Behavior

Examples

Basic Identification

Identify with Attributes

On Page Load (Session Restoration)

Framework Integration

When to Call identify()

Best Practices

1. Identify Early

2. Include Useful Attributes

3. Don’t Call Multiple Times

4. Handle User Switching

Utility Methods

getCurrentUserId()

Complete Example

Next Steps

Getting Started

iOS SDK

Web SDK

​Signature

​Parameters

​Return Value

​Behavior

​Examples

​Basic Identification

​Identify with Attributes

​After Login

​After Signup

​On Page Load (Session Restoration)

​Framework Integration

​When to Call identify()

​Best Practices

​1. Identify Early

​2. Include Useful Attributes

​3. Don’t Call Multiple Times

​4. Handle User Switching

​Related Methods

​Utility Methods

​getCurrentUserId()

​Complete Example

​Next Steps

Signature

Parameters

Return Value

Behavior

Examples

Basic Identification

Identify with Attributes

After Login

After Signup

On Page Load (Session Restoration)

Framework Integration

When to Call identify()

Best Practices

1. Identify Early

2. Include Useful Attributes

3. Don’t Call Multiple Times

4. Handle User Switching

Related Methods

Utility Methods

getCurrentUserId()

Complete Example

Next Steps