Zum Hauptinhalt springen
Mithilfe des $wsCookie-Moduls lesen, setzen, aktualisieren und löschen Sie Browser-Cookies 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 des Nutzers prüfen, ist in $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() 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 oder 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 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_<shopId>_cookie<name>. 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 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 
{{= $wsCookie | json }}
JSON-Ausgabe 
{
  "deleteCookie": "ƒ()",
  "getCookie": "ƒ()",
  "setCookie": "ƒ()",
  "updateCookie": "ƒ()"
}
Anmerkung: "ƒ()" kennzeichnet eine Funktion. Methoden in der Übersicht
MethodeRückgabe-TypBeschreibung
getCookie()stringLiest den Wert eines Cookies anhand seines Namens.
setCookie()–Setzt ein neues Cookie.
updateCookie()stringAktualisiert 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.

​
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
NameTypPflichtStandardBeschreibung
namestringja–Kurzer Name des Cookies, ohne Präfix.
optionsmapnein–keepNameAsIs (bool) – verwendet den Namen unverändert, ohne das automatische Schema.
Nötig für extern gesetzte Cookies (siehe Grundkonzept).
Beispiel, das eine gespeicherte Darstellungsvariante liest. 
{{ var $currentTheme = $wsCookie.getCookie("wsThemeColor") }}

​
$wsCookie.setCookie()

Setzt ein neues Cookie. Signatur
$wsCookie.setCookie(name, value, [age]) Rückgabe
– (kein Rückgabewert) Parameter
NameTypPflichtStandardBeschreibung
namestringja–Kurzer Name des Cookies, ohne Präfix.
valuestring, int, float, list, map, boolja–Wert des Cookies. Komplexe Werte (list, map) werden intern automatisch als JSON gespeichert.
ageintneinSessionGültigkeitsdauer in Sekunden. Ohne Angabe wird ein Session-Cookie gesetzt, das am Ende der Browser-Sitzung verfällt. Maximal 10 Jahre. Beispiel: 31536000 = 365 Tage.
Beispiel, das eine Darstellungsvariante setzt. 
{{ $wsCookie.setCookie("wsThemeColor", "dark") }}
Beispiel, das ein Cookie mit einer Gültigkeitsdauer von 365 Tagen setzt. 
{{ $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
NameTypPflichtStandardBeschreibung
namestringja–Kurzer Name des Cookies, ohne Präfix.
valuestring, int, float, list, map, boolja–Neuer Wert des Cookies.
Beispiel, das eine Darstellungsvariante aktualisiert. 
{{ $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
NameTypPflichtStandardBeschreibung
namestringja–Kurzer Name des Cookies, ohne Präfix.
Beispiel, das ein gesetztes Cookie löscht. 
{{ $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. 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. 
{{ 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. 
{{ 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() 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). 
<a href="?theme=dark">Darkmode aktivieren</a>
<a href="?theme=light">Darkmode ausschalten</a>
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. 
{{ 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. Deshalb gibt es eine Weiche zwischen Dark- und Light-Variante. 
{{ 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 }}
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: 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: 
<a href="https://ihr-shop.de/?kundengruppe=katze">Zu unseren Katzen-Angeboten</a>
<a href="https://ihr-shop.de/?kundengruppe=hund">Zu unseren Hunde-Angeboten</a>
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. 
{{ 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). 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. 
{{ var $gruppe = $wsViews.current.params.kundengruppe }}
{{ if not $gruppe }}
  {{ $gruppe = $wsCookie.getCookie("kundengruppe") }}
{{ /if }}

{{ if $gruppe == "katze" }}
  <h2>Unsere Bestseller für Katzen</h2>
  {{# hier die Banner und Produkte für Katzenhalter #}}
{{ else }}
  {{ if $gruppe == "hund" }}
    <h2>Unsere Bestseller für Hunde</h2>
    {{# hier die Banner und Produkte für Hundehalter #}}
  {{ else }}
    <h2>Für Katzen- und Hundefreunde</h2>
    {{# 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.
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 vermerkt, dass ein Info-Popup bereits gesehen wurde: 
{{# 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.
  • $wsConsent – Einwilligung des Nutzers prüfen, bevor Sie nicht-notwendige Cookies setzen.