Session

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.

info

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.

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	true	If the session was started by a marketing parameter
referrer	string	Hostname of the referring site if available

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

Property	Type	Description
updated	number	Timestamp of last update
isNew	boolean	If this is the first visit on a device
device	string	Randomly generated or previously stored device id
count	number	Total number of sessions
runs	number	Total number of runs (like page views)

sessionStart

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

// On page https://www.elbwalker.com/docs/session?utm_campaign=docs
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,
  },
  // ...
}

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.

Config parameters

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

Parameter	Type	Description
consent	string	The consent state to permit or deny storage access
storage	boolean	If the storage should be used
cb	false or function	Callback function that gets called after the detection process. Or to disable default callback

info

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

Consent

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

Storage

Option to enable enable sessionStorage util to detect a new session with more accuracy and enhanced 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. And additionally, with storage: true, the user's session and device ids are also set 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({
  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.

sessionStorage

Config parameters

Additional config parameters, based on the Storage util:

Property	Type	Description	Default
deviceKey	string	The key to store the device ID in the storage	elbDeviceId
deviceStorage	string	The storage type to use for the device id	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 to use for the session id	local
length	number	Minutes after the last update to consider session as expired	30
pulse	boolean	Update the current session to stay active	false

info

There are additional config parameters for sessionWindow available.

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

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: ['subdomain.elbwalker.com', 'example.com'],
});

A user coming from subdomain.elbwalker.com or example.com to e.b. www.elbwalker.com, 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 });
  storageWrite('sessionId', session.id);
}

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 data.marketing = true automatically.

interface MarketingParameters {
  [key: string]: string;
}

sessionStart({
  parameters: { elb_campaign: 'docs' },
});

Referrer Customization

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

sessionStart({ referrer: 'https://example.com' });

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: 'https://example.com' });

Detection process

Basic rules to detect a new session:

0. Storage Check (Optional): First, check for an existing sessionId in storage. If none is found, consider it a new session. This usually requires consent.
1. Page reload: If the entry type is a page reload, it's not a new session.
2. Marketing Parameters: The presence of marketing parameters in the URL indicates a new session.
3. Referrer Check: A different referrer from the current domain signals a new session.

info

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