Skip to main content


There are multiple ways about how to define and measure a session. Sessions represent a period when a user is actively engaged 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 can be used to trigger a custom event. It works client-side and is cookieless by default. If a new session is detected, it returns the sessions data, otherwise false. There are config parameters to customize the session handling.

The function only checks for a new session and eventually returns the data for a new one. An event has to be triggered manually:

const session = sessionStart();
if (session) elb('session start', session);

This might send a session start event with the following data:

// Page

id: 's3ss10n1d',
marketing: true,
campaign: 'docs',

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.

Config parameters

The sessionStart function is designed to work out of the box but offers optional config parameters for customization:

interface SessionStart {
data?: Walker.Properties;
domains?: string[];
isNew?: boolean;
parameters?: MarketingParameters;
referrer?: string;
url?: string;

interface MarketingParameters {
[key: string]: string;

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 isNew parameter. This might require consent for storage access and therefore isn't implement 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's maybe an expired but at least a new session.

if (!storageRead('sessionId')) {
const session = sessionStart({ isNew: 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 parameter will be flagged with = true automatically.

const session = sessionStart({
parameters: { elb_campaign: 'docs' },

Referrer Customization

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

const session = sessionStart({ referrer: '' });

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

URL Customization

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

const session = sessionStart({ url: '' });