dffreegift — Geschenk ab Warenkorbschwelle — Vollständige Anleitung

Vollständige Anleitung für das dffreegift-Modul für PrestaShop 8 und 9: Installation, Konfiguration, interne Mechanik (native CartRule), Anpassung, Fehlerbehebung und Deinstallation. Jeder Schritt wird durch konzeptionelle Erklärungen und die genauen Produktionsparameter begleitet.

Überblick

dffreegift fügt automatisch einen Geschenkartikel zum Warenkorb hinzu, sobald ein konfigurierter Schwellenwert erreicht wird, und entfernt ihn, wenn der Warenkorb wieder darunter fällt. Die Mechanik stützt sich vollständig auf das native CartRule-System von PrestaShop (Feld gift_product): Das Modul manipuliert Produktpreise nie direkt, erstellt keine temporären SpecificPrice-Einträge und injiziert nichts in die Preisberechnungs-Hooks. Ergebnis: volle Kompatibilität mit Ihren anderen Aktionen, Gutscheincodes, Steuern und Mehrwährungsfähigkeit.

Das Modul zeigt außerdem einen Fortschrittsblock auf der Warenkorbseite mit der Nachricht «Fügen Sie X € hinzu, um Ihr Geschenk zu erhalten», einem farbigen Balken, der sich füllt, während der Schwellenwert näher rückt, und einer Animation beim Überschreiten.

Voraussetzungen

• PrestaShop 8.0 bis 9.x (getestet auf 8.0, 8.1, 8.2, 9.0)
• PHP 8.1 Mindestversion (8.2 und 8.3 unterstützt)
• Ein aktiver Artikel in Ihrem Katalog, der als Geschenk dient (einfacher Artikel oder mit Varianten)
• Administratorzugang zum PrestaShop-Backoffice

Installation

1. Im Backoffice zu Module → Module-Manager → Ein Modul hochladen gehen.
2. Die Datei dffreegift-1.0.0.zip hochladen.
3. Auf Installieren und dann auf Konfigurieren klicken.

Bei der Installation führt das Modul folgende Operationen im Hintergrund aus:

• Registrierung von 5 Hooks: actionCartSave, actionObjectCartRuleDeleteBefore, displayShoppingCart, displayCartExtraProductActions, displayHeader.
• Schreiben der Standardkonfigurationswerte (Schwelle 50 €, Bruttoberechnung, ohne Versand, Lagerprüfung aktiviert).
• Erstellung einer «Phantom»-CartRule mit einem eindeutigen Code wie DFFREEGIFT_A7B3F2D9, sichtbar unter Katalog → Rabatte → Warenkorbregeln.

Konfiguration

Der Konfigurationsbildschirm befindet sich unter Module → DataFirefly Free Gift → Konfigurieren. Alle Parameter sind in einem einzigen Formular gruppiert.

Modul aktivieren

Der Schalter Modul aktivieren fungiert als Hauptschalter. Auf Nein gestellt bleibt das Modul installiert, tut aber nichts: kein Auto-Hinzufügen, kein Frontend-Block, keine Schwellwertberechnung. Nützlich, um das Angebot vorübergehend zu deaktivieren (Ende einer Saisonaktion beispielsweise), ohne die Konfiguration zu verlieren.

Geschenkartikel und Variante

Zwei Felder, in dieser Reihenfolge auszufüllen:

1. ID des Geschenkartikels: Die PrestaShop-ID des zu verschenkenden Artikels eingeben. Die ID ist unter Katalog → Produkte sichtbar (Spalte ID). Nach dem ersten Speichern wird der Produktname als Hinweis unter dem Feld zur Bestätigung angezeigt.
2. Variante: Dropdown mit den verfügbaren Varianten des Produkts. Wird automatisch nachdem Sie die Produkt-ID gespeichert haben aufgefüllt. Wählen Sie eine spezifische Variante (z. B. «Größe M, Farbe schwarz») oder lassen Sie — Ohne Variante — für einen einfachen Artikel.

Auslöseschwelle

Das Feld Auslöseschwelle legt den Warenkorbbetrag fest, ab dem das Geschenk hinzugefügt wird. Zwei zugehörige Parameter definieren die Berechnungsbasis:

