> ## 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.

# Sessions

> How Tell groups events into sessions and what session data is available.

Sessions group a user's events into a single visit. Every event carries a session ID, so you can answer questions like "how many sessions included a purchase" or "what did this user do in their last session."

## How sessions work

A session starts when the SDK initializes (app launch, first page load) and ends when the user is inactive for longer than the **session timeout** (30 minutes by default) or exceeds the **max session length** (24 hours by default). On web, the session ID is persisted to localStorage so page navigations continue the same session.

Every event sent during a session shares the same 16-byte session ID. When a session expires and the user returns, a new session ID is generated and all subsequent events are grouped under it.

Sessions are tracked alongside a **device ID** — a persistent identifier for the physical device. The device ID stays the same across sessions; the session ID rotates.

## Session lifecycle

On mobile (iOS, macOS, visionOS), the SDK observes app lifecycle events and sends **context events** at each transition:

| Trigger              | Context event      | What happens                                            |
| -------------------- | ------------------ | ------------------------------------------------------- |
| App launch           | `session_started`  | New session ID generated, full device context collected |
| App backgrounded     | `app_backgrounded` | Timestamp recorded, context event sent                  |
| App foregrounded     | `app_foregrounded` | If background time \< timeout, session continues        |
| Background > timeout | `session_timeout`  | New session ID generated, context event sent            |
| App terminated       | `app_terminated`   | Final context event sent                                |

Active/inactive transitions (e.g. pulling down notification center) update internal state but don't generate context events — they happen too frequently to be useful.

### Session timeout

The default timeout is 30 minutes. If a user backgrounds your app and returns within 30 minutes, the same session continues. If they return after 30 minutes, a new session starts.

You can configure this at initialization:

```swift theme={null}
try await Tell.shared.configure(
    apiKey: "YOUR_API_KEY",
    sessionTimeout: 15 * 60  // 15 minutes
)
```

```javascript theme={null}
tell.configure('YOUR_API_KEY', { sessionTimeout: 15 * 60 * 1000 }); // 15 minutes
```

### Max session length

Sessions are capped at 24 hours by default to prevent zombie sessions from tabs left open indefinitely. When the max length is reached, the session rotates even if the user is still active.

```javascript theme={null}
tell.configure('YOUR_API_KEY', { maxSessionLength: 12 * 60 * 60 * 1000 }); // 12 hours
```

## Context data

Each context event carries a snapshot of the device and app environment. On mobile SDKs, this is collected automatically — you don't need to send it yourself.

### Automatically collected properties

**Device**

| Property           | Example                                            | Description        |
| ------------------ | -------------------------------------------------- | ------------------ |
| `device_type`      | `mobile`, `tablet`, `desktop`, `tv`, `watch`, `vr` | Device form factor |
| `device_model`     | `iPhone`, `Mac14,2`                                | Hardware model     |
| `operating_system` | `ios`, `macos`, `visionos`                         | OS family          |
| `os_version`       | `18.2.0`                                           | Semver OS version  |

**App**

| Property        | Example           | Description                 |
| --------------- | ----------------- | --------------------------- |
| `app_version`   | `2.1.0`           | Bundle short version string |
| `app_build`     | `42`              | Build number                |
| `app_bundle_id` | `com.example.app` | Bundle identifier           |

**Screen**

| Property                | Example | Description           |
| ----------------------- | ------- | --------------------- |
| `screen_width`          | `1170`  | Physical pixel width  |
| `screen_height`         | `2532`  | Physical pixel height |
| `screen_scale`          | `3.0`   | Display scale factor  |
| `screen_logical_width`  | `390`   | Logical point width   |
| `screen_logical_height` | `844`   | Logical point height  |

**System**

| Property            | Example        | Description                                   |
| ------------------- | -------------- | --------------------------------------------- |
| `memory_total`      | `6442450944`   | Total physical memory (bytes)                 |
| `memory_available`  | `104857600`    | Resident memory usage (bytes)                 |
| `storage_available` | `48318382080`  | Available disk space (bytes)                  |
| `storage_total`     | `127989493760` | Total disk capacity (bytes)                   |
| `battery_level`     | `0.85`         | Battery charge 0.0–1.0 (iOS only)             |
| `battery_state`     | `charging`     | `unplugged`, `charging`, or `full` (iOS only) |

**Locale**

| Property   | Example            | Description     |
| ---------- | ------------------ | --------------- |
| `locale`   | `en_US`            | Device locale   |
| `timezone` | `America/New_York` | Device timezone |

**Session**

| Property              | Example         | Description                                |
| --------------------- | --------------- | ------------------------------------------ |
| `session_reason`      | `session_start` | Why this context event was sent            |
| `app_state`           | `active`        | App state at time of event                 |
| `background_duration` | `1847.5`        | Seconds spent in background (if returning) |

### Adding custom context

Use super properties to attach custom context to every event:

```javascript theme={null}
tell.register({
    deployment: 'canary',
    app_version: '2.1.0',
    build_sha: 'a1b2c3d'
});
```

On the server side, pass context as event properties. There's no fixed schema — the properties field accepts any key-value data, so you can enrich events with whatever is relevant to your application.

## Device IDs

The device ID is a 16-byte UUID that persists across sessions and app updates.

| Platform       | Storage        | Lifetime                             |
| -------------- | -------------- | ------------------------------------ |
| iOS / visionOS | Keychain       | Survives app reinstalls              |
| macOS          | Keychain       | Survives app reinstalls              |
| Web            | `localStorage` | Per browser, cleared on storage wipe |
| Server         | Not applicable | Use user IDs directly                |

Mobile SDKs generate and store the device ID automatically. You never need to manage it yourself.

## What gets attached to events

Every event (track, identify, group, revenue, alias) automatically gets:

1. **Device ID** — from the session manager
2. **Session ID** — from the session manager
3. **Minimal device context** — `device_type`, `operating_system`, `os_version`, `app_version` (if device context enrichment is enabled)
4. **Timestamp** — current time unless overridden

You don't need to pass any of this manually. The SDK handles it.

## Manual session control

You can force a new session at any time:

```swift theme={null}
// Swift — starts new session with custom reason
await Tell.shared.sessionManager?.startNewSession(reason: "user_switched")
```

Call `reset()` to clear the current user, generate a new anonymous ID, and stop the current session. The next event starts a fresh session.

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

## What's next

* [Users & Identity](/tracking/users-and-identity) — device IDs, user IDs, and identity merging
* [Events & Properties](/tracking/events-and-properties) — the event model
* [SDKs](/tracking/sdks/swift) — platform-specific integration guides