Documentation

Identifying Users

Manage distinct IDs, user traits, and logout resets

Default identity behavior

After analytics consent, the SDK creates a project-scoped anonymousdistinctId and stores it in localStorage. That anonymous ID remains the event identity before and afteridentify().

identify(userId, traits?)

analytics.identify('user_123')

analytics.identify('usr_01HXYZ...', {
  plan: 'pro',
  accountTier: 'starter',
})

Calling identify() preserves the anonymousdistinctId, stores the opaque user ID separately aspersonId, and emits $identify. Subsequent events carry both IDs so the original anonymous journey can be joined to the identified person.

Use opaque internal IDs in the browser. The SDK rejects raw email and phone identifiers and removes sensitive credential, payment, cookie, and personal-data fields from browser event properties. Pass consented provider user data only from a server-side conversion workflow.

setUserProperties(properties)

Use this to update traits without changing identity. It emits$set_user.

analytics.setUserProperties({
  plan: 'enterprise',
  renewal_date: '2026-06-01',
})

reset()

Call on logout. reset() generates a new anonymous distinctId, clears the current session ID, and emits $reset.

function handleLogout() {
  analytics.track('logout_clicked')
  analytics.reset()
}

Inspect current IDs

const anonymousId = analytics.getDistinctId()
const personId = analytics.getPersonId()
const sessionId = analytics.getSessionId()

Best practices