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 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 |
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:
try await Tell.shared.configure(
apiKey: "YOUR_API_KEY",
sessionTimeout: 15 * 60 // 15 minutes
)
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.
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 |
| 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 |
| 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 |
| 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) |
| Property | Example | Description |
|---|
locale | en_US | Device locale |
timezone | America/New_York | Device timezone |
| 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:
tell.register({
deployment: 'canary',
app_version: '2.1.0',
build_sha: 'a1b2c3d'
});
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 |
What gets attached to events
Every event (track, identify, group, revenue, alias) automatically gets:
- Device ID — from the session manager
- Session ID — from the session manager
- Minimal device context —
device_type, operating_system, os_version, app_version (if device context enrichment is enabled)
- 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 — starts new session with custom reason
await Tell.shared.sessionManager?.startNewSession(reason: "user_switched")
reset() to clear the current user, generate a new anonymous ID, and stop the current session. The next event starts a fresh session.
What’s next
