VTEX’s Sessions System is a new architecture that allows stores to use new platform features and potentialize its use. With the installation of the new sessions system, your store will be able to handle complex B2B scenarios, will be able to regionalize the experience of your customer and perform promotions segmentations by Campaign Audiences.
Functioning of the Sessions System
Cookie vtex_session
The Sessions System identifies, through the vtex_session
cookie, the information of a specific session of a user browsing in your store.
It is possible to see the properties of a sessions by doing a GET
on the route {{accountname}}.{{environment}}.com.br/api/sessions?items={{namespace}}.{{value}},{{namespace}}.{{value2}}
.
In the JSON reply, the API returns several namespaces. The namespaces are the keys that group together certain types of information about the session.
Below, you may see the example of reply with basic data on a session:
_32{_32 "id": "840f8910-eb3b-4f25-8d51-a06445317906",_32 "namespaces": {_32 "account": {_32 "id": {_32 "value": "0e914df8-c516-45bc-a45a-0aab6482eaf7",_32 "keepAlive": true_32 },_32 "accountName": {_32 "value": "qamarketplace"_32 }_32 },_32 "store": {_32 "channel": {_32 "value": "1"_32 }_32 },_32 "impersonate": {_32 "canImpersonate": {_32 "value": "false"_32 }_32 },_32 "profile": {_32 "isAuthenticated": {_32 "value": "false"_32 }_32 }_32 },_32 "version": 1,_32 "active": true,_32 "debug": false_32}
Below you will find a list of possible namespaces that can be returned by the API:
account
: Namespace with account information where the session is happening.checkout
: Namespace with information related to checkout, such as session cart ID (cartId
) and region (regionId
) that the checkout returns to identify the geographic location of the user browsing this session.store
: Namespace with information about the current sales channel of the session.cookie
: Namespace with information on the authentication cookies of the user.impersonate
: Namespace that identifies if the logged in user has permission to impersonate another user and browse on that user’s behalf.profile
: Namespace with information related to the customer’s profile logged into that session. Eligible price tables for that customer are listed in this namespace.public
: Namespace with general information on a session,utm_campaign
,utm_source
andutmi_campaign
. In this namespace, we also find information aboutcountry
andpostalCode
, which are given to VTEX’s checkout so that it can return theregionId
, require in the namespacecheckout
.authentication
: Namespace with user authentication data in the context of the session.rnb
: Namespace that gives information related to applicable Campaign Audiences and promotions for that session.
Cookie vtex_segment
VTEX Sessions also creates the cookie vtex_segment
. This cookie contains the information with the commercial conditions to be applied to a session.
It is possible to see the properties of a segment by doing a GET
on the route {{accountName}}.{{environment}}.com.br/api/segments/{{segmentToken}}
Below you will find an example of answer with data from a segment:
_10{_10 "campaigns": "vip",_10 "channel": "1",_10 "priceTables": "gold",_10 "regionId": "U1cj",_10 "utm_campaign": "black friday",_10 "utm_source": "google",_10 "utmi_campaign": "banner"_10}
It’s important to stress that the session identified by the cookie vtex_session
is individual. However, the cookie vtex_segment
uses information that can be shared among different users. For example: the same price table can be available to different users in distinct sessions. This way, vtex_segment
is used to control the cache key of the pages.
Changing information from a session
It is possible to change a session’s information by performing a POST
on the following route:
{{account-name}}.{{environment}}.com.br/api/sessions/{{session_token}}
Below you can see an example of a body
used to update the information of a session:
_13{_13 "public": {_13 "utm_campaign": {_13 "value": "Black Friday"_13 },_13 "country": {_13 "value": "USA"_13 },_13 "postalCode": {_13 "value": "05408000"_13 }_13 }_13}
Main features related to the Sessions System
Price Tables
The feature Price Table is identified by the sessions system in the namespace profile
. The price table displays customized prices for that identified user that is browsing in the store. You can create price table for specific customer groups. The Price Tables can by used mainly to handle B2B scenarios. To configure the price tables in your store, access our documentation about how to configure Price Tables
Region
The region feature is identified by the sessions system in the namespace checkout
, with the regionId
property, which is generated when a postalCode
and a country
are added to a session. The feature’s objective is to regionalize the experience of the user in the store. It allows, for example, sellers to configure their own prices and marketplaces to display according to the customer’s region. To configure price and availability according to the customer’s region, access our article about setting up SKU price and availability by Region.
Campaign Audiences
Campaign Audiences are clustering rules that allow promotions to be applied to customers that meet the campaign rules. The Campaign Audiences feature works much like Price Tables. In the Promotions & Taxes module, you can create conditions that apply a promotion to a particular customer if campaign conditions are met.