$wsCookie - Browser cookies - WEBSALE Dokumentation

With the $wsCookie module, you read, set, update, and delete browser cookies directly in the template. Cookies store information per visitor across multiple page views, for example a chosen display variant, a personal greeting, or a remembered consent. This page covers only the reading and writing of cookies themselves. How you check the user’s consent is described in $wsConsent.

Note: Setting cookies may require user consent depending on the type (technically necessary vs. marketing/tracking). Use $wsConsent.checkAllowed() to verify consent before setting non-essential cookies.

Basic concept

Cookies always follow the same flow: Set → Read → React.
Before you can read a cookie, it must first be set. A cookie is always set by an event. Typical triggers are:

a user action (clicking a toggle or link),
a state (the customer logs in),
a dependency (a specific customer data field is present),
the entry path (access via a campaign link or referrer).

On the next page view, you read the value back and react to it, for example with a different display or a personal greeting. Important regarding the time of execution:
The template code is executed when the page is built, not when the user clicks. A cookie is therefore not set at the moment of the click, but only when the click triggers a new request and the template is executed again. Always plan the setting along a page view.

Naming scheme (applies to all methods)

The shop automatically renames its own cookies according to the scheme wsvx_<shopId>_cookie<name>. setCookie("test", …) in the shop example becomes the cookie wsvx_example_cookietest in the browser. In the methods, you always work only with the short name (test); the shop adds the prefix itself. This avoids conflicts with other cookies. Setting and reading use the same scheme. A cookie set with setCookie("test", …) can therefore be read again directly with getCookie("test"), without worrying about the long name. Exception: externally set cookies
Cookies that were not set by the shop (e.g. via custom JavaScript, a third-party tool, or a cookie banner) keep their original name. The automatic scheme would not match them. If you want to read such a cookie, pass the keepNameAsIs: true option to getCookie so that the name is used unchanged. This option is not available for setting, updating, or deleting, because external cookies are usually managed by the tool that set them.

Module overview

Example / excerpt of $wsCookie

{{= $wsCookie | json }}

JSON output

{
  "deleteCookie": "ƒ()",
  "getCookie": "ƒ()",
  "setCookie": "ƒ()",
  "updateCookie": "ƒ()"
}

Note: "ƒ()" indicates a function. Methods at a glance

Method	Return type	Description
`getCookie()`	string	Reads the value of a cookie by its name.
`setCookie()`	–	Sets a new cookie.
`updateCookie()`	string	Updates the value of an existing cookie.
`deleteCookie()`	–	Deletes a cookie by its name.

Templates

All four methods are template functions and are available in every .htm template. The typical flow (Set → Read → React) is described in the Basic concept section.

Variables

No variables are available for $wsCookie.

Methods

$wsCookie.getCookie()

Reads the value of a cookie by its name. Signature
$wsCookie.getCookie(name, [options]) Return
string – value of the cookie. The value is empty if no cookie with this name exists. Parameters

Name	Type	Required	Default	Description
`name`	string	yes	–	Short name of the cookie, without prefix.
`options`	map	no	–	`keepNameAsIs` (bool) – uses the name unchanged, without the automatic scheme. Required for externally set cookies (see Basic concept).

Example that reads a stored display variant.

{{ var $currentTheme = $wsCookie.getCookie("wsThemeColor") }}

$wsCookie.setCookie()

Sets a new cookie. Signature
$wsCookie.setCookie(name, value, [age]) Return
– (no return value) Parameters

Name	Type	Required	Default	Description
`name`	string	yes	–	Short name of the cookie, without prefix.
`value`	string, int, float, list, map, bool	yes	–	Value of the cookie. Complex values (list, map) are stored internally as JSON automatically.
`age`	int	no	Session	Validity period in seconds. Without a value, a session cookie is set, which expires at the end of the browser session. Maximum 10 years. Example: `31536000` = 365 days.

Example that sets a display variant.

{{ $wsCookie.setCookie("wsThemeColor", "dark") }}

