Session
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 different 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 the storage parameter consent, 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 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:
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 | 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 that gets called after the detection process. Or to disable default callback |
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 a
consent choice is available. If at least one permission was granted, the
sessionStorage detects a new session; otherwise, the sessionWindow.
Storage
Option to enable enable sessionStorage util to detect a new session with more accuracy and enhanced data.
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.
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. It will only run once per run.
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 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 |
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:
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:
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.
For more information on storage and expiration, check the storage configuration options in this guide.
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.
Referrer Customization
By default the document.referrer is used, but it can be overwritten with the
referrer parameter.
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.
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.
- Page reload: If the entry type is a page reload, it's not a new session.
- Marketing Parameters: The presence of marketing parameters in the URL indicates a new session.
- 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.