Cookie-Consent-Modul im Hyvä-Theme: DSGVO-konform und CSP-sicher

1. DSGVO und CSP: zwei Anforderungen, eine Lösung

Wer ein Cookie-Consent-Modul im Hyvä-Theme bauen soll, trifft auf zwei Anforderungen, die sich auf den ersten Blick widersprechen. Die DSGVO verlangt, dass Analyse- und Marketing-Skripte erst nach expliziter Einwilligung geladen werden dürfen, der Banner selbst muss also aktiv steuern, welcher Code überhaupt ausgeführt wird. Gleichzeitig blockiert Hyväs eigenes CSP-Modul, das auf Magento_Csp aufsetzt, standardmäßig jedes Inline-Skript ohne gültige Nonce und jeden Script-Tag von einer nicht freigegebenen Domain. Ein klassischer Cookie-Banner, wie er in unzähligen Tutorials für Luma-Themes beschrieben wird, injiziert nach Klick auf "Akzeptieren" per document.write oder dynamisch erzeugtem <script>-Tag den GTM-Container. Genau das verhindert die CSP in einem korrekt konfigurierten Hyvä-Shop.

Die Lösung liegt nicht darin, die CSP zu lockern oder unsafe-inline zu erlauben, denn damit würde man exakt die Schutzfunktion aushebeln, die Hyvä gegenüber klassischen Magento-Themes auszeichnet. Ein sauberes Hyvä Cookie-Consent-System arbeitet stattdessen mit den Bordmitteln des Frameworks: einem Alpine.js-Store für die reaktive Zustandsverwaltung, expliziten Einträgen in csp_whitelist.xml für erlaubte Drittanbieter-Domains und dem projektüblichen Aufruf von $hyvaCsp->registerInlineScript() nach jedem Inline-Block. Erst die Kombination dieser drei Mechanismen ergibt ein DSGVO-konformes Cookie-Consent-Modul, das weder die Sicherheit noch die Rechtskonformität des Shops kompromittiert.

2. Alpine.js Consent-Store aufbauen

Der zentrale Baustein für ein Cookie-Consent-Modul im Hyvä-Theme ist ein global registrierter Alpine-Store, nicht eine lokale x-data-Komponente pro Banner-Instanz. Der Grund: Der Consent-Zustand muss shopweit verfügbar sein, im Footer-Link zum Präferenz-Modal genauso wie im Banner selbst und in jeder Komponente, die einen bedingt geladenen Drittanbieter-Dienst einbindet. Alpine.store('consent', {...}) wird einmal zentral definiert und ist danach über $store.consent aus jedem Template heraus ansprechbar, ohne dass Zustand dupliziert oder über Custom Events synchronisiert werden muss.

Der Store persistiert seinen Zustand in localStorage, damit die Einwilligung über Seitenaufrufe hinweg erhalten bleibt, und spiegelt denselben Zustand zusätzlich in ein Cookie, damit PHP ihn serverseitig lesen kann, dazu mehr in Abschnitt sechs. Die init()-Methode des Stores lädt beim ersten Alpine-Tick den gespeicherten Zustand, fällt aber ohne vorhandenen Eintrag auf den DSGVO-konformen Default zurück: alles außer der essenziellen Kategorie ist zunächst verweigert. Diese Struktur macht das Hyvä Cookie-Consent-Modul reaktiv, jede Komponente mit x-show="$store.consent.granted('analytics')" reagiert sofort auf Änderungen, ohne Page-Reload.

// Alpine.js consent store, registered globally before Alpine.start()
// File: web/js/consent-store.js (loaded via requirejs-config.js, no inline script needed)
document.addEventListener('alpine:init', () => {
  Alpine.store('consent', {
    // Reactive state per category
    categories: {
      essential: true,      // always true, cannot be disabled
      functional: false,
      analytics: false,
      marketing: false,
    },
    interacted: false,

    init() {
      const saved = localStorage.getItem('mironsoft_consent');
      if (saved) {
        const parsed = JSON.parse(saved);
        this.categories = { ...this.categories, ...parsed.categories };
        this.interacted = true;
      }
    },

    granted(category) {
      return this.categories[category] === true;
    },

    acceptAll() {
      Object.keys(this.categories).forEach((key) => (this.categories[key] = true));
      this.persist();
    },

    rejectAll() {
      Object.keys(this.categories).forEach((key) => {
        if (key !== 'essential') this.categories[key] = false;
      });
      this.persist();
    },

    save(selection) {
      this.categories = { ...this.categories, ...selection };
      this.persist();
    },

    persist() {
      this.interacted = true;
      localStorage.setItem('mironsoft_consent', JSON.stringify({ categories: this.categories }));
      // Mirror to a first-party cookie so PHP can read consent server-side
      document.cookie = `mironsoft_consent=${encodeURIComponent(JSON.stringify(this.categories))}; path=/; max-age=31536000; SameSite=Lax`;
      // Dispatch a DOM event so Consent Mode v2 update signals can react
      window.dispatchEvent(new CustomEvent('consent:changed', { detail: this.categories }));
    },
  });
});

