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 | |
clickIds | Array<object> | Custom click-ID registry. Entries with a `param` matching a default override the platform name in place; new params append to the end of the priority list. |
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