Skip to main content
With the $wsSession module, you can read out the customer’s session data in the frontend and set your own session variables. This allows you to display personalized content, track user behavior, or check the session status during payment processes. In this section, you will learn how to read and write session data.

​
Module overview

Example / excerpt of $wsSession 
{{= $wsSession | json }}
JSON output 
{
  "id": "...",
  "referer": "...",
  "userReferer": "...",
  "isInvalid": false,
  "isLocked": false,
  "get": "ƒ()",
  "set": "ƒ()"
}
Note: ƒ() denotes a function. Variables and methods overview
NameReturn typeDescription
idstringReturns the ID of the current session.
refererstringReturns the external page through which the user reached the shop (e.g. Google, Facebook).
userRefererstringReturns a freely definable value that the user has set in the shop. It is set via an input field named ws_user_ref in the template.
isInvalidbooltrue if the session is invalid, otherwise false.
isLockedbooltrue if the session is locked (payment process), otherwise false.
set()-Sets a session variable.
get()stringReturns the value of a session variable previously stored with set().

​
Templates

The data of the $wsSession module can be accessed in all templates.

​
Variables

​
$wsSession.id

Returns the ID of the current session. 
Session ID: {{= $wsSession.id }}

​
$wsSession.referer

Returns the external page through which the user reached the shop, for example a search engine or a social network. The value is automatically set on the first page view and is also included in the order data. 
Referer: {{= $wsSession.referer }}

​
$wsSession.userReferer

Returns a freely definable value that the user has set in the shop. It is set via an input field named ws_user_ref in the template. Whether and how the field is used is determined by the respective template design. The value is also included in the order data. 
User referer: {{= $wsSession.userReferer }}

​
$wsSession.isInvalid

Checks whether the session is valid. Returns true if the session is invalid. 
{{ if $wsSession.isInvalid }}
  // The session is invalid.
{{ else }}
  // The session is valid.
{{ /if }}

​
$wsSession.isLocked

Returns true if the session is locked. A lock occurs during online payment processes (e.g. PayPal, Klarna) to prevent parallel changes to the basket. 
{{ if $wsSession.isLocked }}
  // Session is locked due to payment process
{{ else }}
  // Session is not locked
{{ /if }}

​
Methods

​
$wsSession.set()

Sets a session variable. These values remain valid across all subsequent pages until they are overwritten or deleted. Signature
$wsSession.set(key, value) Parameters
NameTypeRequiredDescription
keystringyesName of the session variable.
valuestringyesValue of the session variable.
Example that stores a category in the session. 
{{ $wsSession.set("lastViewedCategory", "Running shoes") }}

​
$wsSession.get()

Returns the value of a session variable previously stored with set(). Returns an empty string if the variable does not exist. Signature
$wsSession.get(key) Return value
string - Value of the session variable. Parameters
NameTypeRequiredDescription
keystringyesName of the session variable.
Example that reads out a stored category. 
{{ if $wsSession.get("lastViewedCategory") }}
  Category: {{= $wsSession.get("lastViewedCategory") }}
{{ /if }}

​
Actions

Actions for this module are documented separately in the actions chapter: Session

​
Examples

​
Output the current session ID

<!-- Outputs ID of the current session -->
{{= $wsSession.id}}

​
Check whether the session is locked

A session can be temporarily locked when a buyer chooses a payment method with online clearing that redirects them to an external page (e.g. PayPal, credit card, Sofortüberweisung). During the lock, no further actions are possible in the shop in order to prevent inconsistencies – for example, if the customer adds products in another tab. The lock is released as soon as the buyer completes or cancels the payment process. Should this not be possible (e.g. if the external system is unreachable or the payment window was closed), the buyer can start a new session. The basket and login are retained. If the buyer accesses the shop during a lock, a notice message can be displayed: 
{{ if $wsSession.isLocked }}
   <p>Your session is locked due to a pending payment process.</p>
{{ else }}
   <p>Your session is not locked.</p>
{{ /if }}

​
Unlock session

If a session is locked due to a pending payment process, the buyer can manually unlock it by starting a new session. The current basket, all previous entries, and the login are retained. This is helpful when the payment process could not be completed, e.g. due to a closed payment window or a technical problem on the external payment page. 
{{ if $wsSession.isLocked }}
   ...
   {{ var $sessionUnlockAction = $wsActions.create("SessionUnlock") }}
   <form method="post" action="{{= $wsViews.current.url() }}">
       <input type="hidden" name="wscsrf" value="{{= $sessionUnlockAction.csrf }}">
       <input type="hidden" name="wstarget" value="{{= $wsViews.current.url() }}">
       <input type="hidden" name="wsact" value="{{= $sessionUnlockAction.id }}">
       <button type="submit">Unlock</button>
   </form>
{{ else }}
   ...
{{ /if }}

​
Set and query specific session data

With the $wsSession.set function, individual values can be stored in a user’s current session. These values remain valid across all subsequent pages until they are overwritten or deleted. This can be used for various purposes, e.g. to:
  • Save user preferences (e.g. preferred language or category).
  • Control dynamic shop displays based on previous behavior.
  • Make customer-specific adjustments for a personalized shopping experience, and much more.
Suppose a customer navigates to a specific category, e.g. “Running shoes”. You can store this information in the session to use it on other pages. 
{{ $wsSession.set("lastViewedCategory", "Running shoes") }}
This information can then be used on subsequent pages to display relevant content and product recommendations to the user: 
{{ if $wsSession.get("lastViewedCategory") }}
   <h1>Discover new products in the category {{= $wsSession.get("lastViewedCategory") }}.</h1>
     
{{ /if }}

​
Access to session data using the example of the referer

With $wsSession, various values stored in the session can be read out and used. One example is the referer, which indicates from which external page the user reached the shop. This can be useful to analyze whether visitors came via a search engine, an advertisement, or a partner link, for example. 
<p>Referer: {{= $wsSession.referer }}</p>

​
Read URL parameter and set session variable

Suppose there is a URL parameter promoCode that determines whether a special advertising banner for a discount campaign should be displayed. If this parameter is present and has a specific value, a session variable is set, which is then read out on other pages. 
https://www.beispielshop.de/?promoCode=SUMMER2024
  or
https://www.beispielshop.de/?promoCode=WELCOME10
When a page is opened, it is checked whether the promo code was passed as a URL parameter. If so, the value is stored in the session so that it can be evaluated later. 
{{ if $wsViews.current.params.promoCode }}
    {{ $wsSession.set("activePromo", $wsViews.current.params.promoCode) }}
{{ /if }}
Now, on another page, it can be checked which promo code was stored in order to output an appropriate discount banner: 
{{ if $wsSession.get("activePromo") == "SUMMER2024" }}
    <div class="promo-banner">
        <p>🔥 Summer special! <strong>10% off</strong> with the code SUMMER2024!</p>
    </div>
{{ elseif $wsSession.get("activePromo") == "WELCOME10" }}
    <div class="promo-banner">
        <p>🎉 Welcome! <strong>€10 off</strong> on your first order with WELCOME10!</p>
    </div>
{{ else }}
    <div class="promo-banner">
        <p>🛍️ Shop now and discover exclusive offers!</p>
    </div>
{{ /if }}