3. csp_whitelist.xml für Drittanbieter-Skripte

Selbst wenn der Alpine-Store sauber entscheidet, ob Google Tag Manager geladen werden darf, hilft das nichts, solange die CSP den Request auf googletagmanager.com blockiert. Magentos Magento_Csp-Modul arbeitet mit sogenannten Sender Policies pro Domain und Richtlinientyp, script-src, connect-src, frame-src, img-src. Ohne einen passenden Eintrag meldet die Browser-Konsole einen CSP-Verstoß und der Tag-Manager-Container lädt nicht, unabhängig davon, wie korrekt die Consent-Logik im Frontend implementiert ist. Für ein funktionierendes Cookie-Consent-Modul im Hyvä-Theme ist die Whitelist deshalb keine Nebensache, sondern eine harte Voraussetzung.

Die Whitelist wird als eigenständige etc/csp_whitelist.xml im Modul angelegt und definiert für jede Domain, unter welcher Policy sie erlaubt ist. Für Google Tag Manager und Consent Mode v2 braucht es typischerweise Einträge für script-src (googletagmanager.com), connect-src (region1.google-analytics.com, google-analytics.com) und img-src für Pixel-Tracking. Wichtig: Die Whitelist erlaubt der Domain lediglich, geladen zu werden, sie ersetzt nicht die Consent-Prüfung. Das eigentliche Gate, ob das Skript überhaupt in den DOM eingefügt wird, bleibt Aufgabe des Alpine-Stores und der bedingten Layout-Blöcke.

<!-- File: app/code/Mironsoft/CookieConsent/etc/csp_whitelist.xml -->
<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
    <policies>
        <policy id="script-src">
            <values>
                <value id="gtm" type="host">https://www.googletagmanager.com</value>
                <value id="gtm-cdn" type="host">https://*.googletagmanager.com</value>
            </values>
        </policy>
        <policy id="connect-src">
            <values>
                <value id="ga4-collect" type="host">https://*.google-analytics.com</value>
                <value id="ga4-region" type="host">https://region1.google-analytics.com</value>
            </values>
        </policy>
        <policy id="img-src">
            <values>
                <value id="gtm-pixel" type="host">https://www.googletagmanager.com</value>
                <value id="ga-pixel" type="host">https://*.google-analytics.com</value>
            </values>
        </policy>
        <policy id="frame-src">
            <values>
                <value id="gtm-preview" type="host">https://www.googletagmanager.com</value>
            </values>
        </policy>
    </policies>
</csp_whitelist>

4. registerInlineScript() richtig einsetzen

Auch nach einer korrekten Whitelist bleibt ein Problem: Der Banner selbst, das Consent-Mode-Default-Snippet und die Alpine-Initialisierung enthalten meist Inline-Skripte, und genau die blockiert Hyväs CSP-Modul standardmäßig, weil sie keine gültige Nonce tragen. Projektregel für jedes Hyvä-Theme bei Mironsoft ist deshalb: Nach jedem <script>-Inline-Block im phtml-Template folgt zwingend der Aufruf von $hyvaCsp->registerInlineScript(). Diese Methode berechnet einen Hash oder eine Nonce für genau diesen Skriptinhalt und registriert ihn bei der CSP-Middleware, sodass der Browser das Skript ausführt, obwohl es inline im HTML steht.

