Session
A session is a period in which a user actively engages with a website, often used for attribution and conversion tracking. Tools define and detect sessions in different ways.
The session source runs sessionStart with its
settings: it detects a new session, sets the user ids and pushes a
session start event, or executes custom code. It works
client-side and is cookieless by default, and returns
Session Data. The Config Parameters below
are the config of sessionStart: the session source passes its settings and
its own collector; set the source up as its page describes.
sessionStart is also exported for direct use. Called without a collector, it
only returns the session data: it pushes no event, sets no user ids, and with
consent it does nothing. The snippets below pass collector where they show an
event and leave it out where only the returned data matters.
In the cookieless mode (default), only the sessionWindow Util
is used. With config parameter storage: true, the
sessionStorage runs and reads the page signals through
sessionWindow.
Working with storage usually requires consent and is not activated by default. Use the consent option to control the storage access permissions.
In the complete example
The web flow of flow-complete.json, the tested example flow, runs the session source with
storage behind functional consent:
{
"package": "@walkeros/web-source-session",
"config": {
"settings": {
"storage": true,
"consent": "functional",
"length": 30
}
},
"examples": { … }
}web-entry/flows/web/sources/session/config/settings/consent: "functional". Storage for session ids waits for the functional consent key. Guide chapter consent-privacy
A visit from a Google Ads click starts a session: the source sets user.session and user.device and emits session start with the raw gclid, which the server keeps for the conversion.
{
"storage": true
}elb("user", {
"session": "s3ss10n",
"device": "d3v1c3"
});
elb("session", {
"id": "s3ss10n",
"start": 1790251200000,
"isNew": true,
"count": 1,
"runs": 1,
"isStart": true,
"storage": true,
"referrer": "www.google.com",
"campaign": "trail",
"medium": "cpc",
"source": "google",
"gclid": "gclid-abc123",
"clickId": "gclid",
"platform": "google",
"marketing": true,
"device": "d3v1c3",
"updated": 1790251200000
});
elb({
"name": "session start",
"data": {
"id": "s3ss10n",
"start": 1790251200000,
"isNew": true,
"count": 1,
"runs": 1,
"isStart": true,
"storage": true,
"referrer": "www.google.com",
"campaign": "trail",
"medium": "cpc",
"source": "google",
"gclid": "gclid-abc123",
"clickId": "gclid",
"platform": "google",
"marketing": true,
"device": "d3v1c3",
"updated": 1790251200000
},
"source": {
"type": "session",
"platform": "web",
"url": "https://www.example.com/?utm_source=google&utm_medium=cpc&utm_campaign=trail&gclid=gclid-abc123",
"referrer": "https://www.google.com/"
}
})marketingSession of step session. Guide chapter web-entrySession data
Depending on the storage and consent parameters, the sessionStart function
returns an object with several properties. If a new session is detected,
isStart is set to true, otherwise false.
| Property | Type | Description |
|---|---|---|
| isStart | boolean | If this is a new session or a known one |
| storage | boolean | If the storage was used to determine the session |
| id | string | Randomly generated or previously stored session id |
| start | number | Timestamp of session start |
| marketing | boolean | If the session was started by a marketing parameter |
| referrer | string | Hostname of the referring site if available |
With storage: true and granted consent, the returning object will be
extended with the following:
| Property | Type | Description |
|---|---|---|
| updated | number | Timestamp of last update |
| isNew | boolean | If no stored session was found |
| device | string | Randomly generated or previously stored device id |
| count | number | Sessions counted since the stored session began |
| runs | number | Total number of runs (like page views) |
The stored session is kept for twice the session length after its last
update. A visitor who returns later starts with isNew: true and count: 1
again, while device stays the same (see
isStart vs isNew).
sessionStart
Example of calling sessionStart on a user's first visit, with the
collector that startFlow returns:
// On page https://www.walkeros.io/docs/session?utm_campaign=docs
sessionStart({ storage: true, collector });
// pushes the event
{
name: "session start",
data: {
isStart: true,
storage: true,
id: 'r4nd0m1d',
start: 1711715862000,
marketing: true,
campaign: 'docs',
// Additionally in storage mode
updated: 1711715862000,
isNew: true,
device: 'd3v1c31d',
count: 1,
runs: 1,
},
// ...
}In addition, with storage: true and optionally granted consent, the id and
device values are set automatically as user.session and user.device ids.
Window mode sets neither: its id is only available as data.id of the
session start event.
Config parameters
All parameters of sessionStart are optional:
| Parameter | Type | Description |
|---|---|---|
| consent | string or Array<string> | The consent state to permit or deny storage access |
| storage | boolean | If the storage should be used |
| cb | false or function | Callback function called after detection, or false to disable the default callback |
| collector | object | Receives the user ids and the session start event; the session source passes its own |
There are additional config parameters for storage and for window available.
Consent
The consent state to wait for before detecting a new session decides whether
storage access is allowed. If set, it registers an
on consent event and won't start until a
consent choice is available. If at least one permission was granted, the
sessionStorage detects a new session; otherwise, the sessionWindow.
sessionStart({ consent: 'marketing', collector }); // Won't start automatically
// User makes a consent choice and CMP calls:
elb('walker consent', { marketing: true }); // Triggers the session detection
// Detects the session with storage accessStorage
Enables the sessionStorage util, which detects a new session with more accuracy and more data.
sessionStart({ storage: true });Callback
The cb parameter can be used to disable the default callback or to define a
custom one. The default callback triggers a session start event if isStart
is true. With storage: true, it also sets the user's session and
device ids via elb('walker user', user);. The default callback
function is passed as the third parameter.
const session = sessionStart({ cb: false }); // Disables the default callback
sessionStart({
collector,
cb: (session, instance, defaultCb) => {
console.log(session);
defaultCb(session, instance); // Call the default callback
},
});Detection process
Based on the storage option either the sessionStorage or the sessionWindow is used to detect a new session. If a consent state is set, the session detection gets scheduled via an on-consent command. Each mode (window, storage) detects once per page load, so a later consent change in the same mode starts no new session.
sessionStorage
Config parameters
Additional config parameters for storage-based session detection:
| Property | Type | Description | Default |
|---|---|---|---|
| deviceKey | string | The key to store the device ID in the storage | elbDeviceId |
| deviceStorage | string | The storage type for the device ID (local, session, cookie) | local |
| deviceAge | number | The age in days to consider the device ID as expired | 30 |
| sessionKey | string | The key to store the session ID in the storage | elbSessionId |
| sessionStorage | string | The storage type for the session ID (local, session, cookie) | local |
| domain | string | Cookie domain, e.g. example.com to share IDs across subdomains (cookie only) | |
| length | number | Minutes after the last update to consider session as expired | 30 |
| pulse | boolean | Update the current session to stay active | false |
There are additional config parameters for sessionWindow available.
Cookie storage
Set deviceStorage and/or sessionStorage to cookie to persist the IDs as
cookies. Use domain to set the cookie on a parent domain so all subdomains
share the same session and device IDs:
sessionStart({
storage: true,
deviceStorage: 'cookie',
sessionStorage: 'cookie',
domain: 'example.com', // Shared across www.example.com, shop.example.com, ...
});Without domain, cookies are host-only and bound to the exact (sub)domain that
set them. When adding domain to an existing setup, previously written
host-only cookies remain until they expire, so both variants can coexist
temporarily.
Detection process
Basic rules to detect a new session:
sessionWindow
Config parameters
| Parameter | Type | Description |
|---|---|---|
| data | object | Custom data to enhance the default data properties |
| domains | array | Internal domains to prevent new sessions from triggering when navigating |
| isStart | boolean | Manual new session control |
| parameters | object | Marketing parameters to enhance the default and support custom ones |
| referrer | string | Referrer customization |
| url | string | URL customization |
Custom data
Add custom information to the default data properties, like a session count:
const count = 2;
const session = sessionStart({ data: { count } });This will return a data object like { id: "r4nd0m", count: 2 }.
Internal domains
Define internal domains to prevent new sessions from triggering when navigating between them:
const session = sessionStart({
domains: ['subdomain.walkeros.io', 'example.com'],
});A user who comes from subdomain.walkeros.io or example.com to, for example,
www.walkeros.io does not trigger a new session.
Manual new session control
Determine if it's a new session using the isStart parameter. This might
require consent for storage access, which isn't implemented by default.
Usually, the sessionId written to the storage is set up to expire and should
be updated with each page view. If the sessionId is missing, the session may
have expired, but it is a new session either way.
import { storageRead, storageWrite } from '@walkeros/web-core';
if (!storageRead('sessionId')) {
const session = sessionStart({ isStart: true });
storageWrite('sessionId', session.id);
}For more information on storage and expiration, check the storage configuration options in this guide.
Marketing parameters
The helper util getMarketingParameters extracts common parameters like all
utm variants and typical clickIds such as fbclid and gclid.
To support custom parameters as well, add parameters: for example
{ elb_campaign: 'campaign' } adds campaign: "docs" to data for a URL with
?elb_campaign=docs.
A session with marketing parameters will be flagged with data.marketing = true
automatically.
interface MarketingParameters {
[key: string]: string;
}
sessionStart({
parameters: { elb_campaign: 'campaign' },
});Click IDs and platform resolution
When the URL contains a known ad-platform click ID, getMarketingParameters
adds two fields to its result:
clickId: the URL parameter name that was found (e.g.gclid).platform: the canonical platform identifier (e.g.google).
The raw value is also stored under the parameter name itself, so a URL like
https://example.com/?gclid=abc produces:
{
clickId: 'gclid',
gclid: 'abc',
platform: 'google',
}
If a URL contains multiple click IDs, every raw value is preserved, but
clickId and platform reference the highest-priority match. See
getMarketingParameters.ts
for the full list and priority order.
Extending the registry from flow.json
Pass a clickIds array in the session source settings. Entries with a param
matching a default override the platform name in place; new params append to
the end of the priority list.
{
"version": 4,
"flows": {
"default": {
"config": { "platform": "web" },
"sources": {
"session": {
"package": "@walkeros/web-source-session",
"config": {
"settings": {
"clickIds": [
{ "param": "xyzclid", "platform": "xyz" },
{ "param": "fbclid", "platform": "facebook" }
]
}
}
}
}
}
}
}
Referrer customization
By default the document.referrer is used, but it can be overwritten with the
referrer parameter.
sessionStart({ referrer: 'https://example.com' });URL customization
By default, the window.location.href is used, but it can be overwritten with
the url parameter.
sessionStart({ url: 'https://example.com' });Detection process
Basic rules to detect a new session:
- Storage Check (Optional): First, check for an existing sessionId in storage. If none is found, consider it a new session. This usually requires consent.
- Navigation type: Only a plain navigation can start a session. A reload, back and forward, or a browser without Navigation Timing cannot.
- Marketing Parameters: The presence of marketing parameters in the URL indicates a new session.
- Referrer Check: A referrer from another host, or none (a direct visit), signals a new session.
Referrer hiding can cause multiple unintended events for the same user. For more details, see Referrer Hiding.