Skip to content

Visitor identification

In order to connect events with visitors over the course of a session, the visitors must be identified by Elevate. This can occur on two levels, by device and by actual visitors. All visitors can experience device-based personalisation through an assigned randomized customer key.

To enable cross device personalisation and personalized recommendations off-site, such as with Email recommendations, an identifier tied to the visitor is required. This is normally only applicable for signed in visitors and requires a secret visitor identifier.

Selecting visitor identifier

The identifier must uniquely identify the visitor, but must not be an externally known customer property such as a user name, email address, or social security number as that is a personal data breach liability and against the EU General Data Protection Regulation.

The identifier must however be possible to obtain given a visitor, regardless of device and site, where personalisation is to have any effect. For example, to enable personalized email recommendations, it must be possible to access the identifier within the email service provider.

A retailer will typically have their own internal identifier systems for visitors, such as using identification tables or secret hashing of visitor data, to enable personalisation. This type of internal identification will likely only be able to provide personalisation for members or signed in visitors to a retailer's site.

Identical customer keys

For any external use, such as Email recommendations, the same identifier used on the site must be supplied. This means that the customerKey argument provided to Email recommendations must match the customerKey that is set when a visitor signs in to a retailer's site.

API integration

Both device based and visitor based personalisation must be integrated with the 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 previously assigned customer key with a secret visitor identifier to be used in future requests.
  4. When a visitor signs out, reset the session:
    • Signal closing of the current session through an end notification with the secret visitor identifier as the customer key in the notification.
    • Randomize a new customer key and replace the previously assigned secret visitor identifier.

For client side integrations, the JavaScript library, esales-api, offers support for working with session keys and customer keys.

Linked keys

If more than one customer key is provided for a session, Elevate will automatically link them together. An example of this is when a session is started with a visitor that is not signed in to the site at first. The visitor still triggers events in the session. While the session is still active, the visitor signs in to the site thus creating a new or activating a pre-existing customer key.


A session is a group of interactions within a given time-frame. An Elevate session starts when a visitor triggers a request and ends when an end notification is sent to Elevate, or when a criteria for automatically ending a session is met. A session automatically ends after:

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.

Example 1: A session starts 13:00 with a Landing Page request. This session will end at 13.15 due to inactivity 13:00-13:15 (15 minutes inactivity). This session will be considered a bounce session since the session span is less than 1 second and has no notifications. 13:05 a new query is sent with the same session key. This session will end at 13:20 due to 15 minutes inactivity (15 minutes inactivity). This session will not be considered a bounce session since the session span is not less than 1 second.
Example 2: A session starts 13:30 and includes a click request. No more requests after 13:45. This session will end at 15:00 due to inactivity between 14:00-15:00 (1 hour inactivity starting from the beginning of the hour).

Rules for usage of session keys

Note the following with regards to session keys:

  • A session key must be connected to a unique Elevate visitor and must not be reused.
  • An Elevate invocation must be performed for a visitor when caching on the site is done, even if a cached response is sent to the end customer. Notifications of events on the site must always be sent to Elevate with the visitor's session key.
  • In a production environment, notify = false must not be sent to reduce the number of sessions.

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.