Session source
Standalone session detection and management that can be composed with any walkerOS source.
Installation
- Integrated
- Bundled
Install the packages:
Configure in your code:
Detection methods
The session source uses two complementary methods:
| Method | Storage | Use Case |
|---|---|---|
| Window | None | Privacy-first, per-page session |
| Storage | localStorage | Cross-page session tracking |
Window-based detection
Without storage, session detection relies on browser signals:
Navigation type:
Marketing parameters:
UTM and other marketing parameters trigger session start. The following are recognized by default:
To capture additional URL parameters, pass a parameters map. Each entry maps a URL parameter name to the property name it should be stored as in the session data:
Storage-based detection
With storage: true, sessions persist across page loads:
Session lifecycle:
┌─────────────────────────────────────────────────────────────┐
│ Session Timeline │
├─────────────────────────────────────────────────────────────┤
│ │
│ User visits Page 2 Page 3 30min idle │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ [Session 1] ─────────────────────────────► [Expires] │
│ id: abc123 │
│ │
│ User returns │
│ │ │
│ ▼ │
│ [Session 2] │
│ id: def456 │
└─────────────────────────────────────────────────────────────┘
Storage keys:
| Key | Default | Description |
|---|---|---|
sessionKey | elbSessionId | localStorage key for session ID |
deviceKey | elbDeviceId | localStorage key for device ID |
Session start event
When a new session is detected, the source pushes a session start event and sets the user's session and device IDs on the collector:
isStart vs isNew:
| Field | Meaning |
|---|---|
isStart: true | A new session began on this page load |
isNew: true | This is the device's very first session ever (storage mode only) |
A returning visitor starting their second session has isStart: true but isNew: false. isNew only appears in storage mode since window-only mode has no device memory.
Click ID parameters are stored twice: clickId identifies which platform originated the click (e.g. 'gclid'), and a separate field stores the actual value (e.g. gclid: 'AW-123...'). This makes it easy to filter by platform without inspecting the value.
Configuration
| Property | Type | Description | More |
|---|---|---|---|
storage | boolean | Enable persistent storage for session/device IDs | |
consent | string | array | Consent key(s) required to enable storage mode | |
length | number | Session timeout in minutes | |
pulse | boolean | Keep session alive on each event | |
sessionKey | string | Storage key for session ID | |
sessionStorage | 'local' | 'session' | Storage type for session | |
deviceKey | string | Storage key for device ID | |
deviceStorage | 'local' | 'session' | Storage type for device | |
deviceAge | number | Device ID age in days | |
cb | function | Custom session callback function or false to disable |
Consent integration
Session detection adapts to consent state:
| Consent State | Behavior |
|---|---|
| No consent | Window-only detection (no storage) |
| Consent granted | Storage-based with device ID |
| Consent revoked | Falls back to window-only |
Pulse mode
With pulse: true, the source updates the session's last-seen timestamp on each page load without counting it as a new page view and without triggering a new session start event. Use this for heartbeat-style presence tracking where you want to extend session lifetime without inflating runs:
Custom session callback
The cb setting lets you hook into session detection. It receives the detected session data, the collector instance, and the default callback:
Set cb: false to completely disable the default behavior — no user commands and no session start event will be emitted. This is useful when you want full control over what happens after detection.
Next steps
- Browser Source - DOM-based event tracking
- DataLayer Source - GTM/GA4 integration
- Consent Guide - Consent management patterns