# 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…

- Seite: <https://www.datafirefly.com/de/documentation/dffreegift/>
- Sprache: de
- Aktualisiert am: 2026-08-05
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dffreegift/index.md), [en](https://www.datafirefly.com/en/documentation/dffreegift/index.md), [es](https://www.datafirefly.com/es/documentation/dffreegift/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffreegift/index.md), [it](https://www.datafirefly.com/it/documentation/dffreegift/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffreegift/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffreegift/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

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**.

**Hinweis.** Die bei der Installation erstellte CartRule hat noch keinen Geschenkartikel zugewiesen (`gift_product = 0`) und ist daher funktional noch nicht aktiv. Sie wird synchronisiert, sobald Sie eine Geschenkartikel-ID im Konfigurationsbildschirm speichern.

## 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.

**Tipp.** Wenn Sie den Geschenkartikel später ändern, wird die CartRule beim Speichern automatisch resynchronisiert. Sie müssen die Regel im Rabatte-Bereich nie manuell anfassen.

### 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.

**Empfehlung.** Diese Prüfung aktiviert lassen. Sie zu deaktivieren, kann zu blockierten Bestellungen an der Kasse führen, weil das Geschenk nicht verfügbar ist — verschlechterte Kundenerfahrung und manueller Eingriff nötig.

### 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).

**Hinweis.** Die Schwelle von dffreegift wird auf die Summe _ohne das Geschenk_ ausgewertet. Wenn Sie eine andere Cart-Rule haben, die die Summe rabattiert, bevor dffreegift sie auswertet, erfolgt der Vergleich auf die Summe _nach Rabatt_. Ein Warenkorb von 60 € mit 15 € Rabatt fällt auf 45 € und löst keine Schwelle von 50 € aus.

## 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_`.

**Achtung.** Die Deinstallation stellt Geschenke in vergangenen Bestellungen nicht wieder her — diese behalten ihren ursprünglichen Snapshot mit dem Geschenk korrekt erfasst. Nur laufende Warenkörbe sind betroffen.

## 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](https://www.datafirefly.com/de/kontaktieren-sie-uns/) 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]`)