• Bruttoberechnung: Wenn aktiviert, enthält die Summe alle auf den Warenkorb angewandten Steuern. Wenn deaktiviert, wird der Schwellenwert mit dem Nettobetrag verglichen. Die meisten B2C-Shops rechnen brutto; B2B-Shops denken oft netto.
• Versandkosten einschließen: Wenn aktiviert, werden geschätzte Versandkosten vor dem Vergleich zur Summe hinzugefügt. In der Praxis selten aktiviert, da Versandkosten nicht immer berechnet sind, wenn der Kunde seinen Warenkorb ansieht (noch kein Versanddienstleister gewählt = 0 €).

Konkret entspricht die ausgewertete Summe einem nativen PrestaShop-Aufruf:

Cart::getOrderTotal(
    $with_taxes = (bool) CFG_TAX_INCL,
    $type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);

Das garantiert, dass der für den Vergleich verwendete Wert strikt identisch mit dem in der Warenkorbübersicht angezeigten Wert ist.

Lagerprüfung

Der Schalter Lagerbestand des Geschenks prüfen (standardmäßig aktiviert) setzt das Auto-Hinzufügen aus, wenn der Geschenkartikel nicht verfügbar ist. Die Prüfung respektiert die global in PrestaShop konfigurierte Out-of-Stock-Strategie:

• Ist der Artikel als «Bestellung bei Nichtverfügbarkeit erlauben» markiert, bleibt das Auto-Hinzufügen auch bei Bestand 0 aktiv.
• Verweigert der Artikel Bestellungen bei Nichtverfügbarkeit, wird das Auto-Hinzufügen ausgesetzt, sobald der Bestand 0 erreicht.

Einschränkung nach Kundengruppen

Das Raster Berechtigte Kundengruppen listet alle Gruppen des Shops mit einer Checkbox pro Gruppe. Zwei Verhalten:

• Keine Checkbox angekreuzt: Alle Kunden sind berechtigt, einschließlich nicht identifizierter Besucher (sofern die Standardgruppe PS_UNIDENTIFIED_GROUP nicht ausgeschlossen ist, das Standardverhalten).
• Eine oder mehrere Checkboxen angekreuzt: Nur Kunden, die Mitglied mindestens einer angekreuzten Gruppe sind, sehen den Fortschrittsblock und profitieren vom Auto-Hinzufügen.

Typische Anwendungsfälle:

• Geschenk der Gruppe «Gewerbekunden» für eine B2B-Klientel vorbehalten.
• Geschenk der Gruppe «VIP» für ein Treueprogramm vorbehalten.
• Geschenk allen angeboten außer Wiederverkäufern (alle Gruppen außer der Wiederverkäufer-Gruppe ankreuzen).

Anzeigeoptionen

Zwei unabhängige Schalter steuern das Erscheinungsbild des Frontend-Blocks:

• Fortschrittsmeldung anzeigen: Aktiviert oder deaktiviert den Block auf der Warenkorbseite vollständig. Auf Nein gestellt funktioniert das Auto-Hinzufügen weiterhin, aber auf Kundenseite erscheint keine Meldung (nützlich, wenn Sie die Anzeige über Ihr eigenes Theme steuern wollen).
• Fortschrittsbalken anzeigen: Aktiviert oder deaktiviert den farbigen Balken unter der Meldung. Die Textnachricht bleibt sichtbar.

Wie es technisch funktioniert

Die Phantom-CartRule

Anstatt Produktpreise zu manipulieren, nutzt dffreegift den nativen Geschenk-Mechanismus von PrestaShop über CartRule. Bei der Installation wird eine Regel mit folgenden Eigenschaften angelegt:

• code = DFFREEGIFT_A7B3F2D9 (Suffix bei der Installation zufällig erzeugt)
• gift_product = 0 (bei jedem Speichern der Konfiguration aktualisiert)
• gift_product_attribute = 0 (bei jedem Speichern der Konfiguration aktualisiert)
• quantity = 999.999 und quantity_per_user = 999.999 (praktisch unbegrenzt)
• date_from = jetzt, date_to = +50 Jahre
• active = 1, kein Code, kein Rabatt, keine Produkt- oder Kategorie-Beschränkung

