User identification allows you to connect anonymous sessions to known users, track properties across sessions, and build complete user profiles.
Identifying Users
When a user signs up or logs in, identify them to merge their anonymous activity:
// User logs in
await composite.identify('user_123', {
email: '[email protected]',
name: 'John Doe'
});
sys_identify event that:
- Links the anonymous ID to the identified user
- Sets the provided properties on the person profile
- Enables attribution of past anonymous events to this user
With Additional Options
await composite.identify('user_123',
{ email: '[email protected]' },
{
$set_once: {
signup_date: new Date().toISOString(),
referrer: document.referrer
}
}
);
Getting Identity Info
const distinctId = composite.getDistinctId(); // Current user ID
const anonymousId = composite.getAnonymousId(); // Anonymous ID
const sessionId = composite.getSessionId(); // Current session ID
Reset Identity (Logout)
When a user logs out, reset their identity:
Calling reset() generates a new anonymous ID, clears the identified user, and resets the session. Use this when users log out.
Person Properties
Set Properties (Overwrite)
Always overwrites existing values:
composite.setPersonProperties({
email: '[email protected]',
plan: 'premium',
company: 'Acme Corp'
});
Set Properties Once (First-Touch)
Only sets if the property doesn’t already exist - useful for attribution:
composite.setPersonPropertiesOnce({
first_seen: new Date().toISOString(),
initial_referrer: document.referrer,
signup_source: 'google_ads'
});
Set Properties with Events
Set person properties along with an event capture:
composite.capture('subscription_started',
{ plan: 'premium', price: 29.99 },
{
$set: {
plan: 'premium',
subscription_status: 'active'
},
$set_once: {
first_subscription_date: new Date().toISOString()
}
}
);
Create Alias
Link another identifier to the current person:
composite.createAlias('stripe:cus_abc123');
composite.createAlias('email:[email protected]');
Complete Example
import composite from '@composite-inc/composite-js/content-script';
// Initialize
await composite.init({
apiKey: 'pk_your_api_key',
transport: 'chrome-extension',
sessionRecording: true
});
// Track anonymous user browsing
composite.capture('page_viewed', { page: '/pricing' });
composite.setPersonPropertiesOnce({ first_page: '/pricing' });
// User signs up
await composite.identify('user_123', {
email: '[email protected]',
name: 'John Doe'
});
// Track identified user activity
composite.capture('subscription_started',
{ plan: 'premium' },
{ $set: { plan: 'premium' } }
);
// Link external identifier
composite.createAlias('stripe:cus_abc123');
// User logs out
await composite.reset();
Storage and Persistence
The SDK automatically uses Chrome’s storage API for persistence. User identification persists across:
- Browser sessions
- Extension updates
- Tab closures
API Reference
| Method | Description |
|---|
identify(distinctId, properties?, options?) | Identify user and merge anonymous data |
setPersonProperties(properties) | Set person properties (overwrite) |
setPersonPropertiesOnce(properties) | Set person properties (first-touch) |
createAlias(alias) | Link identifier to current person |
reset() | Reset identity and session |
getDistinctId() | Get current user ID |
getAnonymousId() | Get anonymous ID |
getSessionId() | Get current session ID |
Best Practices
Identify Promptly
Call identify() as soon as the user logs in or signs up
Use set_once for Attribution
Capture first-touch data like referrer, UTM params on first visit
Reset on Logout
Always call reset() when users log out to prevent data mixing
Consistent IDs
Use the same distinct_id format across all your systems
What’s Next?