Example that sets a cookie with a validity period of 365 days.

{{ $wsCookie.setCookie("welcomeBackName", $wsAccount.displayName, 31536000) }}

$wsCookie.updateCookie()

Updates the value of an existing cookie. Signature
$wsCookie.updateCookie(name, value) Return
string – new value of the cookie. Parameters

Name	Type	Required	Default	Description
`name`	string	yes	–	Short name of the cookie, without prefix.
`value`	string, int, float, list, map, bool	yes	–	New value of the cookie.

Example that updates a display variant.

{{ $wsCookie.updateCookie("wsThemeColor", "light") }}

$wsCookie.deleteCookie()

Deletes a cookie by its name. Internally, the lifetime is set to -1, which causes the browser to discard the cookie immediately. Signature
$wsCookie.deleteCookie(name) Return
– (no return value) Parameters

Name	Type	Required	Default	Description
`name`	string	yes	–	Short name of the cookie, without prefix.

Example that deletes a previously set cookie.

{{ $wsCookie.deleteCookie("wsThemeColor") }}

Actions

No actions are available for $wsCookie.

Examples

The following examples are ordered from simple to more complex: from a state, through a user action and the entry path, to an externally set cookie. The trigger here is the “login” state. When the customer opens the shop, they are greeted personally, even if they are not logged in, provided they have logged in at least once before. This preserves a personal touch without requiring the customer to stay logged in permanently. Step 1: Set the cookie on login As soon as the customer has logged in, their display name is stored in the cookie. If the display name is missing or empty, the email address is used instead. The third parameter specifies the validity period in seconds (here 365 days), so that the greeting is preserved over a longer period.

{{ if $wsAccount.isLoggedIn }}
  {{ var $welcomeName = $wsAccount.displayName }}
  {{ if not $welcomeName }}
    {{ $welcomeName = $wsAccount.email }}
  {{ /if }}
  {{ $wsCookie.setCookie("welcomeBackName", $welcomeName, 31536000) }}
{{ /if }}

Step 2: Display the greeting on any page On any page, for example the home page, you read the name and display the corresponding greeting. If no cookie is present, because the customer has never logged in or the cookie has expired, nothing is displayed.

{{ var $name = $wsCookie.getCookie("welcomeBackName") }}
{{ if $name }}
  Welcome back, {{= $name }}!
{{ /if }}

Result
Returning customers see their personal greeting until the cookie expires or is deleted.

Note: This cookie contains personal data. Check consent via $wsConsent.checkAllowed() and refer to the cookie policy on the home page.

Storing a display variant (e.g. dark mode)

The trigger here is a user action, namely a click. Since WEBSALE does not work with a theme system, you have to create a display variant yourself. To do this, you store the user’s choice in a cookie and load the matching style sheet when the page is built. Step 1: Provide the trigger The user chooses the variant via a link. The click triggers a page view, and only then can the value be set (see time of execution).

<a href="?theme=dark">Enable dark mode</a>
<a href="?theme=light">Disable dark mode</a>

Step 2: Write the choice to the cookie when the page is built The validity period of 365 days (in seconds) ensures that the choice is preserved beyond the session. Without this value, it would only be a session cookie and the setting would be lost after closing the browser.

{{ if $wsViews.current.params.theme }}
  {{ $wsCookie.setCookie("wsThemeColor", $wsViews.current.params.theme, 31536000) }}
{{ /if }}

Step 3: Read on every page view and load the matching style sheet The cookie only stores the choice. The visible change is created by the matching style sheet. That’s why there is a switch between the dark and light variant.

{{ var $currentTheme = $wsCookie.getCookie("wsThemeColor") }}
{{ if $currentTheme == "dark" }}
  <link rel="stylesheet" href="/css/theme-dark.css">
{{ else }}
  <link rel="stylesheet" href="/css/theme-light.css">
{{ /if }}

Result
The chosen variant is preserved across all page views until the user switches it.

Onsite personalization: audience-specific content