Wenn der Schwellenwert erreicht ist, hängt das Modul diese Regel per Cart::addCartRule($id) an den Warenkorb an. PrestaShop kümmert sich um den Rest:

• Einfügen einer Warenkorbzeile mit gift = 1 und price = 0.
• Anzeige in der Warenkorbübersicht mit einem «Geschenk»-Badge.
• Berücksichtigung bei der Umwandlung in eine Bestellung.
• Snapshot im Bestellverlauf (das Geschenk bleibt sichtbar, auch wenn Sie den Geschenkartikel später ändern).

Wenn der Warenkorb unter den Schwellenwert fällt, hängt das Modul die Regel per Cart::removeCartRule($id) ab. Die Geschenkzeile wird im selben Request entfernt.

Verwendete Hooks

• actionCartSave: Haupt-Hook. Wird bei jedem Warenkorb-Speichern aufgerufen (Hinzufügen, Ändern, Entfernen, Kundenlogin mit Warenkorb-Merge). Das Modul berechnet die Summe und entscheidet, die Regel anzuhängen oder abzuhängen. Ein statischer self::$syncing-Flag verhindert die Rekursion, wenn das Anhängen der Regel selbst ein Speichern auslöst.
• actionObjectCartRuleDeleteBefore: Selbstheilung. Löscht ein Admin die Phantom-Regel manuell aus Katalog → Rabatte, erkennt dieser Hook die Löschung und setzt die ID in der Konfiguration zurück. Die nächste Synchronisation legt eine saubere Regel neu an.
• displayHeader: Registriert das Frontend-CSS und -JS (views/css/dffreegift.css und views/js/dffreegift.js).
• displayShoppingCart: Rendert den Fortschrittsblock auf der Warenkorbseite.
• displayCartExtraProductActions: Für zukünftige Erweiterungen reserviert (Badge auf der Geschenkzeile).

Berechnung des Schwellenwerts

Bei jedem Aufruf von syncCartGift() prüft das Modul in dieser Reihenfolge:

1. Ist das Modul aktiviert? (sonst wird abgebrochen)
2. Ist der Kunde gemäß den konfigurierten Gruppen berechtigt? (sonst abhängen, falls angehängt)
3. Ist der Geschenkartikel gültig (existiert, aktiv, auf Lager falls Prüfung aktiv)? (sonst abhängen)
4. Berechnung der Summe je nach Brutto/Netto und Versandeinschluss.
5. Vergleich mit dem Schwellenwert mit Rundungstoleranz von 0,001 €.
6. Regel anhängen, wenn Schwelle erreicht und noch nicht angehängt. Abhängen, wenn unter der Schwelle und aktuell angehängt.

Frontend-Fortschrittsblock

Der Block wird automatisch auf der Warenkorbseite angezeigt, zwischen Produktübersicht und Gesamtsumme. Zwei visuelle Zustände:

• Ausstehend (Schwelle nicht erreicht): heller grauer Hintergrund, Nachricht «Fügen Sie X,XX € hinzu, um Ihr Geschenk zu erhalten», orangefarbener Balken, der sich füllt, je näher die Schwelle rückt.
• Ziel erreicht (Schwelle überschritten): heller grüner Hintergrund, Nachricht «Geschenk zu Ihrem Warenkorb hinzugefügt!», Balken vollständig grün gefüllt. Eine pulse-Animation wird beim Übergang von ausstehend zu erreicht ausgelöst.

Farben anpassen

Farben sind in views/css/dffreegift.css definiert. Um sie ohne Modifikation des Moduls anzupassen (das würde Ihre Änderungen bei Updates überschreiben), überschreiben Sie die Klassen im CSS Ihres Themes:

