Skip to content

Sessions and Notifications

A session is a core concept with eSales. A session starts when a visitor arrives at a site and ends when an end notification based on the personalisation strategy is sent to eSales. During a session, notifications about visitor actions, so called events, are sent back to eSales.

Sessions, together with notifications, not only enable basic eSales functionality, but also enable personalised content and help eSales continuously improve recommendations and search results.

An event can be a visitor clicking the rendering of a product returned by eSales. Another example of an event is when a visitor adds a product variant to their cart based on the search result returned by eSales. In short, events are user interactions with a site.

Content that is rendered by eSales, such as products and ads, all have a unique string identifying them called a ticket. Tickets are generated automatically by eSales and include encoded information about the rendered item, its panel path, and more.

Notification types

The following notification types are supported in the eSales Web API:

  • Click: Sent when the visitor clicks on a product, ads or others eSales entities.
  • Non-eSales click: Sent when the visitor clicks on a product not returned by eSales (i.e. not having a ticket).
  • Adding-to-cart: Sent when the visitor adds a product to their cart.
  • Non-eSales adding-to-cart: Sent when the visitor adds a product not returned by eSales (i.e. not having a ticket) to their cart.
  • Payment: Sent when the visitor has placed an order.
  • End session: Sent when the visitor signs out.

Read more about implementation of Notifications in the JavaScript library documentation and RESTful API documentation.

Visitor identification

In order to connect an event with a visitor, the visitor must first be identified by eSales. This is done with Session objects. By adding a so called customer key when the Session object is created and including it in all requests sent to eSales within the session, the visitor will remain identified.

A customer key is a unique user identifier. By default this is a random number generated by the JavaScript and is stored in a cookie to be re-used when a visitor returns.

User names or e-mail addresses of signed in visitors should not be used directly as customer keys as that is against the EU General Data Protection Regulation.

If more than one customer key is provided for a session, eSales 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 an new or activating a pre-existing customer key.

This means that personalised content from eSales will be based on the behavioural data from all former sessions using either of those customer keys. This is a powerful way of providing personalised content across different platforms and touch points, but if erroneously implemented can result in strange or irrelevant recommendations.

Identifying visitors that are not signed in

There are a wide range of techniques to identify visitors that are not signed in. The standard technique, which Apptus recommends, is to use cookies. All implementation suggestions will assume that cookies is the chosen technique for identifying customers.

Identifying returning visitors across devices

Returning visitors using the same device and browser as with previous visits are identified with the generated customer keys stored in cookies while they are signed in to the site. A visitor must sign in to the site to receive cross device personalisation.

A personal customer key is generated when a visitor signs in to the site. For the Web API v2 this must be a UUID v4 supplied by the retailer. For the Web API v1, the class CustomerKeyAuthentication must be implemented to generate a personal customer key and an additional authorization token. The authorization token is used to verify the customer key in the eSales Web API v1 service.

The personal customer key should be stored by the retailer for each visitor.

Level of personalisation

Level of personalisation can also be referred to as notification strategy. The level of personalisation determines how sessions, visitor identification, and notifications is to be implemented and managed. This will affect how behaviour data is managed and how results and personalised content is presented.

All levels of personalisation allow for visitor identification across devices as soon as a visitor signs in and a personal customer key is specified.

Low level of personalisation

  • When it is considered a risk with significant impact that user data possibly could leak between different visitors using the same device and browser.
  • If visitors on the site signs in to a high degree at an early stage.

Pros

  • eSales functions will never produce a result based on the behavioural data from sessions with other visitors.

Cons

  • All functions that are based on visitor information will not perform to its full potential until the visitor signs in. A result of this is that when the visitor returns to the site a second time without signing in, personalisation such as recommendations will not be given properly.

Implementation guidelines

  • When a visitor signs in to the site, a customer notification is made using the visitors’ unique identification for the site.
  • When a visitor signs out, the ongoing eSales session should be ended explicitly.

Medium level of personalisation

  • When visitors should be able to "clear" their actions by signing out from a browser but still have room for personalisation in between visits to the site.
  • When signed in visitors never should be able to affect each other's content.

Pros

  • Personalised content persists of multiple session of the user does not sign in. I.a. a visitor that browses the site a few days without signing in will get recommendations based on previous browsing.
  • eSales functions will never produce a result based on the behavioural data from sessions with other signed in visitors.

Cons

  • All functions that are based on visitor information will not perform to its full potential when a visitor has signed out and then returns to the site using the same browser. A result of this is that when the visitor returns to the site a second time without signing in, personalisation such as recommendations will not be given properly.

Implementation guidelines

  • When a visitor enters the site, look for a unique identifier stored in the cookies and notify this value to eSales. If no such value is present, a new one is created and stored. This could be a randomly generated value.
  • When the visitor signs in to the site, a customer notification is made using the visitor's unique identification for the site.
  • When the visitor signs out, the ongoing eSales session should be ended explicitly. The value of the unique identifier stored in the cookie should also be regenerated and overwritten. Any new action should be treated as if it is a new visitor to the site, i.e. make a new customer notification the “new” session using the new identifier. Note that from an eSales perspective, the session_id can be reused if the previous session as been explicitly ended. These sessions will not be linked.

High level of personalisation

  • When it is considered that the impact of user data possibly leaking between different visitors using the same browser is very low.
  • When using personalised content before a visitor signs in, such as on a start page.

Pros

  • Personalised content persist event if the visitor signs out. This will have the strong benefit of being able to give personalised content to visitors who have not yet signed in. This enables the use of personalised content on a start page.

Cons

  • Personalised content persist event if the visitor signs out. This may be negative if the content could be considered as especially personal. The visitor cannot easily make the personalised content disappear. This is however only visible for another visitor using that same device and browser.
  • If multiple visitors share a device and browser, their behavioural data will be linked together. As a result, a visitor could potentially get content based on other visitors actions. For most sites this is a very rare scenario.

Implementation guidelines

  • When a visitor enters the site, look for a unique identifier stored in the cookies and notify this value to eSales. If no such value is present, a new one is created and stored. This could be a randomly generated value.
  • When the visitor signs in to the site, a customer notification is made using the visitor's unique identification for the site.

Notification set-up recommendations

The following list items are recommendations when implementing notifications to a site with eSales.

  • Always notify eSales when clicks are made on eSales content such as products and ads. Notifying clicks on categories is not necessary.
  • Always notify eSales when a product is added to cart with an "addtocart"-notification
  • Notify all purchased carts to eSales when they happen
  • Notify cost, quantity, and selling price for each purchased item in the cart
  • Session-handling must support the selected level of personalisation
  • Market must be present on all notifications
×