Für ein DSGVO-konformes Cookie-Consent-Modul betrifft das mehrere Stellen: das Default-Consent-Snippet für Google Consent Mode v2, das vor jedem anderen Skript im Head stehen muss, die Initialisierung des Alpine-Stores, falls sie nicht über eine externe Datei geladen wird, und gegebenenfalls ein kleines Bootstrap-Skript, das den Banner beim ersten Besuch anzeigt. Ohne den registerInlineScript()-Aufruf funktioniert der Code im Entwicklungsmodus oft trotzdem, weil CSP-Reports dort nur geloggt werden, in Produktion mit erzwungener CSP schlägt die Ausführung dann aber lautlos fehl, ein Klassiker unter den Hyvä-Debugging-Fallen.

<?php
/** @var \Hyva\Theme\Model\ViewModelRegistry $viewModels */
/** @var \Hyva\Theme\ViewModel\HyvaCsp $hyvaCsp */
$hyvaCsp = $viewModels->require(\Hyva\Theme\ViewModel\HyvaCsp::class);
?>
<!-- File: templates/consent/banner.phtml -->
<div
    x-data
    x-show="!$store.consent.interacted"
    x-cloak
    class="fixed inset-x-0 bottom-0 z-50 bg-slate-900 text-white p-6 shadow-2xl"
    role="dialog"
    aria-label="Cookie-Einwilligung"
>
    <p class="text-sm mb-4">
        Wir nutzen Cookies fuer essenzielle Funktionen sowie optional fuer
        Analyse und Marketing. Details im Praeferenz-Modal.
    </p>
    <div class="flex gap-3">
        <button type="button" x-on:click="$store.consent.acceptAll()" class="bg-orange-600 px-4 py-2 rounded-lg text-sm font-bold">
            Alle akzeptieren
        </button>
        <button type="button" x-on:click="$store.consent.rejectAll()" class="border border-white/40 px-4 py-2 rounded-lg text-sm">
            Nur essenziell
        </button>
        <button type="button" x-on:click="$store.open('preferences')" class="text-sm underline">
            Einstellungen
        </button>
    </div>
</div>

<script>
    // Bootstrap: show banner only if the user has not interacted yet
    window.addEventListener('alpine:init', () => {
        if (!localStorage.getItem('mironsoft_consent')) {
            document.dispatchEvent(new CustomEvent('consent:show-banner'));
        }
    });
</script>
<?php /* Mandatory after every inline script block in a Hyva theme */ ?>
<?= $hyvaCsp->registerInlineScript() ?>

5. Google Consent Mode v2 implementieren

Seit Google Consent Mode v2 für Werbekunden im europäischen Wirtschaftsraum verpflichtend ist, reicht es nicht mehr, GTM einfach erst nach Einwilligung zu laden. Google erwartet zusätzlich zwei Consent-Signale, ad_user_data und ad_personalization, die schon vor jeder Nutzerinteraktion auf "denied" gesetzt sein müssen, das sogenannte Default-Signal. Fehlt dieses Default-Signal, drosselt Google die Datenqualität in GA4 und Ads spürbar, selbst wenn der Nutzer später zustimmt. Ein vollständiges Cookie-Consent-Modul im Hyvä-Theme muss dieses Timing exakt einhalten: Default-Signal vor dem GTM-Container-Tag, Update-Signal erst nach expliziter Interaktion.

Technisch bedeutet das zwei getrennte gtag('consent', ...)-Aufrufe. Der Default-Call steht als eigener, über registerInlineScript() registrierter Block ganz oben im Head, noch vor dem eigentlichen GTM-Snippet, und setzt alle Werbe-relevanten Kategorien auf "denied". Sobald der Nutzer im Banner oder im Präferenz-Modal eine Auswahl trifft, feuert der Alpine-Store das Event consent:changed, ein Listener übersetzt die Kategorien in gtag('consent', 'update', {...}) und Google passt die Tag-Auslieferung in Echtzeit an, ohne Page-Reload. Diese Update-Signal-Logik ist der Teil, den viele Cookie-Plugins für klassische Themes schlicht nicht abbilden, weil sie vor Consent Mode v2 entwickelt wurden.

