Altersverifikation für PrestaShop – Sperrendes Modal für CBD, Alkohol, Vape & medizinisches Fachpersonal

Das Modul dfagegate fügt Ihrem PrestaShop-8- oder -9-Shop ein sperrendes Altersverifikations-Modal hinzu. Es deckt zwei unterschiedliche Märkte ab: den Standard-Modus für altersbeschränkte Produkte (CBD, Alkohol, Vape, Waffen, Feuerzeuge, 18+-Produkte) und den Medizin-Modus für Medizinprodukte, die medizinischem Fachpersonal vorbehalten sind (in Frankreich im Sinne von Artikel L5122-9 des Gesundheitsgesetzbuchs).

Installation

Die Installation folgt dem Standard-PrestaShop-Workflow. Nach dem Kauf bei DataFirefly erhalten Sie eine ZIP-Datei dfagegate-X.Y.Z.zip.

Über das Back-Office (empfohlen)

1. Melden Sie sich in Ihrem PrestaShop-Back-Office an
2. Gehen Sie zu Module → Modul-Katalog
3. Klicken Sie oben rechts auf Modul hochladen
4. Wählen Sie die ZIP-Datei dfagegate-X.Y.Z.zip
5. Nach dem Upload klicken Sie auf Installieren

Über FTP

1. Entpacken Sie das Archiv lokal
2. Laden Sie den Ordner dfagegate/ in das Verzeichnis modules/ Ihres PrestaShop hoch
3. Gehen Sie zu Module → Modul-Katalog
4. Suchen Sie nach „DataFirefly Age Gate“ und klicken Sie auf Installieren

Ersteinrichtung

Zugriff auf die Konfiguration: Module → Installierte Module → DataFirefly Age Gate → Konfigurieren.

Die Konfiguration ist in 6 Tabs organisiert:

• Allgemein — Aktivierung, Modus, Verifizierungstyp, Mindestalter
• Inhalt — mehrsprachige Texte (Titel, Nachricht, Buttons, rechtliche Hinweise)
• Aussehen — Logo, Farben, Hintergrund-Unschärfe
• Verhalten — Cookie, Weiterleitung, Bypass-Regeln
• Medizin-Modus — Berufe und Berufsausweisnummer (gilt nur im Medizin-Modus)
• Logs & DSGVO — Protokollierung und Diagnose

Tab Allgemein

• Modul aktivieren — Ja/Nein-Schalter, steuert die globale Anzeige des Modals
• Modus — Standard (CBD, Alkohol, Vape, Waffen) oder Medizinisch (Fachpersonal)
• Verifizierungstyp — Ja/Nein-Button, Geburtsdatum oder Berufserklärung
• Mindestalter — 18 standardmäßig, 21 für manche Märkte

Tab Inhalt

Jede in Ihrem PrestaShop aktivierte Sprache verfügt über einen eigenen Textblock. Standardwerte sind in FR, EN, ES und DE vorbefüllt. Für jede Sprache können Sie konfigurieren:

• Titel — groß oben im Modal angezeigt (Standard: „Altersverifikation“)
• Nachricht — Haupterklärungstext, Zeilenumbrüche bleiben erhalten
• Bestätigen-Button — Beschriftung des positiven Buttons (Standard: „Ich bin 18 oder älter“)
• Ablehnen-Button — Beschriftung des negativen Buttons
• Rechtlicher Hinweis — Text am Fuß des Modals
• Ablehnungsnachricht — Bildschirm bei Ablehnung, vor der Weiterleitung

Tab Aussehen

