> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# $wsSession - Session data

> Reference for $wsSession: read the customer's session data and set custom session variables for personalized content and payment status checks.

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`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsSession | json }}
```

**JSON output**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "id": "...",
  "referer": "...",
  "userReferer": "...",
  "isInvalid": false,
  "isLocked": false,
  "get": "ƒ()",
  "set": "ƒ()"
}
```

**Note:** `ƒ()` denotes a function.

**Variables and methods overview**

| **Name**      | **Return type** | **Description**                                                                                                                       |
| ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string          | Returns the ID of the current session.                                                                                                |
| `referer`     | string          | Returns the external page through which the user reached the shop (e.g. Google, Facebook).                                            |
| `userReferer` | string          | 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. |
| `isInvalid`   | bool            | `true` if the session is invalid, otherwise `false`.                                                                                  |
| `isLocked`    | bool            | `true` if the session is locked (payment process), otherwise `false`.                                                                 |
| `set()`       | -               | Sets a session variable.                                                                                                              |
| `get()`       | string          | Returns 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
User referer: {{= $wsSession.userReferer }}
```

### \$wsSession.isInvalid

Checks whether the session is valid. Returns `true` if the session is invalid.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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**

| **Name** | **Type** | **Required** | **Description**                |
| -------- | -------- | ------------ | ------------------------------ |
| `key`    | string   | yes          | Name of the session variable.  |
| `value`  | string   | yes          | Value of the session variable. |

**Example** that stores a category in the session.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ $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**

| **Name** | **Type** | **Required** | **Description**               |
| -------- | -------- | ------------ | ----------------------------- |
| `key`    | string   | yes          | Name of the session variable. |

**Example** that reads out a stored category.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsSession.get("lastViewedCategory") }}
  Category: {{= $wsSession.get("lastViewedCategory") }}
{{ /if }}
```

***

## Actions

Actions for this module are documented separately in the actions chapter: [Session](/en/frontend/referenz/aktionen/session)

***

## Examples

### Output the current session ID

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<!-- 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:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ $wsSession.set("lastViewedCategory", "Running shoes") }}
```

This information can then be used on subsequent pages to display relevant content and product recommendations to the user:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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 }}
```

***

## Related links

* [Session](/en/frontend/referenz/aktionen/session)