{
  "_comment_default": "Fires before GTM container, all ad signals denied by default",
  "default": {
    "ad_storage": "denied",
    "ad_user_data": "denied",
    "ad_personalization": "denied",
    "analytics_storage": "denied",
    "functionality_storage": "denied",
    "personalization_storage": "denied",
    "security_storage": "granted",
    "wait_for_update": 500
  },
  "_comment_update": "Fired from the consent:changed listener after user interaction",
  "update_on_accept_all": {
    "ad_storage": "granted",
    "ad_user_data": "granted",
    "ad_personalization": "granted",
    "analytics_storage": "granted",
    "functionality_storage": "granted",
    "personalization_storage": "granted"
  },
  "update_on_reject_all": {
    "ad_storage": "denied",
    "ad_user_data": "denied",
    "ad_personalization": "denied",
    "analytics_storage": "denied",
    "functionality_storage": "denied",
    "personalization_storage": "denied"
  }
}

6. Server-seitiges Auslesen des Consent-Status

Alpine-Store und localStorage lösen das clientseitige Gating, aber nicht jede Entscheidung darf erst im Browser fallen. Wenn ein Layout-XML-Block einen ganzen GTM-Container inklusive Noscript-Fallback komplett unterdrücken soll, oder wenn ein Server-Side-Rendering-Zweig unterschiedliche Inhalte je nach Consent-Status ausliefern muss, braucht PHP Zugriff auf den aktuellen Zustand, bevor der erste Byte HTML das Backend verlässt. Deshalb spiegelt der Alpine-Store seinen Zustand in ein first-party Cookie, und ein ViewModel liest dieses Cookie serverseitig aus.

Ein solches ViewModel implementiert ArgumentInterface und nutzt in PHP 8.4 Constructor Property Promotion für die CookieManagerInterface-Injektion. Die Methode hasConsent(string $category) dekodiert das JSON-Cookie und liefert einen sauberen Boolean zurück, den phtml-Templates und Layout-Konditionen gleichermaßen nutzen können. Damit wird das Cookie-Consent-Modul im Hyvä-Theme nicht nur clientseitig reaktiv, sondern auch serverseitig konsistent, ein wichtiger Unterschied gegenüber reinen JavaScript-Lösungen, die bei deaktiviertem JavaScript oder beim ersten Server-Response komplett wirkungslos bleiben.

<?php

declare(strict_types=1);

namespace Mironsoft\CookieConsent\ViewModel;

use Hyva\Theme\Model\ViewModelRegistry;
use Magento\Framework\Stdlib\CookieManagerInterface;
use Magento\Framework\View\Element\Block\ArgumentInterface;

/**
 * Reads the consent cookie mirrored by the Alpine.js consent store
 * to allow server-side gating of layout blocks and templates.
 */
final class ConsentStatus implements ArgumentInterface
{
    private const COOKIE_NAME = 'mironsoft_consent';

    /**
     * @param CookieManagerInterface $cookieManager Reads first-party cookies from the request
     */
    public function __construct(
        private readonly CookieManagerInterface $cookieManager
    ) {
    }

    /**
     * Checks whether the visitor has granted consent for a given category.
     *
     * @param string $category One of essential, functional, analytics, marketing
     * @return bool True if the category is granted, false for missing or denied consent
     */
    public function hasConsent(string $category): bool
    {
        if ($category === 'essential') {
            return true;
        }

        $raw = $this->cookieManager->getCookie(self::COOKIE_NAME);
        if ($raw === null) {
            return false;
        }

        /** @var array<string, bool>|null $decoded */
        $decoded = json_decode((string) $raw, true);
        if (!is_array($decoded)) {
            return false;
        }

        return $decoded[$category] ?? false;
    }
}

7. Kategorien: essenziell, funktional, analytisch, Marketing

Ein rechtssicheres DSGVO-konformes Cookie-Consent-Modul unterscheidet mindestens vier Kategorien, weil das TTDSG und die DSGVO unterschiedliche Rechtsgrundlagen für unterschiedliche Zwecke verlangen. Essenzielle Cookies, Session-ID, CSRF-Token, Warenkorb-Persistenz, sind technisch notwendig und dürfen ohne Einwilligung gesetzt werden, ihr Toggle im Banner ist deshalb im Alpine-Store dauerhaft auf true fixiert und nicht abwählbar. Funktionale Cookies decken Komfortfunktionen ab, etwa eine gemerkte Wunschliste über mehrere Besuche hinweg, ohne die der Shop trotzdem grundsätzlich funktioniert.

