> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Users & Identity

> How Tell identifies users — device IDs, user IDs, and identity merging.

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.

```swift theme={null}
Tell.shared.identify("user_123", traits: [
    "name": "Jane",
    "email": "jane@example.com",
    "plan": "pro"
])
```

```javascript theme={null}
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:

```swift theme={null}
Tell.shared.alias("anon_visitor_abc", userId: "user_123")
```

```javascript theme={null}
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:

```swift theme={null}
Tell.shared.group("company_456", properties: [
    "name": "Acme Corp",
    "plan": "enterprise",
    "employees": 150
])
```

```javascript theme={null}
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)

```swift theme={null}
Tell.shared.reset()
```

```javascript theme={null}
tell.reset();
```

This ensures the next user on a shared device gets a clean identity.

## Event types for identity

| Method     | Event type | When to use                                                |
| ---------- | ---------- | ---------------------------------------------------------- |
| `identify` | `identify` | User logs in or signs up — link device to known user       |
| `alias`    | `alias`    | Merge two identities (anonymous to known, or cross-device) |
| `group`    | `group`    | Associate 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](/tracking/sessions) for the full list of collected properties.

## What's next

* [Sessions](/tracking/sessions) — session lifecycle and device context
* [Events & Properties](/tracking/events-and-properties) — the event model and property patterns
* [SDKs](/tracking/sdks/swift) — platform-specific integration guides