Skip to main content
Tell tracks users through three layers of identity: device IDs (automatic), anonymous IDs (automatic), and user IDs (you provide these). Together they let you follow a user from their first anonymous visit through login and across devices.

​
Identity layers

​
Device ID

A 16-byte UUID generated the first time the SDK initializes on a device. On mobile, it’s stored in the Keychain and survives app reinstalls. On web, it lives in localStorage. You never set this yourself — the SDK creates and manages it. Every event includes the device ID automatically.

​
Anonymous ID

A UUID string assigned to unidentified users. The SDK generates one on first launch and persists it in UserDefaults (mobile) or localStorage (web). All events use this as the user ID until you call identify. The anonymous ID is regenerated when you call reset() (e.g. on logout), giving the next user a clean slate.

​
User ID

The identifier you provide when you know who the user is — typically after login or signup. Once set, all subsequent events use this user ID instead of the anonymous ID. 
Tell.shared.identify("user_123", traits: [
    "name": "Jane",
    "email": "jane@example.com",
    "plan": "pro"
])

tell.identify('user_123', {
    name: 'Jane',
    email: 'jane@example.com',
    plan: 'pro'
});
The second argument is traits — persistent properties associated with the user. Traits are stored with the identify event and appear in user analytics.

​
How identification works

Before identify is called, events are sent with the anonymous ID: 
Event: page_view     user_id: "550e8400-e29b-..."  (anonymous)
Event: feature_used  user_id: "550e8400-e29b-..."  (anonymous)
After identify("user_123"), the SDK switches to the known user ID: 
Event: identify      user_id: "user_123"            traits: {name: "Jane", ...}
Event: purchase      user_id: "user_123"
Event: page_view     user_id: "user_123"
The user ID persists across sessions until reset() is called.

​
Identity resolution with alias

When you discover that two IDs belong to the same person — for example, an anonymous visitor who later logs in on a different device — use alias to merge them: 
Tell.shared.alias("anon_visitor_abc", userId: "user_123")

tell.alias('anon_visitor_abc', 'user_123');
This tells Tell that the previous ID (anon_visitor_abc) and the new user ID (user_123) are the same person. Historical events from the previous ID can then be attributed to the merged identity.

​
Groups

Associate a user with a company, team, or organization: 
Tell.shared.group("company_456", properties: [
    "name": "Acme Corp",
    "plan": "enterprise",
    "employees": 150
])

tell.group('company_456', {
    name: 'Acme Corp',
    plan: 'enterprise',
    employees: 150
});
Group properties work like user traits — they’re stored with the group event and can be used in analytics to break down metrics by company or team.

​
Reset (logout)

When a user logs out, call reset() to:
  • Clear the current user ID (reverts to anonymous)
  • Generate a new anonymous ID
  • Clear all super properties
  • Reset opt-out state to the configured default
  • Stop the current session (next event starts a fresh one)
Tell.shared.reset()

tell.reset();
This ensures the next user on a shared device gets a clean identity.

​
Event types for identity

MethodEvent typeWhen to use
identifyidentifyUser logs in or signs up — link device to known user
aliasaliasMerge two identities (anonymous to known, or cross-device)
groupgroupAssociate user with a company or team
reset—User logs out — clear identity for next user

​
What gets sent automatically

You don’t need to pass identity information on every event. The SDK tracks:
  • Device ID — generated once, attached to every event
  • Session ID — rotated on timeout, attached to every event
  • User ID — anonymous until identify, then the known ID
On mobile, the SDK also attaches device context (device type, OS, app version) to context events automatically. See Sessions for the full list of collected properties.

​
What’s next

  • Sessions — session lifecycle and device context
  • Events & Properties — the event model and property patterns
  • SDKs — platform-specific integration guides