Analytische Cookies, GA4, Hotjar, Microsoft Clarity, erfordern explizite Einwilligung, weil sie Nutzerverhalten personenbeziehbar auswerten. Marketing-Cookies, Google Ads Remarketing, Meta Pixel, LinkedIn Insight Tag, haben die strengsten Anforderungen, da sie oft mit Drittanbietern geteilte Identifikatoren erzeugen. Jede dieser vier Kategorien bekommt im Alpine-Store ein eigenes Boolean-Flag und im Layout-XML einen eigenen bedingten Block, sodass ein Hyvä Cookie-Consent-System granular steuern kann, welches Skript unter welcher Bedingung überhaupt in den DOM gelangt, statt pauschal "alles oder nichts" zu entscheiden.

8. Präferenz-Modal mit Alpine x-transition

Die DSGVO verlangt nicht nur eine initiale Einwilligung, sondern auch die jederzeitige Möglichkeit, diese zu widerrufen oder anzupassen, ohne dass der Nutzer dafür den Browser-Cache leeren oder den Support kontaktieren muss. Ein reiner Erstbesuch-Banner ohne dauerhaften Zugang zu den Einstellungen ist deshalb kein vollständiges Cookie-Consent-Modul im Hyvä-Theme, auch wenn er technisch CSP-konform ist. Ein Footer-Link "Cookie-Einstellungen" muss das gleiche Präferenz-Modal öffnen, das auch beim ersten Besuch über den Banner-Link "Einstellungen" erreichbar ist.

Das Modal selbst nutzt Alpines x-show in Kombination mit x-transition für ein sanftes Ein- und Ausblenden, gebunden an ein zusätzliches Store-Flag wie $store.consent.preferencesOpen. Für jede der vier Kategorien rendert das Modal einen eigenen Toggle-Switch, der direkt an $store.consent.categories.analytics et cetera bindet, essenziell bleibt dabei deaktiviert und mit einem erklärenden Hinweistext versehen. Ein "Speichern"-Button ruft $store.consent.save(selection) auf, was sowohl die Persistierung als auch das Consent-Mode-Update-Event auslöst, sodass Änderungen sofort wirksam werden, ohne dass die Seite neu geladen werden muss.

9. Consent-Patterns im Vergleich

Die Unterschiede zwischen einer naiven, aus Luma- oder WordPress-Tutorials übernommenen Cookie-Banner-Implementierung und einem korrekt gebauten Cookie-Consent-Modul im Hyvä-Theme zeigen sich am deutlichsten im direkten Vergleich der einzelnen Bausteine.

In der Summe zeigt der Vergleich, dass keine einzelne Maßnahme allein genügt. Erst die Kombination aus CSP-konformer Skript-Registrierung, expliziter Domain-Whitelist, reaktivem Consent-Store, korrekt getimten Google-Signalen und dauerhafter Änderbarkeit ergibt ein DSGVO-konformes Cookie-Consent-Modul, das sowohl vor Abmahnungen als auch vor stillen CSP-Blockaden schützt.

10. Zusammenfassung

Ein Cookie-Consent-Modul im Hyvä-Theme ist kein reines Frontend-Feature, sondern ein Zusammenspiel aus CSP-Konfiguration, reaktiver State-Verwaltung und serverseitiger Lesbarkeit. Der Alpine.js-Store übernimmt die reaktive UI-Logik und die Persistierung in localStorage, csp_whitelist.xml gibt genau die Domains frei, die nach Einwilligung tatsächlich geladen werden dürfen, und registerInlineScript() sorgt dafür, dass jeder notwendige Inline-Block, vom Consent-Mode-Default bis zur Banner-Initialisierung, unter der strikten CSP überhaupt ausgeführt wird.

Wer diese Bausteine sauber zusammensetzt, erhält ein DSGVO-konformes Cookie-Consent-Modul, das Google Consent Mode v2 korrekt bedient, Nutzern jederzeit eine Änderung ihrer Präferenzen erlaubt und dabei keine einzige CSP-Regel verletzt. Genau diese Kombination unterscheidet ein durchdachtes Hyvä-natives System von generischen Cookie-Plugins, die für klassische, CSP-freie Themes entwickelt wurden und in einem strikt abgesicherten Hyvä-Shop schlicht nicht funktionieren.

11. FAQ: Cookie-Consent-Modul im Hyvä-Theme