Skip to main content


Source code Package Source code Package

There are multiple ways to define and measure a session. Sessions represent a period when a user actively engages with a website, often used for attribution and conversion tracking. Different tools may define and detect sessions in varying ways.

The sessionStart util helps to detect a new session independently and triggers a session start event or executes custom code. It works client-side and is cookieless by default. The Util returns Session Data information. There are Config Parameters to customize the session detection.

In the cookieless mode (default), only the sessionWindow Util is used. With config parameter storage: true, the sessionStorage gets called before the sessionWindow.


Working with Storage usually requires consent and is not activated by default. Use the consent option to control the storage access permissions.

Session Data

Depending on enabling the storage parameter, the sessionStart function returns an object with several properties. If a new session is detected, isStart is set to true, otherwise false.

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
marketingtrueIf the session was started by a marketing parameter

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

updatednumberTimestamp of last update
isNewbooleanIf this is the first visit on a device
devicestringRandomly generated or previously stored device id
countnumberTotal number of sessions
runsnumberTotal number of runs (like page views)


Example of calling sessionStart on a user's first visit:

// On page
sessionStart({ storage: true });

// will automatically create the event
event: "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.

Config parameters

The sessionStart function is designed to work out of the box. All parameters are optional for customization:

consentstringThe consent state to permit or deny storage access
storagebooleanIf the storage should be used
cbfalse or
Callback function that gets called after the detection process.
Or to disable default callback

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

Setting a consent state to wait for before detecting a new session is used to decide if storage access is allowed or not. If set, it registers an on consent event and won't start until that consent choice is available. If permission was granted, the sessionStorage detects a new session; otherwise, the sessionWindow.

sessionStart({ consent: 'marketing' }); // Won't start automatically
// User makes a consent choice and CMP calls:
elb('walker consent', { marketing: true }); // Triggers the session detection
// Returns a session with storage access


Option to enable enable sessionStorage util to detect a new session with more accuracy and enhanced data.

sessionStart({ storage: true });


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. And additionally, with storage: true, the user's session and device ids are also set via elb('walker user', user);.

const session = sessionStart({ cb: false }); // Disables the default callback

cb: (session, instance) => {

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.


Config parameters

Additional config parameters, based on the Storage util:

deviceKeystringThe key to store the device ID in the storageelbDeviceId
deviceStoragestringThe storage type to use for the device idlocal
deviceAgenumberThe age in days to consider the device ID as expired30
sessionKeystringThe key to store the session ID in the storageelbSessionId
sessionStoragestringThe storage type to use for the session idlocal
sessionAgenumberThe age in days to consider the session ID as expired30
lengthnumberMinutes after the last update to consider session as expired30

There are additional config parameters for sessionWindow available.

Detection process

Basic rules to detect a new session:


Config parameters

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

Enhance the default data properties with custom information, 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: ['', ''],

A user coming from or to e.b., will no longer 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, it may be an expired but at least a new session.

if (!storageRead('sessionId')) {
const session = sessionStart({ isStart: true });

For more information on storage and expiration, see Utils/Storage

Marketing Parameters

The helper util getMarketingParameters is used to extract common parameters like all utm variants, typical clickIds like fbclid, gclid, and others.

To enhance the default and support custom ones add parameters, like { elb_campaign: 'campaign' } to add campaign: "docs" to data for a url with ?elb_campaign=docs.

A session with marketing parameters will be flagged with = true automatically.

interface MarketingParameters {
[key: string]: string;

parameters: { elb_campaign: 'docs' },

Referrer Customization

By default the document.referrer is used, but it can be overwritten with the referrer parameter.

sessionStart({ referrer: '' });

domains can be extended, e.g., internal sub-domains. Data can be pre-defined, e.g., to use your ID.

URL Customization

By default, the window.location.href is used, but it can be overwritten with the url parameter.

sessionStart({ url: '' });

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. Page reload: If the entry type is a page reload, it's not a new session.
  3. Marketing Parameters: The presence of marketing parameters in the URL indicates a new session.
  4. Referrer Check: A different referrer from the current domain signals a new session.

Be aware of potential multiple unintended events for the same user due to referrer hiding. For more details, learn about Referrer Hiding.