Session-context Tutorial
How to configure the Session Context Service
By default, an anonymous user session expires after one hour. You can refresh the anonymous session by sending a request to the Refreshing an anonymous token endpoint.
There is no timeout for logged customer sessions.
You can use the price matching mechanism based on a session context file values. For more information on how the price matching functionality works, check out How to use the price matching functionality in the Price Service Tutorials.
How to manage user sessions and session context files
Sessions and session context files can be managed both by your customers and employees.
In the following scenario, we are going to perform the following actions from the perspective of an employee:
Create one of the following user sessions (these requests are normally sent on the storefront, but are here for illustrative purposes):
To be able to manage a user session and its corresponding session context file, a session context must already exist. The session context (and session ID) is created when a cart is created. Until then, only the anonymous or customer token is available and there is no session context to retrieve or manage.
Create an anonymous user session
An anonymous user session starts when a non-logged user enters the storefront and sends a request to the Requesting an anonymous token endpoint. That request returns only an anonymous access token, no session context is created yet.
To test the endpoint, open the API reference or check the example of a curl request.
A session context, and its session ID, is created only when a cart is created for that user - when they add a product to the cart. Until then, only the anonymous token is returned. There is no session context resource to retrieve or manage. After the session context exists, the session ID should be preserved on the storefront, for example in user cookies.
Once a session context has been created (when a cart was created), it contains the following information:
cartId— present when a cart was created (session context is created at that time).customerId— this field is empty for anonymous users.currency— fetched from the site settings of the tenant's default site.targetLocation— fetched from the home base address specified in the tenant's default site's settings.siteCode— fetched from the site settings of the tenant's default site.
An anonymous customer's session is terminated if one of those two requirements is met:
The customer has logged in.
The session has reached its lifetime.
Create a customer session
The session is created when a customer logs in to the storefront. This means that the anonymous session that was established when the user entered the site is migrated into a customer session when a request is sent to the Logging in a customer endpoint.
If a session context already existed for the anonymous session (for example when a cart was created before login), the session ID and session context remain the same after login. If no cart was created yet, the session context is created only when a cart is created (after or before login).
To test the endpoint, open the API reference or check the example of a curl request.
Retrieve a session context by using a session Id
The session context is created when a cart is created - when a customer adds an item to the cart. The session-context details can be retrieved using the sessionId and include the following information:
cartId— if a cart was created during the anonymous session, the cart's Id is present. If not, adding products to cart triggers the Session Context Service, creates the session context if needed, and adds acartId.customerId— retrieved from the saas token returned during login, based on the user password provided.currency— fetched from thecustomerprefferedCurrencyentry in the customer's profile.targetLocation— fetched from the customer's profile. Either default shipping address, or default billing address. Empty if none of those exist.siteCode— fetched from thecustomerprefferedSiteentry in the customer's profile.
If any of these values are not present in the customer's profile, they are retrieved from the configuration on your main site.
The customer's session is terminated when the customer logs out.
Get the session ID
When retrieving the session-context details, you must supply the sessionId. It can be retrieved from the storefront or by sending the request to the Retrieving own session context endpoint with the customerToken - in the request. Then, the response includes the sessionId.
Example:
The response is:
Retrieve the session context by sending a request to the Retrieving a session context endpoint. Use the sessioncontext.context_manage scope.
To test the endpoint, open the API reference or check the example of a curl request.
The response is:
To test the endpoint, open the API reference or check the example of a curl request.
Add new attributes to the session context
If you want to personalize user experience on your website, you can add custom attributes to selected session contexts. Your attributes are not validated, as they are only stored in the Emporix Commerce Engine and can be deleted at any time. However, you can make the data actionable by incorporating a solution of your choice.
Example:
If you want to suggest products on the storefront that are relevant to the weather conditions near the user's location, you can add two new attributes: latitude and longitude to the session context. The data can be collected on the storefront every time a user enters your website, and it will be kept in the Emporix Commerce Engine. You can then implement a mechanism that uses the collected data, for example to display relevant products first, according to the weather.
For example, it's raining in the user's location, so the list of suggested products on the storefront prioritizes umbrellas and other rain equipment.
You can also implement a mechanism allowing users to manage and modify their own sessions and session contexts by calling the Adding a new attribute to a session context endpoint on the storefront.
In the following example, we add an attribute by sending a request to the Adding a new attribute to a session context endpoint with the sessioncontext.context_manage scope (with underscore in session_context).
To test the endpoint, open the API reference or check the example of a curl request.
The changes introduced to the session context are automatically applied to the user session to which the session context belongs.
Last updated
Was this helpful?