Session management¶

Sessions¶

A session is a group of interactions within a defined time frame and forms the basis for tracking visitor behavior and enabling personalization in Elevate. Sessions are central to ensuring consistent user experiences, allowing Elevate to maintain context, preferences, and personalization as visitors navigate a site.

Session lifecycle¶

The session lifecycle outlines how Elevate internally defines and manages sessions for reporting, behavioral analysis, and more. This process is handled automatically and is intended for informational purposes only, requiring no explicit action from the integrator.

An Elevate session begins when a visitor triggers a request and ends either via an end notification or automatically when one of the following criteria is met:

• 15 minutes if there are no notifications for either click, add to cart, payment, add favorite, remove favorite, remove recent searches or remove recently viewed
• 1 hour of inactivity, counted from the start of each hour
• 00:00 UTC, regardless of activity

A session is considered a bounce session if the following conditions are met:

• The session spans less than 1 second.
• The session has no interactive notifications.

Examples¶

1. A session starts 13:00 with a Landing Page request. This session will end at 13.15 due to 15 minutes of inactivity. This session will be considered a bounce session.
2. A session starts 13:00 with a Landing Page request, followed by a new query 13:05. This session will end at 13:20 due to 15 minutes inactivity. This session will not be considered a bounce session.
3. A session starts 12:55 with a Landing Page request, followed by a click request at 12:58 and a new query at 13:05. This session will end at 15:00 due to inactivity between 14:00-15:00. This session will not be considered a bounce session.
4. A session starts 23:55 with a Landing Page request, followed by a click request at 23:58. This session will end at 00:00. This session will not be considered a bounce session.

Session handling requirements¶

The following practices must be followed in all production environments:

• Each session must be tied to a unique Elevate visitor, session keys must not be reused.
• Elevate requests must be made even when using caching.
• Event notifications must always be sent with the visitor's session key.
• In production, notify = false must not be used with the intent of limiting session volume.

Visitor identification¶

To connect behavior and events to individual users across and within sessions, visitors must be identified in Elevate. Identification can happen at two levels:

• Device-based – using a randomized customerKey, assigned to all visitors for basic personalization.
• Visitor-based – using a persistent, secret identifier tied to a known visitor (e.g., a signed-in user), which enables cross-device and off-site personalization such as Email recommendations.

Selecting visitor identifier¶

When a visitor is known to the site, typically by signing in, the retailer can use a persistent identifier to enable cross-device and off-site personalization. This identifier represents the visitor internally and must be chosen with care to ensure both privacy compliance and technical compatibility across systems.

The following requirements apply when selecting such an identifier:

• Must uniquely and consistently identify the visitor across devices, access points, and systems.
• Must not be an externally known property (e.g. email address, username, or social security number), as this could violate the EU GDPR.
• Must be possible to access wherever personalization is applied (e.g. in email platforms for personalized sends).

Retailers can typically generate persistent identifiers using internal systems, such as ID tables or hashed visitor data, to enable personalization for signed-in members.

Implementing visitor identification¶

The following steps outline how to manage visitor identifiers through the Elevate API:

1. When an unknown visitor triggers a request, assign the visitor a random customer key and set the assigned customer key to the request.
   • Use UUID v4 as initial randomized customer keys
   • Persist the randomized customer key for the visitor, for example in a cookie or local storage.
2. When a visitor with an already assigned customer key triggers a new request, set the assigned customer key on the request.
3. When a visitor signs in to the site or is otherwise identified, replace the current key with a secret visitor identifier for all future requests.
4. When a visitor signs out:
   • Retain the current customer key to maximize the level of personalization.

Client side integrations can use the JavaScript library, esales-api, which provides built-in support for managing customerKey and sessionKey.

Linked keys¶

If multiple customerKey values are used during a single session, Elevate will automatically link them. This typically happens when a visitor starts unauthenticated and then signs in—triggering a transition from a random key to a known identifier.

Consent and privacy¶

To comply with GDPR and other regulations, consent may be required before tracking visitors. If a visitor does not consent:

• Randomize both customerKey and sessionKey per request/notification.
• Include notify=false in all queries to prevent behavioral tracking.

Limitations¶

Randomizing keys breaks tracking continuity and limits or disables personalized features, such as:

• PERSONAL recommendations
• FAVORITES based recommendations
• Evolve functionality (e.g. integration with Voyado Engage)