Skip to main content

Session tracking

The web tracker can add a context entity to events with information about the current session. The context entity repeats some of the session information stored in canonical event properties (e.g. domain_useriddomain_sessionid), but also adds new information.

It adds a reference to the previous session (previousSessionId) and first event in the current session (firstEventIdfirstEventTimestamp). It also adds an index of the event in the session, useful for ordering events as they were tracked (eventIndex).


Because session tracking requires the session cookie, no session context entities will be added to events if anonymous tracking is enabled.

The default session expiry time is 30 minutes.

Tracking the session entity

The session entity is automatically tracked once configured.

Client session entity properties

The client_session context entity consists of the following properties:

userIdAn identifier for the user of the session (same as domain_userid).Yes
sessionIdAn identifier (UUID) for the session (same as domain_sessionid).Yes
sessionIndexThe index of the current session for this user (same as domain_sessionidx).Yes
eventIndexOptional index of the current event in the session. Signifies the order of events in which they were tracked.No
previousSessionIdThe previous session identifier (UUID) for this user.No
storageMechanismThe mechanism that the session information has been stored on the device.Yes
firstEventIdThe optional identifier (UUID) of the first event id for this session.No
firstEventTimestampOptional date-time timestamp of when the first event in the session was tracked.No

Please note that the session context entity is only available since version 3.5 of the tracker.

Starting a new session

The tracker automatically tracks session information and implements session timeouts after which the session is reset.

However, in case you want to trigger a new session manually (e.g., after logging out a user), you can use the newSession call to do that.

This will expire the current session and start a new session.


On session update callback

The onSessionUpdateCallback option, allows you to supply a callback function to be executed whenever a new session is generated on the tracker.

The callback's signature is: (clientSession: ClientSession) => void where clientSession includes the same values as you would expect on the client_session context.

Note: The callback is not called whenever a session is expired, but only when a new one is generated.


Please note that the session context entity is only available since version 3.11 of the tracker.

Whenever an event fires, the tracker creates a session cookie. If the cookie didn’t previously exist, the tracker interprets this as the start of a new session.

By default the session cookie expires after 30 minutes. This means that a user leaving the site and returning in under 30 minutes does not change the session. You can override this default by setting sessionCookieTimeout to a duration (in seconds) in the initial tracker configuration object. For example,

sessionCookieTimeout: 3600

would set the session cookie lifespan to an hour.

Was this page helpful?