• Logo — PNG, JPG, SVG oder WEBP, max. 2 MB, oben im Modal angezeigt
• Hintergrundfarbe — Farbe der Hauptkarte (weiß standardmäßig)
• Primärfarbe — Titel und Haupt-Button (schwarz #111111 standardmäßig)
• Textfarbe — Nachrichtentext
• Overlay-Farbe — Schleier hinter dem Modal, akzeptiert CSS-Formate rgba() und Hex (Standard: rgba(15,15,20,0.85))
• Hintergrund-Unschärfe — moderner Effekt, funktioniert in allen aktuellen Browsern

Tab Verhalten

• Cookie-Dauer — in Tagen (90 standardmäßig). 0 für ein Session-Cookie (gelöscht beim Schließen des Browsers)
• Weiterleitungs-URL bei Ablehnung — leer lassen, um nur die Ablehnungsnachricht zu zeigen, oder eine externe URL angeben
• Bypass-IPs — Liste von IPs (eine pro Zeile), für die das Modal nie erscheint. Ideal für Sie und Ihr Team während Tests
• Bypass-URLs — ausgeschlossene Teilpfade. Vorbefüllt mit /legal, /contact und anderen rechtlichen Seiten
• Bypass für eingeloggte Kunden — wenn aktiviert, sehen bereits authentifizierte Kunden das Modal nie

Tab Medizin-Modus

Dieser Tab gilt nur, wenn der Modus auf Medizinisch und der Verifizierungstyp auf Berufserklärung steht.

• Berufsliste — einer pro Zeile. Standard: Arzt, Apotheker, Krankenpfleger/in, Physiotherapeut, Zahnarzt, Tierarzt, Sonstiges medizinisches Fachpersonal. Vollständig anpassbar
• Berufsausweisnummer verpflichtend — wenn aktiviert, erscheint ein Feld im Modal. Regex-Validierung, die 9 bis 11 Ziffern akzeptiert. Die Nummer wird nicht gespeichert, sie wird nur serverseitig validiert

Tab Logs & DSGVO

• Ablehnungen protokollieren — speichert jede Ablehnung in der Tabelle ps_dfagegate_log mit SHA-256-gehashter IP (nie im Klartext), Datum, Grund

Dieser Tab zeigt auch eine DSGVO-Zusammenfassung:

• Gesetztes Cookie — dfagegate_ok
• Kategorie — unbedingt erforderlich (rechtliche Zugangskonformität)
• Daten — Wert „1″, konfigurierbare Dauer, SameSite=Lax, Secure bei HTTPS

Konfiguration nach Markt

CBD-Shop für Endverbraucher

• Modus: Standard
• Verifizierungstyp: Ja/Nein-Button
• Mindestalter: 18
• Cookie-Dauer: 90 Tage
• Weiterleitungs-URL: leer (nur Ablehnungsnachricht)

Premium-Spirituosen / Alkohol-Shop

• Modus: Standard
• Verifizierungstyp: Geburtsdatum (strengere Kontrolle)
• Mindestalter: 18 (oder 21 für US-Märkte)
• Weiterleitungs-URL: beliebige offizielle Informationsseite

Vape-Shop / Nikotin-E-Liquids

• Modus: Standard
• Verifizierungstyp: Geburtsdatum (dringend empfohlen für Nikotin)
• Mindestalter: 18
• Ablehnungen protokollieren: Ja (nützlich bei einer behördlichen Prüfung)

Waffengeschäft

• Modus: Standard
• Verifizierungstyp: Geburtsdatum (verpflichtend)
• Mindestalter: 18
• Bypass-URLs: /vorschriften, /jagdschein hinzufügen
• Ablehnungen protokollieren: Ja

Medizintechnik-Shop (professionelle Geräte)

• Modus: Medizinisch
• Verifizierungstyp: Berufserklärung
• Berufsliste: Arzt, Apotheker, Physiotherapeut, Osteopath (an Ihren Katalog anpassen)
• Berufsausweisnummer verpflichtend: Ja
• Bypass für eingeloggte Kunden: Ja (wenn Sie den Beruf bereits bei der Registrierung prüfen)

Wie die Geburtsdatum-Verifizierung funktioniert

Im Gegensatz zu einem einfachen Button erfolgt die Berechnung serverseitig, nicht im Browser:

1. Der Besucher gibt Tag, Monat und Jahr im Modal ein
2. JavaScript sendet diese Werte an den AJAX-Controller DfagegateAjaxModuleFrontController
3. PHP validiert das Datum mit checkdate() und berechnet das Alter über DateTimeImmutable::diff()
4. Liegt das Alter unter dem konfigurierten Schwellenwert, gibt der Server eine JSON-Antwort mit success=false, denied=true und der Fehlermeldung zurück
5. Das Modal zeigt die Ablehnungsnachricht und leitet nach 2 Sekunden weiter
6. Erreicht das Alter den Schwellenwert, wird das Cookie dfagegate_ok gesetzt und das Modal schließt sich

Beachten Sie: Das Geburtsdatum wird nie gespeichert — es wird für eine einzige Berechnung verwendet und dann vergessen. Nur die binäre Validierung (akzeptiert / abgelehnt) wird über das Cookie festgehalten.

Wie der Medizin-Modus funktioniert

1. Das Modal zeigt ein Dropdown mit Berufen (konfigurierbar) und optional ein Feld für die Berufsausweisnummer
2. Eine verpflichtende Checkbox für die eidesstattliche Erklärung ist vorhanden
3. Der AJAX-Controller validiert, dass ein Beruf ausgewählt wurde
4. Ist die Nummer verpflichtend, validiert der Server das Format über einen regulären Ausdruck, der 9 bis 11 aufeinanderfolgende Ziffern akzeptiert
5. Keine Speicherung: Weder Beruf noch Nummer werden in der Datenbank aufbewahrt — das Cookie dfagegate_ok materialisiert nur den erfolgreichen Durchgang

Multishop

Das Modul ist 100% Multishop-kompatibel. Alle Einstellungen (Modus, Verifizierungstyp, mehrsprachige Texte, Farben, Bypass-Regeln) werden pro Shop-Kontext über id_shop_group und id_shop gespeichert. Das bedeutet, ein einziges PrestaShop kann beherbergen:

• Einen CBD-FR-Shop im Standard-Modus ab 18 mit französischen Texten
• Einen Vape-UK-Shop im Standard-Modus ab 18 mit englischen Texten
• Einen Medizintechnik-DE-Shop im Medizin-Modus mit verpflichtender Berufsausweisnummer und deutschen Texten

So konfigurieren Sie einen bestimmten Sub-Shop:

1. Wählen Sie im Kontext-Selektor oben im Back-Office den Ziel-Sub-Shop
2. Öffnen Sie die Modulkonfiguration
3. Ändern Sie die Werte — sie werden nur für diesen Shop gespeichert

Die Hooks werden bei der Installation auf allen Shops registriert über Shop::getCompleteListOfShopsID(), was die klassische Falle vermeidet, dass ein Modul nur im aktuellen Shop läuft.

Kompatibilität mit benutzerdefinierten Themes

Das Modul nutzt den Standard-Hook displayBeforeBodyClosingTag, um das Modal kurz vor dem schließenden Body-Tag zu injizieren. Dieser Hook sollte auf PrestaShop 1.7.5+ universell sein.

Leider rufen manche benutzerdefinierten Themes diesen Hook nicht auf. Für diesen Fall liefert dfagegate einen JavaScript-Injektions-Fallback mit:

1. PHP rendert das vollständige Modal-HTML vor und übergibt es via Media::addJsDef an JS
2. Beim DOMContentLoaded prüft das Skript, ob das Element mit der ID dfagegate-modal im DOM existiert
3. Falls ja, alles gut — der Hook hat funktioniert
4. Falls nicht, injiziert das Skript das Modal selbst via insertAdjacentHTML('beforeend', ...)
5. Eine console.info-Nachricht bestätigt die Aktivierung des Fallbacks

Diagnose und Debugging

Nach der Aktivierung fügt dfagegate einen HTML-Kommentar im Head-Tag jeder Frontend-Seite hinzu, in der Form „dfagegate v1.0.3 enabled=1 should_display=1″.

Dieser Kommentar ist Ihr erster Diagnosepunkt. Sehen Sie sich den Quellcode einer Seite an (Strg+U oder Cmd+U) und suchen Sie nach „dfagegate“.

Kommentar	Interpretation
Gar kein Kommentar	Der Hook displayHeader ist nicht registriert — prüfen Sie, ob das Modul installiert und aktiv ist
enabled=0	Der Schalter „Modul aktivieren“ steht auf Nein im Tab Allgemein
enabled=1 should_display=0	Ein Bypass ist aktiv: Ihre IP steht auf der Whitelist, die aktuelle URL entspricht einem ausgeschlossenen Pfad, oder Sie sind ein eingeloggter Kunde mit aktiviertem Bypass
enabled=1 should_display=1	Serverseitig ist alles in Ordnung. Erscheint das Modal nicht, prüfen Sie die Browser-Konsole

Das Modal erscheint immer noch nicht?

1. Ist der Diagnose-Kommentar mit should_display=1 vorhanden? Falls nicht, korrigieren Sie die Konfiguration
2. Öffnen Sie den Shop im privaten Modus. Das Cookie dfagegate_ok könnte in einer früheren Sitzung gesetzt worden sein
3. Prüfen Sie Ihre IP gegen die Bypasses im Tab Verhalten
4. Öffnen Sie die Browser-Konsole (F12). Suchen Sie nach [dfagegate]-Nachrichten
5. Prüfen Sie die PrestaShop-Logs unter Erweiterte Einstellungen → Logs, filtern Sie nach „dfagegate“
6. Leeren Sie den PrestaShop-Cache nach jeder Konfigurationsänderung: Erweiterte Einstellungen → Leistung → Cache leeren

Cookie im Browser zurücksetzen

1. Öffnen Sie die DevTools (F12)
2. Tab Application (Chrome) oder Storage (Firefox)
3. Bereich Cookies → Ihre Domain
4. Löschen Sie die Zeile dfagegate_ok
5. Laden Sie die Seite neu

DSGVO-Konformität

Das Cookie dfagegate_ok

• Typ — unbedingt erforderlich zur Erfüllung einer rechtlichen Zugangspflicht
• Rechtsgrundlage — von der vorherigen Einwilligung ausgenommen (ähnliche Ausnahmen existieren im europäischen ePrivacy-Rahmen)
• Wert — binär (1 = bestätigt)
• Dauer — konfigurierbar (90 Tage standardmäßig), oder Session bei 0
• Attribute — SameSite=Lax, automatisches Secure bei HTTPS, Path=/

Die Ablehnungs-Logs

Wenn Sie Ablehnungen protokollieren aktivieren, wird jede Ablehnung in der Tabelle ps_dfagegate_log gespeichert mit:

• id_shop — betroffener Sub-Shop
• reason — Ablehnungsgrund (user_refused oder dob_under_age)
• age — deklariertes Alter, falls zutreffend
• profession — deklarierter Beruf, falls zutreffend
• ip_hash — SHA-256 der IP, nie die Klartext-IP
• date_add — Zeitstempel

Das SHA-256-Hashing macht die IP nicht umkehrbar und erlaubt zugleich die Deduplizierung von Versuchen (dieselbe IP erzeugt immer denselben Hash). Das ist der von Datenschutzbehörden empfohlene Kompromiss für Zugangsstatistiken.

Die Verifizierungsdaten

• Das Geburtsdatum wird via AJAX für die Berechnung übertragen, aber nie gespeichert
• Die Berufsausweisnummer wird serverseitig validiert und dann vergessen, nie gespeichert
• Nur die binäre Validierung wird über das Cookie festgehalten

Technische Struktur und Integration

Verwendete Hooks

• displayHeader — injiziert den Diagnose-Kommentar
• actionFrontControllerSetMedia — registriert CSS und JS, übergibt Konfiguration und vorgerendetes Modal-HTML an JS
• displayBeforeBodyClosingTag — rendert das Modal serverseitig (JS-Fallback, falls im Theme fehlend)

AJAX-Endpunkte

Der AJAX-Controller antwortet unter /module/dfagegate/ajax und akzeptiert zwei Aktionen:

• action=confirm — mit Parametern je nach Verifizierungstyp (nichts für Ja/Nein, Tag/Monat/Jahr für Geburtsdatum, Beruf/Nummer für medizinisch)
• action=refuse — protokolliert die Ablehnung und gibt die Weiterleitungs-URL zurück

Die Antworten sind JSON. Eine Bestätigung gibt success=true zurück. Eine Ablehnung wegen unzureichenden Alters gibt success=false, denied=true und die passende Fehlermeldung zurück. Ein Validierungsfehler gibt success=false mit der Meldung zurück. Eine Nutzer-Ablehnung gibt success=true und redirect_url mit der konfigurierten Weiterleitungs-URL zurück.

Datenbankschema

Eine einzige Tabelle wird erstellt: ps_dfagegate_log. Sie enthält die Spalten id_log (Auto-Increment-Primärschlüssel), id_shop, reason (varchar 64), age (nullable), profession (varchar 128 nullable), ip_hash (char 64 für den SHA-256) und date_add (datetime). Zwei Sekundärindizes optimieren Reporting-Abfragen: idx_shop_date auf (id_shop, date_add) und idx_reason auf reason.

Deinstallation

Deaktivieren ohne Entfernen

Module → Installierte Module → DataFirefly Age Gate → Deaktivieren. Konfiguration und Log-Tabelle bleiben erhalten. Sie können jederzeit ohne Neukonfiguration reaktivieren.

Vollständige Deinstallation

Module → Installierte Module → DataFirefly Age Gate → Deinstallieren. Diese Aktion:

• Löscht die Tabelle ps_dfagegate_log
• Entfernt alle Konfigurationseinträge (18 skalare Schlüssel + 6 mehrsprachige Schlüssel)
• Deregistriert die Hooks
• Entfernt das Modul aus dem System

Support und Updates

Jede Lizenz beinhaltet:

• 12 Monate Updates — PrestaShop-Kompatibilität, Korrekturen, Verbesserungen
• Technischer E-Mail-Support — Antwort innerhalb von 24 Arbeitsstunden, FR/EN
• 30-Tage-Rückerstattung, ohne Fragen
• Unverschlüsselter Quellcode — Sie können das Modul frei an Ihre spezifischen Bedürfnisse anpassen

Für technische Fragen oder Fehlermeldungen kontaktieren Sie uns über Ihr DataFirefly-Konto. Geben Sie Ihre PrestaShop-Version, PHP-Version, Modulversion (oben im Konfigurationsbildschirm sichtbar) und möglichst den Diagnose-Kommentar aus dem Head-Tag Ihres Shops an.