Sessions vs replays
How HumanBehavior defines a session, when ids rotate, heartbeats, and what a replay stores.
Session
A session is a continuous period of activity from a browser tab/window identified by a sessionId.
How the SDK manages it
| Rule | Shipped value / behavior |
|---|---|
| Idle timeout | 30 minutes without activity → SDK rotates to a new sessionId |
| Max length | 24 hours → force rotate |
| Persistence | human_behavior_session in localStorage across reloads within the idle window |
| Anonymous user | endUserId (UUID) in cookie/localStorage human_behavior_end_user_id |
| Multi-window | Separate windowId per window; FullSnapshot per window for the player |
The 30-minute idle window is intentionally aligned with the ingestion server’s session inactivity setting. Misalignment would produce analytics sessions whose attached replay only covers part of the span.
Lifecycle HTTP calls
sessionId and anonymous endUserId are created in the browser (localStorage / cookie). The SDK does not need a bootstrap request before recording.
| Call | Role |
|---|---|
POST /api/ingestion/events | Replay chunks (+ some event stream traffic); first event also creates the user/session server-side |
POST /api/ingestion/heartbeat | ~30s presence so idle tabs stay “live” |
POST /api/ingestion/session-end | Unload beacon so live presence drops immediately |
POST /api/ingestion/init still exists on the server but is optional / deprecated — normal SDK startup does not call it.
Minimum duration
By default the SDK holds outbound traffic until the session is at least 5 seconds old (minimumDurationMilliseconds). Bounce tabs under that threshold may appear empty until you lower the gate.
Replay
A replay is the stored rrweb timeline for a session: FullSnapshots, incremental mutations, input/mouse data (subject to redaction), and player activity streams (console, network, custom, etc.).
Not every analytics product stores DOM replays; in HumanBehavior Replays is a first-class nav item because session recording is a core ingest path (/events).
Live vs archived
| State | Meaning |
|---|---|
| Live | Session still receiving heartbeats / events within the server live window; player may stream |
| Archived | Session finalized; standard VOD-style playback |
When a dashboard user watches live, the ingestion response can signal liveViewerActive, and the SDK temporarily flushes every 150ms instead of 3s.
How this shows up in the UI
| UI | Uses sessions / replays |
|---|---|
| Replays list / player | Direct |
| Issues → Session replays | Deep link with issue context |
| Visitors detail → Replays | Per-person history |
| Dashboard Sessions KPI | Aggregate counts |