The trigger here is the entry path, i.e. a campaign link through which the visitor enters the shop. Unlike the personal greeting, this is true onsite personalization: you display different content on the shop pages depending on a characteristic of the visitor. The scenario: A pet supplies shop sends separate newsletters to cat and dog owners. Via the link in the newsletter, the shop remembers the target group and from then on shows matching content. Step 1: Campaign link in the newsletter The links in the newsletter carry the target group as a parameter:

<a href="https://your-shop.com/?kundengruppe=katze">To our offers for cats</a>
<a href="https://your-shop.com/?kundengruppe=hund">To our offers for dogs</a>

Step 2: Write the target group to the cookie when the page is built When the visitor opens the shop via the link, the template reads the parameter and stores the target group. The validity period of 30 days (2592000 seconds) ensures that the assignment is preserved on later visits as well.

{{ if $wsViews.current.params.kundengruppe }}
  {{ $wsCookie.setCookie("kundengruppe", $wsViews.current.params.kundengruppe, 2592000) }}
{{ /if }}

Step 3: Display the matching content on every page On the shop pages, you determine the target group and display the matching content. Important: A freshly set cookie can only be read on the next page view (see time of execution). On the first call via the campaign link, you therefore fall back on the parameter and only afterwards on the cookie. This way, the visitor already sees the right content when entering. If neither parameter nor cookie is present, you display neutral default content.

{{ var $gruppe = $wsViews.current.params.kundengruppe }}
{{ if not $gruppe }}
  {{ $gruppe = $wsCookie.getCookie("kundengruppe") }}
{{ /if }}

{{ if $gruppe == "katze" }}
  <h2>Our bestsellers for cats</h2>
  {{# banners and products for cat owners go here #}}
{{ else }}
  {{ if $gruppe == "hund" }}
    <h2>Our bestsellers for dogs</h2>
    {{# banners and products for dog owners go here #}}
  {{ else }}
    <h2>For cat and dog lovers</h2>
    {{# neutral default content as long as no target group is known #}}
  {{ /if }}
{{ /if }}

Result
Visitors from the cat newsletter see the cat content on every visit, visitors from the dog newsletter see the dog content. All others see the default content.

Note: The cookie value is readable in the browser and can be modified by the user. Therefore, use the target group only to display content, not for security-relevant decisions such as prices or access rights. Since this is not a technically necessary cookie, check the user’s consent beforehand.

The trigger here is a cookie that was set outside the shop, for example by your own JavaScript or by a third-party tool. Such cookies keep their original name and are not renamed automatically. To read them, pass keepNameAsIs: true. Otherwise, the shop will look for the renamed name and won’t find the cookie. In the example, a flag set via JavaScript indicates that an info popup has already been seen:

{{# The cookie was set via JavaScript:
    document.cookie = "infoPopupSeen=true"
    In the template we read it unchanged with keepNameAsIs. #}}
{{ var $popupSeen = $wsCookie.getCookie("infoPopupSeen", { keepNameAsIs: true }) }}
{{ if $popupSeen != "true" }}
  {{# Cookie not present, show info popup #}}
{{ /if }}

Result
The popup only appears as long as the externally set flag is missing.

​Basic concept

​Naming scheme (applies to all methods)

​Module overview

​Templates

​Variables

​Methods

​$wsCookie.getCookie()

​$wsCookie.setCookie()

​$wsCookie.updateCookie()

​$wsCookie.deleteCookie()

​Actions

​Examples

​Personal greeting (WelcomeBack cookie)

​Storing a display variant (e.g. dark mode)

​Onsite personalization: audience-specific content

​Reading an externally set cookie

​Further reading

Basic concept

Naming scheme (applies to all methods)

Module overview

Templates

Variables

Methods

$wsCookie.getCookie()

$wsCookie.setCookie()

$wsCookie.updateCookie()

$wsCookie.deleteCookie()

Actions

Examples

Personal greeting (WelcomeBack cookie)

Storing a display variant (e.g. dark mode)

Onsite personalization: audience-specific content

Reading an externally set cookie

Further reading