.dffreegift-progress {
    border-color: #ihre-farbe;
    background: #ihr-hintergrund;
}
.dffreegift-progress--reached {
    background: #ihr-helles-gruen;
    border-color: #ihr-gruen;
}
.dffreegift-progress__bar-fill {
    background: linear-gradient(90deg, #farbe1, #farbe2);
}

Texte anpassen

Kundenseitige Texte sind über den Standard-PrestaShop-Mechanismus übersetzbar. Gehen Sie zu International → Übersetzungen, wählen Sie «Modulübersetzungen», wählen Sie dffreegift und die Sprache, und suchen Sie den Domain Modules.Dffreegift.Shop. Verfügbare Strings:

• «Fügen Sie %amount% hinzu, um Ihr Geschenk zu erhalten» — ausstehende Nachricht (%amount% wird automatisch durch den formatierten Restbetrag je Währung und Locale ersetzt).
• «Geschenk zu Ihrem Warenkorb hinzugefügt!» — Nachricht bei erreichtem Ziel.
• «Fortschritt zum Geschenk» — ARIA-Label des Balkens (wird von Screenreadern gelesen).

Koexistenz mit anderen Aktionen

Da das Geschenk über eine native CartRule hinzugefügt wird, koexistiert es normal mit jeder anderen CartRule. Erwartete Verhalten:

• Andere Kundengutscheincodes (Prozentrabatt, Festbetrag, kostenloser Versand): gelten normal parallel zum Geschenk. Das Geschenk verbraucht den Rabatt nicht und umgekehrt.
• Andere Regel mit gift_product woanders konfiguriert: PrestaShop behandelt beide als unabhängige Regeln und fügt beide Geschenke hinzu. Vorsicht, wenn Sie mehrere Geschenkmodule stapeln.
• Regel mit product_restriction, die den Geschenkartikel ausschließt: Die einschränkende Regel gewinnt. Das Geschenk wird nicht hinzugefügt, wenn eine andere aktive Regel es explizit ausschließt.
• Regel mit cart_rule_restriction: Verbietet eine andere Regel die Verwendung unserer durch Kreuzbeschränkung, wird das Auto-Hinzufügen blockiert (natives PrestaShop-Verhalten).

Multi-Shop

Das Modul funktioniert mit dem Multi-Shop-Setup von PrestaShop im Standard-Shop-Kontext. Konfigurationen (Schwelle, Geschenkartikel, Optionen) werden per Configuration::updateValue gespeichert, das den aktuellen Shop-Kontext respektiert. Die bei der Installation erstellte CartRule wird dem zur Installationszeit aktiven Shop zugeordnet.

Für einen Multi-Shop-Rollout mit unterschiedlichen Geschenken pro Shop muss das Modul derzeit in jedem Shop-Kontext separat installiert und konfiguriert werden. Kontaktieren Sie den Support für eine Variante mit explizitem id_shop-Scoping.

Fehlerbehebung

Das Geschenk wird nicht zum Warenkorb hinzugefügt

In dieser Reihenfolge prüfen:

1. Ist das Modul richtig aktiviert? (Module → Konfigurieren → Schalter Modul aktivieren).
2. Ist der Geschenkartikel gültig? (korrekte ID, aktives Produkt, auf Lager falls Lagerprüfung aktiv).
3. Ist der Kunde in einer erlaubten Gruppe? (Wenn Sie nach Gruppen einschränken, sieht ein nicht identifizierter Besucher, der in keiner erlaubten Gruppe ist, nichts).
4. Ist die Schwelle tatsächlich erreicht? Rechnen Sie die Summe gemäß Ihrer Parameter (brutto/netto, mit/ohne Versand) manuell nach.
5. Existiert die Phantom-CartRule und ist sie aktiv? Gehen Sie zu Katalog → Rabatte → Warenkorbregeln und suchen Sie nach DFFREEGIFT_.

Der Fortschrittsblock erscheint nicht auf der Warenkorbseite

Häufige Ursachen:

• Der Schalter Fortschrittsmeldung anzeigen steht auf Nein.
• Der Kunde ist gemäß den konfigurierten Kundengruppen nicht berechtigt.
• Der Geschenkartikel ist ungültig (existiert nicht, inaktiv oder nicht verfügbar bei aktiver Lagerprüfung).
• Ihr benutzerdefiniertes Theme ruft den Hook displayShoppingCart nicht auf. Prüfen Sie mit dem Befehl grep -r "displayShoppingCart" themes/ihr-theme/ oder in Module → Positionen.

Die CartRule ist aus dem Backoffice verschwunden

Hat jemand die Regel unter Katalog → Rabatte gelöscht, hat der Hook actionObjectCartRuleDeleteBefore die Löschung erkannt und die Konfiguration zurückgesetzt. Bei der nächsten Warenkorb-Synchronisation (also beim nächsten Produkt-Hinzufügen durch einen Kunden) wird automatisch eine neue Regel mit einem neuen DFFREEGIFT_xxxxxxxx-Code erstellt.

Um die Regeneration sofort zu erzwingen, ohne auf einen Kunden zu warten:

1. Gehen Sie zu Module → DataFirefly Free Gift → Deaktivieren.
2. Dann wieder Aktivieren. Das erzeugt eine saubere Regel neu.

Fehler in den PrestaShop-Logs

Das Modul loggt Exceptions unter Erweiterte Parameter → Logs mit dem Präfix [dffreegift]. Eine typische Meldung im Fehlerfall:

[dffreegift] actionCartSave error: <Fehlerbeschreibung>

Diese Fehler unterbrechen niemals den Warenkorbfluss — sie sind rein informativ. Bei wiederkehrenden Logs leiten Sie die vollständige Nachricht an den Support weiter.

Die Schwelle scheint falsch berechnet

Die Berechnung hängt strikt von Ihren Parametern Bruttoberechnung und Versandkosten einschließen ab. Um zu prüfen, was PrestaShop zurückgibt:

• Brutto + ohne Versand: entspricht dem Zwischensumme Produkte (brutto) in der Warenkorbübersicht.
• Brutto + mit Versand: entspricht der Gesamtsumme (brutto) (Produkte + Versand, falls ein Versanddienstleister gewählt).
• Netto + ohne Versand: entspricht der Zwischensumme Produkte (netto).
• Netto + mit Versand: entspricht der Gesamtsumme (netto) (Produkte + Versand netto).

Wenn Sie eine Abweichung feststellen, vergleichen Sie mit der genauen Zeile in der Warenkorbübersicht — meist liegt die Lücke an Versandkosten, die noch nicht berechnet sind (der Kunde hat noch keinen Versanddienstleister gewählt, also ist der Versand 0 €).

Deinstallation

Gehen Sie zu Module → Module-Manager → DataFirefly Free Gift → Deinstallieren. Die Deinstallation entfernt:

• Die Phantom-CartRule und alle ihre Warenkorb-Zuordnungen (laufende Warenkörbe verlieren ihr Geschenk automatisch).
• Alle Konfigurationsschlüssel mit dem Präfix DFFREEGIFT_.

Kurz-FAQ

• Erscheint das Geschenk im Header-Mini-Warenkorb? Nein, nur auf der Warenkorbseite (Hook displayShoppingCart). Der Mini-Warenkorb wird von jedem Theme unterschiedlich behandelt und eine themenspezifische Integration wäre nötig. Auf Anfrage beim Support.
• Kann ich mehrere Geschenke mit mehreren Schwellen anbieten (z. B. Geschenk A bei 50 €, Geschenk B bei 100 €)? Nein, Version 1.0.0 verwaltet ein Geschenk mit einer Schwelle. Für mehrere Stufen den Support kontaktieren.
• Ist das Geschenk in Rückerstattungen enthalten? Wie jedes native PrestaShop-Geschenkprodukt erscheint das Geschenk in der Bestellung zum Preis 0. Bei Teilrückerstattung bleibt das Geschenk ohne finanziellen Effekt in der Bestellung.
• Kann ich die Datei dffreegift.php direkt bearbeiten? Technisch ja (Quellcode nicht verschlüsselt), aber offizielle Updates überschreiben Ihre Änderungen. Für tiefgreifende Anpassungen ein Override-Modul erstellen.

Support und Updates

Das Modul enthält 12 Monate Updates und Support ab Kaufdatum. Support per E-Mail auf Französisch oder Englisch, Antwort innerhalb von 24 Werkstunden.

Bei Fragen oder Problemen kontaktieren Sie den DataFirefly-Support unter Angabe von:

• PrestaShop-Version (sichtbar unter Erweiterte Parameter → Information)
• PHP-Version
• Installierte dffreegift-Version
• Beschreibung des beobachteten vs. erwarteten Verhaltens
• Auszug aus den PrestaShop-Logs falls anwendbar ([dffreegift])