commercetools Frontend provides a session mechanism to its extensions. Any action extension can read and write the session, while other extension types can only read the session.
Reading the session works through the property
Write the session
The mechanics to use the session in an action schematically works as follows:
As a first step, the action code ensures to have properly initialized
sessionData. During the execution of the action, the session data is updated (in this case, the value
42 is stored). Eventually, the
sessionData is returned as part of the
If you return
sessionData from an action, you need to maintain all session information that you didn't touch. If you only return the session key written by the action, all other session data will be lost. commercetools Frontend doesn't perform merge on the session but only stores the returned
A complete example looks like this:
This example is an extended version of the action extension example we used in the developing an action extension article. In addition to searching for characters, the action now stores statistics about the Star Wars movie preferences of the user, calculated by looking at the first result of the character search.
If you want to reproduce this complete example, find the code for calculating movie preference statistics at the end of this article.
Read the session
sessionData is possible in any extension since it's part of the
Request object. As could already be seen, an
action extension receives the
Request directly as its input. All other extension types receive the
Request as part of their corresponding context data. For example, the following
data-source extension can be used to read the tracked
DataSourceContext carries the
Request, which in turn carries
sessionData (which might be empty if no session was written before!).
Direct session access in the frontend code is prohibited because the session might contain sensitive data, such as access tokens. For this reason, the session JWT token is encrypted in production. To use parts of the session in a component, you need to expose this part selectively through a
action as shown in this example.
Session encryption is a pending feature and hasn't been implemented yet. It'll be delivered soon.
Once this data source is registered in studio (see the Developing a data source extension article for more information), a Frontend component can use the exposed part of the
sessionData, for example like this:
Caveats with session
When there are multiple actions writing to the session, the last one to finish executing wins. This might lead to unexpected behavior in non-deterministic implementations.
Consider you give your customers 50 reward points each time they add an item to the cart and 20 when they add it to the wishlist. The application stores the customer’s reward points in the
sessionData and batch the updates for reward points to increase efficiency.
updateRewardPoints function below initiates all the updates in the order the customer interacted with the application.
In the above example, the customer should end up with the same reward points as they started with. But, because the updates are network calls and each request can take a different time to start, execute and return the final state of the session becomes un-deterministic. The diagram below shows a scenario where
deductFiftyRewardsPoints takes the longest to execute.
To avoid this pitfall, you need to write deterministic code. The above example can be re-implemented using
async/await to happen in a sequential and deterministic manner.
Movie preference calculation
The following code is used to calculate movie preferences in the action example we used earlier in this article: