Skip to main content
Ask your AI

Session

Source code Package

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.

note

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:

/flows/web/sources/session
{
  "package": "@walkeros/web-source-session",
  "config": {
    "settings": {
      "storage": true,
      "consent": "functional",
      "length": 30
    }
  },
  "examples": { … }
}
The session source sets user.session and user.device and emits session start with the raw click id. Guide chapter 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.

Event
{
  "storage": true
}
Out
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/"
  }
})
New session from an ad click: example marketingSession of step session. Guide chapter web-entry

Session 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.

PropertyTypeDescription
isStartbooleanIf this is a new session or a known one
storagebooleanIf the storage was used to determine the session
idstringRandomly generated or previously stored session id
startnumberTimestamp of session start
marketingbooleanIf the session was started by a marketing parameter
referrerstringHostname of the referring site if available

With storage: true and granted consent, the returning object will be extended with the following:

PropertyTypeDescription
updatednumberTimestamp of last update
isNewbooleanIf no stored session was found
devicestringRandomly generated or previously stored device id
countnumberSessions counted since the stored session began
runsnumberTotal 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,
  },
  // ...
}
info

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:

ParameterTypeDescription
consentstring or Array<string>The consent state to permit or deny storage access
storagebooleanIf the storage should be used
cbfalse or
function
Callback function called after detection, or false to disable the default callback
collectorobjectReceives the user ids and the session start event; the session source passes its own
info

There are additional config parameters for storage and for window available.

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 access

Storage​

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:

PropertyTypeDescriptionDefault
deviceKeystringThe key to store the device ID in the storageelbDeviceId
deviceStoragestringThe storage type for the device ID (local, session, cookie)local
deviceAgenumberThe age in days to consider the device ID as expired30
sessionKeystringThe key to store the session ID in the storageelbSessionId
sessionStoragestringThe storage type for the session ID (local, session, cookie)local
domainstringCookie domain, e.g. example.com to share IDs across subdomains (cookie only)
lengthnumberMinutes after the last update to consider session as expired30
pulsebooleanUpdate the current session to stay activefalse
info

There are additional config parameters for sessionWindow available.

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​

ParameterTypeDescription
dataobjectCustom data to enhance the default data properties
domainsarrayInternal domains to prevent new sessions from triggering when navigating
isStartbooleanManual new session control
parametersobjectMarketing parameters to enhance the default and support custom ones
referrerstringReferrer customization
urlstringURL 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:

  1. Storage Check (Optional): First, check for an existing sessionId in storage. If none is found, consider it a new session. This usually requires consent.
  2. Navigation type: Only a plain navigation can start a session. A reload, back and forward, or a browser without Navigation Timing cannot.
  3. Marketing Parameters: The presence of marketing parameters in the URL indicates a new session.
  4. Referrer Check: A referrer from another host, or none (a direct visit), signals a new session.
note

Referrer hiding can cause multiple unintended events for the same user. For more details, see Referrer Hiding.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)