> ## 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. # $wsCookie - Browser-Cookies > Modul $wsCookie zum Lesen, Setzen, Aktualisieren und Löschen einzelner Browser-Cookies im Template, z.B. für Darkmode oder Begrüßung. Mithilfe des `$wsCookie`-Moduls lesen, setzen, aktualisieren und löschen Sie [Browser-Cookies](/glossar#cookie) direkt im Template. Cookies speichern pro Besucher Informationen über mehrere Seitenaufrufe hinweg, zum Beispiel eine gewählte Darstellungsvariante, eine persönliche Begrüßung oder ein gemerktes Einverständnis. Auf dieser Seite geht es nur um das Lesen und Schreiben der Cookies selbst. Wie Sie die [Einwilligung](/glossar#consent) des Nutzers prüfen, ist in [\$wsConsent](/frontend/referenz/module/wsconsent) beschrieben. Hinweis: Das Setzen von Cookies kann je nach Art (technisch notwendig vs. Marketing/Tracking) eine Einwilligung des Nutzers erfordern. Prüfen Sie mit [\$wsConsent.checkAllowed()](/frontend/referenz/module/wsconsent#\$wsconsent-checkallowed) die Zustimmung, bevor Sie nicht-notwendige Cookies setzen. *** ## Grundkonzept Cookies folgen immer demselben Ablauf: **Setzen → Lesen → Reagieren.** \ Bevor Sie einen Cookie lesen können, muss er zuerst gesetzt werden. Gesetzt wird ein Cookie immer durch ein Ereignis. Typische Auslöser sind: * eine Benutzeraktion (Klick auf einen Toggle oder Link), * ein Zustand (der Kunde loggt sich ein), * eine Abhängigkeit (ein bestimmtes Kundendatenfeld ist vorhanden), * der Einstiegsweg (Aufruf über einen [Kampagnen-Link](/glossar#kampagnen-link) oder [Referrer](/glossar#referrer)). Beim nächsten Seitenaufruf lesen Sie den Wert wieder aus und reagieren darauf, etwa mit einer anderen Darstellung oder einer persönlichen Begrüßung. Wichtig zum Zeitpunkt der Ausführung: \ Der [Template-Code](/glossar#template-code) wird beim Seitenaufbau ausgeführt, nicht beim Klick. Ein Cookie wird also nicht im Moment des Klicks gesetzt, sondern erst dann, wenn der Klick eine neue Anfrage auslöst und das Template dabei erneut ausgeführt wird. Planen Sie das Setzen deshalb immer entlang eines Seitenaufrufs ein. ### Namensschema (gilt für alle Methoden) Der Shop benennt eigene Cookies automatisch um, und zwar nach dem Schema `wsvx__cookie`. Aus `setCookie("test", …)` im Shop `example` wird im Browser das Cookie `wsvx_example_cookietest`. In den Methoden arbeiten Sie immer nur mit dem kurzen Namen (`test`), das Präfix ergänzt der Shop selbst. So vermeiden Sie Konflikte mit anderen Cookies. Setzen und Lesen verwenden dasselbe Schema. Ein mit `setCookie("test", …)` gesetztes Cookie können Sie also direkt mit `getCookie("test")` wieder auslesen, ohne sich um den langen Namen kümmern zu müssen. **Ausnahme: Extern gesetzte Cookies**\ Cookies, die nicht vom Shop gesetzt wurden (z.B. über eigenes JavaScript, ein Drittanbieter-Tool oder ein Cookie-Banner), behalten ihren Original-Namen. Das automatische Schema würde hier ins Leere greifen. Wenn Sie ein solches Cookie auslesen möchten, übergeben Sie bei [getCookie](/frontend/referenz/module/ws-cookie-browser-cookie#wscookie-getcookie) die Option `keepNameAsIs: true`, damit der Name unverändert verwendet wird. Zum Setzen, Aktualisieren oder Löschen ist diese Option nicht vorgesehen, da externe Cookies in der Regel von dem Tool verwaltet werden, das sie gesetzt hat. *** ## Modulübersicht **Beispiel / Ausschnitt über** `$wsCookie` ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{= $wsCookie | json }} ``` **JSON-Ausgabe** ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "deleteCookie": "ƒ()", "getCookie": "ƒ()", "setCookie": "ƒ()", "updateCookie": "ƒ()" } ``` Anmerkung: `"ƒ()"` kennzeichnet eine Funktion. **Methoden in der Übersicht** | **Methode** | **Rückgabe-Typ** | **Beschreibung** | | ---------------- | ---------------- | -------------------------------------------------- | | `getCookie()` | string | Liest den Wert eines Cookies anhand seines Namens. | | `setCookie()` | – | Setzt ein neues Cookie. | | `updateCookie()` | string | Aktualisiert den Wert eines bestehenden Cookies. | | `deleteCookie()` | – | Löscht ein Cookie anhand seines Namens. | *** ## Templates Alle vier Methoden sind Template-Funktionen und stehen in jedem `.htm`-Template zur Verfügung. Den typischen Ablauf (Setzen → Lesen → Reagieren) beschreibt der Abschnitt [Grundkonzept](#grundkonzept). *** ## Variablen Für `$wsCookie` stehen keine Variablen zur Verfügung. *** ## Methoden ### \$wsCookie.getCookie() Liest den Wert eines Cookies anhand seines Namens. **Signatur**\ `$wsCookie.getCookie(name, [options])` **Rückgabe**\ `string` – Wert des Cookies. Der Wert ist leer, wenn kein Cookie mit diesem Namen existiert. **Parameter** | **Name** | **Typ** | **Pflicht** | **Standard** | **Beschreibung** | | --------- | ------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | ja | – | Kurzer Name des Cookies, ohne Präfix. | | `options` | map | nein | – | `keepNameAsIs` (bool) – verwendet den Namen unverändert, ohne das automatische Schema.
Nötig für extern gesetzte Cookies (siehe [Grundkonzept](#namensschema-gilt-für-alle-methoden)). | **Beispiel,** das eine gespeicherte Darstellungsvariante liest. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ var $currentTheme = $wsCookie.getCookie("wsThemeColor") }} ``` ### \$wsCookie.setCookie() Setzt ein neues Cookie. **Signatur**\ `$wsCookie.setCookie(name, value, [age])` **Rückgabe**\ – (kein Rückgabewert) **Parameter** | **Name** | **Typ** | **Pflicht** | **Standard** | **Beschreibung** | | -------- | ----------------------------------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | ja | – | Kurzer Name des Cookies, ohne Präfix. | | `value` | string, int, float, list, map, bool | ja | – | Wert des Cookies. Komplexe Werte (list, map) werden intern automatisch als [JSON](/glossar#json) gespeichert. | | `age` | int | nein | Session | Gültigkeitsdauer in Sekunden. Ohne Angabe wird ein [Session-Cookie](/glossar#session-cookie) gesetzt, das am Ende der Browser-Sitzung verfällt. Maximal 10 Jahre. Beispiel: `31536000` = 365 Tage. | **Beispiel,** das eine Darstellungsvariante setzt. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ $wsCookie.setCookie("wsThemeColor", "dark") }} ``` **Beispiel,** das ein Cookie mit einer Gültigkeitsdauer von 365 Tagen setzt. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ $wsCookie.setCookie("welcomeBackName", $wsAccount.displayName, 31536000) }} ``` ### \$wsCookie.updateCookie() Aktualisiert den Wert eines bestehenden Cookies. **Signatur**\ `$wsCookie.updateCookie(name, value)` **Rückgabe**\ `string` – neuer Wert des Cookies. **Parameter** | **Name** | **Typ** | **Pflicht** | **Standard** | **Beschreibung** | | -------- | ----------------------------------- | ----------- | ------------ | ------------------------------------- | | `name` | string | ja | – | Kurzer Name des Cookies, ohne Präfix. | | `value` | string, int, float, list, map, bool | ja | – | Neuer Wert des Cookies. | **Beispiel,** das eine Darstellungsvariante aktualisiert. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ $wsCookie.updateCookie("wsThemeColor", "light") }} ``` ### \$wsCookie.deleteCookie() Löscht ein Cookie anhand seines Namens. Intern wird die Lebensdauer dabei auf `-1` gesetzt, wodurch der Browser das Cookie sofort verwirft. **Signatur**\ `$wsCookie.deleteCookie(name)` **Rückgabe**\ – (kein Rückgabewert) **Parameter** | **Name** | **Typ** | **Pflicht** | **Standard** | **Beschreibung** | | -------- | ------- | ----------- | ------------ | ------------------------------------- | | `name` | string | ja | – | Kurzer Name des Cookies, ohne Präfix. | **Beispiel,** das ein gesetztes Cookie löscht. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ $wsCookie.deleteCookie("wsThemeColor") }} ``` *** ## Aktionen Für `$wsCookie` stehen keine Aktionen zur Verfügung. *** ## Beispiele Die folgenden Beispiele sind von einfachen zu komplexeren Fällen geordnet: vom Zustand über die Benutzeraktion und den Einstiegsweg bis hin zum extern gesetzten Cookie. ### Persönliche Begrüßung (WelcomeBack-Cookie) Auslöser ist hier der Zustand "Login". Der Kunde wird beim Aufruf des Shops persönlich begrüßt, auch wenn er nicht eingeloggt ist, sofern er sich zuvor einmal eingeloggt hat. So bleibt eine persönliche Note erhalten, ohne dass der Kunde dauerhaft angemeldet sein muss. **Schritt 1: Cookie beim Login setzen** Sobald sich der Kunde eingeloggt hat, wird sein Anzeigename im Cookie gespeichert. Fehlt der Anzeigename oder ist er leer, wird die E-Mail-Adresse verwendet. Der dritte Parameter gibt die Gültigkeitsdauer in Sekunden an (hier 365 Tage), damit die Begrüßung über einen längeren Zeitraum erhalten bleibt. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ if $wsAccount.isLoggedIn }} {{ var $welcomeName = $wsAccount.displayName }} {{ if not $welcomeName }} {{ $welcomeName = $wsAccount.email }} {{ /if }} {{ $wsCookie.setCookie("welcomeBackName", $welcomeName, 31536000) }} {{ /if }} ``` **Schritt 2: Begrüßung auf einer beliebigen Seite anzeigen** Auf einer beliebigen Seite, etwa der Startseite, lesen Sie den Namen aus und zeigen die entsprechende Begrüßung an. Wenn kein Cookie vorhanden ist, weil sich der Kunde beispielsweise nie eingeloggt hat oder das Cookie abgelaufen ist, wird nichts angezeigt. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ var $name = $wsCookie.getCookie("welcomeBackName") }} {{ if $name }} Willkommen zurück, {{= $name }}! {{ /if }} ``` **Ergebnis**\ Wiederkehrende Kunden sehen ihre persönliche Begrüßung, bis das Cookie abläuft oder gelöscht wird. **Hinweis:** Dieses Cookie enthält personenbezogene Daten. Prüfen Sie die Einwilligung über [\$wsConsent.checkAllowed()](/frontend/referenz/module/wsconsent#\$wsconsent-checkallowed) und weisen Sie auf der Startseite auf die Cookie-Richtlinien hin. ### Darstellungsvariante (z. B. Darkmode) speichern Auslöser ist hier eine Benutzeraktion, nämlich ein Klick. Da WEBSALE nicht mit einem Theme-System arbeitet, müssen Sie eine Darstellungsvariante selbst erstellen. Dazu legen Sie die Wahl des Nutzers in einem Cookie ab und laden beim Seitenaufbau das passende Stylesheet. **Schritt 1: Auslöser bereitstellen** Der Nutzer wählt die Variante über einen Link. Der Klick löst einen Seitenaufruf aus, erst dabei kann der Wert gesetzt werden (siehe [Zeitpunkt der Ausführung](#grundkonzept)). ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Darkmode aktivieren Darkmode ausschalten ``` **Schritt 2: Auswahl beim Seitenaufbau ins Cookie schreiben** Die Gültigkeitsdauer von 365 Tagen (in Sekunden) sorgt dafür, dass die Auswahl über die Sitzung hinaus erhalten bleibt. Ohne diesen Wert wäre es nur ein Session-Cookie und die Einstellung wäre nach dem Schließen des Browsers verloren. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ if $wsViews.current.params.theme }} {{ $wsCookie.setCookie("wsThemeColor", $wsViews.current.params.theme, 31536000) }} {{ /if }} ``` **Schritt 3: Bei jedem Seitenaufruf lesen und passendes Stylesheet laden** Das Cookie speichert lediglich die Auswahl. Die sichtbare Änderung entsteht erst durch das passende [Stylesheet](/glossar#stylesheet). Deshalb gibt es eine Weiche zwischen Dark- und Light-Variante. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ var $currentTheme = $wsCookie.getCookie("wsThemeColor") }} {{ if $currentTheme == "dark" }} {{ else }} {{ /if }} ``` **Ergebnis**\ Die gewählte Variante bleibt über alle Seitenaufrufe hinweg erhalten, bis der Nutzer sie wechselt. ### Onsite-Personalisierung: zielgruppenspezifische Inhalte Auslöser ist hier der Einstiegsweg, also ein Kampagnen-Link, über den der Besucher in den Shop kommt. Anders als die persönliche Begrüßung ist dies echte [Onsite-Personalisierung](/glossar#onsite-personalisierung): Sie spielen abhängig von einem Merkmal des Besuchers unterschiedliche Inhalte auf den Shop-Seiten aus. Das Szenario: Ein Tierbedarfs-Shop verschickt getrennte Newsletter an Katzen- und Hundehalter. Über den Link im Newsletter merkt sich der Shop die Zielgruppe und zeigt fortan passende Inhalte. **Schritt 1: Kampagnen-Link im Newsletter** Die Links im Newsletter tragen die Zielgruppe als Parameter: ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Zu unseren Katzen-Angeboten Zu unseren Hunde-Angeboten ``` **Schritt 2: Zielgruppe beim Seitenaufbau ins Cookie schreiben** Ruft der Besucher den Shop über den Link auf, liest das Template den Parameter aus und speichert die Zielgruppe. Die Gültigkeitsdauer von 30 Tagen (2592000 Sekunden) sorgt dafür, dass die Zuordnung auch bei späteren Besuchen erhalten bleibt. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ if $wsViews.current.params.kundengruppe }} {{ $wsCookie.setCookie("kundengruppe", $wsViews.current.params.kundengruppe, 2592000) }} {{ /if }} ``` **Schritt 3: Auf jeder Seite die passenden Inhalte anzeigen** Auf den Shop-Seiten ermitteln Sie die Zielgruppe und blenden die passenden Inhalte ein. Wichtig: Ein frisch gesetztes Cookie ist erst beim **nächsten** Seitenaufruf lesbar (siehe [Zeitpunkt der Ausführung](#grundkonzept)). Beim ersten Aufruf über den Kampagnen-Link greifen Sie deshalb auf den Parameter zurück und erst danach auf das Cookie. So sieht der Besucher schon beim Einstieg die richtigen Inhalte. Ist weder Parameter noch Cookie vorhanden, zeigen Sie einen neutralen Standardinhalt. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{ var $gruppe = $wsViews.current.params.kundengruppe }} {{ if not $gruppe }} {{ $gruppe = $wsCookie.getCookie("kundengruppe") }} {{ /if }} {{ if $gruppe == "katze" }}

Unsere Bestseller für Katzen

{{# hier die Banner und Produkte für Katzenhalter #}} {{ else }} {{ if $gruppe == "hund" }}

Unsere Bestseller für Hunde

{{# hier die Banner und Produkte für Hundehalter #}} {{ else }}

Für Katzen- und Hundefreunde

{{# neutraler Standardinhalt, solange keine Zielgruppe bekannt ist #}} {{ /if }} {{ /if }} ``` **Ergebnis**\ Besucher aus dem Katzen-Newsletter sehen bei jedem Aufruf die Katzen-Inhalte, Besucher aus dem Hunde-Newsletter die Hunde-Inhalte. Alle anderen sehen den Standardinhalt. Hinweis: Der Cookie-Wert ist im Browser lesbar und kann vom Nutzer verändert werden. Verwenden Sie die Zielgruppe daher nur zur Anzeige von Inhalten, nicht für sicherheitsrelevante Entscheidungen wie Preise oder Zugriffsrechte. Da es sich nicht um ein technisch notwendiges Cookie handelt, prüfen Sie zuvor die Einwilligung des Nutzers. ### Extern gesetztes Cookie lesen Auslöser ist hier ein Cookie, das außerhalb des Shops gesetzt wurde, beispielsweise per eigenem JavaScript oder durch ein Tool eines Drittanbieters. Solche Cookies behalten ihren ursprünglichen Namen und werden nicht automatisch umbenannt. Um sie auszulesen, übergeben Sie `keepNameAsIs: true`. Andernfalls sucht der Shop nach dem umbenannten Namen und findet das Cookie nicht. Im Beispiel hat ein per JavaScript gesetztes [Flag](/glossar#flag) vermerkt, dass ein Info-Popup bereits gesehen wurde: ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {{# Das Cookie wurde per JavaScript gesetzt: document.cookie = "infoPopupSeen=true" Im Template lesen wir es mit keepNameAsIs unverändert aus. #}} {{ var $popupSeen = $wsCookie.getCookie("infoPopupSeen", { keepNameAsIs: true }) }} {{ if $popupSeen != "true" }} {{# Cookie nicht vorhanden, Info-Popup anzeigen #}} {{ /if }} ``` **Ergebnis**\ Das Popup erscheint nur, solange das extern gesetzte Flag fehlt. *** ## Weiterführende Links * [\$wsConsent](/frontend/referenz/module/wsconsent) – Einwilligung des Nutzers prüfen, bevor Sie nicht-notwendige Cookies setzen.