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
.
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,
},
// ...
}
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 |
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 |
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:
- 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.
If you need professional support with your walkerOS implementation, check out our services.