Sessions

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:

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

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:

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:

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")

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

Tell.shared.reset()

What’s next

Users & Identity — device IDs, user IDs, and identity merging
Events & Properties — the event model
SDKs — platform-specific integration guides

Getting Started

Tracking

Pipeline

Analytics

Installing

How sessions work

Session lifecycle

Session timeout

Max session length

Context data

Automatically collected properties

Adding custom context

Device IDs

What gets attached to events

Manual session control

What’s next

​How sessions work

​Session lifecycle

​Session timeout

​Max session length

​Context data

​Automatically collected properties

​Adding custom context

​Device IDs

​What gets attached to events

​Manual session control

​What’s next

How sessions work

Session lifecycle

Session timeout

Max session length

Context data

Automatically collected properties

Adding custom context

Device IDs

What gets attached to events

Manual session control

What’s next