Smart Offers — Vollständige Dokumentation

Smart Offers ist ein PrestaShop 8 Modul, mit dem Sie 1+1-Angebote, Mengenpakete, Multi-Produkt-Pakete und Wahlangebote erstellen können — mit automatischem Hinzufügen der Geschenkprodukte zum Warenkorb und einer sorgfältigen Darstellung auf der Produktseite.

Überblick

Smart Offers deckt die vier am häufigsten verwendeten Formate gruppierter Angebote im E-Commerce in einem einzigen Modul ab, ohne komplexe Konfiguration. Die Engine bewertet den Warenkorb bei jeder Änderung, fügt die Geschenkprodukte automatisch hinzu, sobald die Bedingungen erfüllt sind, und erstellt eine Warenkorbregel, die diese Einheiten kostenlos macht — das Kundenerlebnis ist sofort und lesbar.

Installation

1. Laden Sie die Datei dfoffers-vX.Y.Z.zip aus Ihrem DataFirefly-Kundenbereich herunter
2. Gehen Sie im PrestaShop-Backoffice zu Module → Modulverwaltung
3. Klicken Sie auf die Schaltfläche Modul hochladen oben auf der Seite
4. Ziehen Sie die ZIP-Datei per Drag-and-Drop oder klicken Sie, um sie auszuwählen
5. Die Installation erfolgt automatisch: Tabellen werden erstellt, Hooks registriert, und ein neuer Reiter Katalog → Gruppierte Angebote erscheint im Menü

Die vier Angebotstypen

1+1 auf dasselbe Produkt

Das virale Buy-One-Get-One-Format: Der Kunde kauft eine Einheit eines Produkts und erhält eine weitere Einheit desselben Produkts kostenlos. Sie konfigurieren:

• Ein einziges Produkt (als Trigger UND als Belohnung verwendet)
• Die zu kaufende Menge, um das Angebot auszulösen (in der Regel 1)
• Die Geschenkmenge (in der Regel 1)

Typisches Beispiel: „Beim Kauf von 1 Paar Socken ist das zweite gratis.“ Wenn der Kunde das Paar in seinen Warenkorb legt, fügt die Engine automatisch ein zweites hinzu und wendet einen Rabatt in Höhe des Stückpreises an.

Kaufe X, erhalte Y kostenlos (verschiedene Produkte)

Bundle-Format: Mehrere unterschiedliche Trigger-Produkte müssen im Warenkorb vorhanden sein, damit das Angebot aktiviert wird, und dann werden ein oder mehrere verschiedene Produkte kostenlos angeboten. Sie konfigurieren:

• Die Liste der Trigger-Produkte mit ihren jeweiligen Mengen
• Die Liste der Belohnungsprodukte mit ihren jeweiligen Mengen

Typisches Beispiel: „Beim Kauf einer Tagescreme und eines Serums zusammen erhalten Sie eine Maskenprobe gratis.“ Die Engine prüft, ob alle Trigger vorhanden sind, bevor sie das Angebot aktiviert.

Variantenwahl

Freies Kompositionsformat: Sie definieren eine Liste möglicher Produkte oder Varianten, aus denen der Kunde sein Los zusammenstellt. Die Engine identifiziert automatisch die billigsten Warenkorbartikel als kostenlose Einheiten, was der üblichen kommerziellen Interpretation des Buy-N-Get-M entspricht.

• Die Liste möglicher Produkte oder Varianten
• Die Anzahl der zu kaufenden Einheiten aus dieser Menge
• Die Anzahl der Geschenkeinheiten (die billigsten)

Typisches Beispiel: „3 T-Shirts aus unserer Auswahl gekauft, das billigste ist gratis.“ Der Kunde stellt sein Los zusammen, die Engine berührt seinen Warenkorb nicht, sondern wendet einen Rabatt auf die billigsten Einheiten an.

Mengenpaket

B2B- und Lagerräumungsformat: Für jedes Los von X gekauften Einheiten eines Produkts erhält der Kunde Y kostenlose Einheiten eines anderen Produkts. Sie konfigurieren:

• Das Trigger-Produkt mit der Stufenmenge (z. B. 10)
• Das Belohnungsprodukt mit der angebotenen Menge (z. B. 20)

Typisches Beispiel: „Für 10 gekaufte Weinflaschen erhalten Sie 2 Gläser gratis.“ Praktisch für Lieferanten, die ein ergänzendes Produkt fördern oder ruhenden Bestand abbauen wollen, indem sie ihn an ein gut verkauftes Produkt hängen.

Ihr erstes Angebot erstellen

Gehen Sie im Backoffice zu Katalog → Gruppierte Angebote und klicken Sie auf Neues Angebot.

Schritt 1: Typ wählen

Vier visuelle Karten präsentieren Ihnen die verfügbaren Typen mit einer kurzen Beschreibung. Klicken Sie auf die, die Ihrer kommerziellen Aktion entspricht. Das Formular passt sich automatisch an und zeigt nur die für diesen Typ relevanten Felder.

Schritt 2: Angebot benennen und mit Badge versehen

Geben Sie Folgendes ein:

• Angebotsname (Pflichtfeld): Das, was der Kunde im Banner sehen wird. Verfügbar in fünf Sprachen.
• Badge-Text (optional, max. 64 Zeichen): kurze Nachricht, die im Pill oben am Banner angezeigt wird (z. B. 1+1 GRATIS, SONDERANGEBOT, BLACK FRIDAY).
• Badge-Farbe: sechs DataFirefly-Presets verfügbar plus ein freier Farbwähler. Die Farbe wird sowohl für das Banner der Produktseite ALS AUCH für die Geschenkmarke auf der Warenkorbseite verwendet.

Schritt 3: Trigger-Produkte hinzufügen

Klicken Sie auf Trigger-Produkt hinzufügen. Ein Suchmodal öffnet sich mit einem Feld, das Ihren Katalog live abfragt (Debounce 250 ms nach dem letzten Tastendruck). Geben Sie einen Namen, eine Referenz oder eine EAN ein; die Ergebnisse erscheinen sofort.

Klicken Sie auf ein Produkt, um es hinzuzufügen. Wenn das Produkt Varianten hat, erscheinen die Varianten als Schaltflächen unter dem Ergebnis — klicken Sie auf die, die Sie interessiert, um sie direkt hinzuzufügen. Geben Sie die erforderliche Menge im Feld rechts neben der Zeile an.

Schritt 4: Geschenkprodukte hinzufügen

Gleiches Verfahren für die Geschenkprodukte. Dieser Abschnitt ist für den Typ Variantenwahl ausgeblendet, da die Varianten sowohl als Kandidaten als auch als Belohnungen dienen.

Schritt 5: spezifische Regeln

• Kumulierbar: Wenn aktiviert, gilt das Angebot mehrmals für jedes Trigger-Los. Ohne Kumulierung gilt das Angebot nur einmal unabhängig von der Anzahl der Einheiten. Standardmäßig deaktiviert, um Ihre Margen zu schützen.
• Für den Typ Variantenwahl erscheinen zwei zusätzliche Felder: wie viele Einheiten der Kunde kaufen muss und wie viele kostenlos angeboten werden.

Schritt 6: Aktivierung

• Gültigkeitsdaten: Lassen Sie leer für ein permanentes Angebot. Geben Sie das Start- oder Enddatum ein, um die Aktivierung zu automatisieren.
• Priorität: Wenn mehrere Angebote gleichzeitig gelten können, wird dasjenige mit der niedrigsten Priorität zuerst ausgewertet.
• Status: On/Off-Schalter, standardmäßig aktiviert. Praktisch, um ein Angebot vorübergehend zu deaktivieren, ohne es zu löschen.

Schritt 7: Shops (bei Multi-Shop)

Wählen Sie die Shops aus, in denen das Angebot verfügbar sein soll. Nichts ankreuzen bedeutet, dass das Angebot in allen Shops aktiv ist.

Wie die Auto-Add-Engine funktioniert

Die Engine hängt sich an den PrestaShop-Hook actionCartSave und läuft bei jeder Warenkorbänderung (Hinzufügen, Entfernen, Mengenänderung, Zusammenführung beim Login).

1. Sie ruft alle aktiven Angebote für den aktuellen Shop ab
2. Für jedes Angebot berechnet sie die bezahlte Menge jedes Trigger-Produkts (Gesamtmenge im Warenkorb minus dem, was die Engine bei einer vorherigen Auswertung bereits automatisch hinzugefügt hat)
3. Sie bewertet, ob die Bedingungen des Angebots erfüllt sind
4. Wenn ja, fügt sie die fehlenden Geschenkprodukte über Cart::updateQty zum Warenkorb hinzu
5. Sie erstellt oder aktualisiert eine Warenkorbregel (CartRule) mit einem festen Bruttorabatt in Höhe des Wertes der angebotenen Einheiten
6. Sie zeichnet in der Tabelle ps_dfoffers_cart_auto die hinzugefügten Einheiten auf, um sie von den Einheiten zu unterscheiden, die der Kunde selbst hinzugefügt hat

Sauberer Widerruf

Wenn der Kunde ein Trigger-Produkt entfernt oder seine Menge unter die Schwelle reduziert, bewertet die Engine das Angebot beim nächsten actionCartSave neu. Wenn die Bedingung nicht mehr erfüllt ist, entfernt sie die automatisch hinzugefügten Einheiten (ohne die vom Kunden selbst hinzugefügten Einheiten dank des Trackings zu berühren) und löscht die zugehörige Warenkorbregel.

Darstellung auf der Produktseite

Auf jeder Trigger-Produktseite wird ein Verlaufsbanner über den Hook displayProductAdditionalInfo angezeigt. Es enthält:

• Ein weißes Pill-Badge mit Geschenk-Icon, das den Badge-Text enthält
• Den Angebotstitel
• Eine dynamische Nachricht je nach Angebotstyp („Fügen Sie 1 Produkt hinzu, erhalten Sie 1 gratis“, „Für 10 gekaufte Einheiten, 20 Einheiten gratis“ usw.)
• Ein Raster mit klickbaren Miniaturansichten der beteiligten Produkte, getrennt in zwei Gruppen Kaufen / Gratis erhalten mit einem kreisförmigen SVG-Separator dazwischen

Die Bannerfarbe übernimmt die im Angebot konfigurierte Badge-Farbe. Die Darstellung ist responsiv: Auf Mobilgeräten stapeln sich die beiden Gruppen vertikal, und der Separator dreht sich, um nach unten zu zeigen.

Darstellung im Warenkorb

Seit Version 1.1.0 helfen zwei verschiedene Indikatoren dem Kunden, die Geschenkprodukte in seinem Warenkorb zu identifizieren.

Geschenk-Badge auf jeder Zeile

Auf jeder Warenkorbzeile, die von einem Angebot automatisch hinzugefügte Einheiten enthält, erscheint ein kleines farbiges Badge 🎁 ×N gratis neben den Zeilenaktionen. Die Farbe übernimmt die des Angebots-Badges, und das Badge zeigt an, wie viele Einheiten dieser Zeile kostenlos sind (nützlich, wenn ein Teil der Menge bezahlt und der andere angeboten wird, z. B. bei einem 1+1 gleiches Produkt).

Detaillierter Warenkorb-Footer

Unter dem Produktraster fasst ein grüner Block die im Warenkorb aktivierten Angebote zusammen. Für jedes Angebot zeigt der Block:

• Den Angebotsnamen und seinen Badge-Text (in farbigem Pill)
• Die Liste der von diesem Angebot angebotenen Produkte als visuelle Chips mit runder Miniaturansicht, Name und Menge
• Jeder Chip ist klickbar und führt zur Produktseite des Geschenks

Der Kunde kann so auf einen Blick überprüfen, was er kostenlos erhalten hat und durch welche kommerzielle Aktion.

Sonderfälle und Verhalten

Warum 1+1 auf dasselbe Produkt speziell behandelt wird

Wenn das Trigger-Produkt auch das Geschenkprodukt ist, machen viele Bundle-Angebotsmodule auf dem Markt den Fehler, die bezahlte Einheit des Kunden als bereits die angebotene Einheit zu identifizieren, und wenden den Rabatt auf diese Einheit an — am Ende zahlt der Kunde null für eine Einheit, anstatt für eine zu zahlen und eine zweite gratis zu erhalten.

Smart Offers behandelt diesen Fall mit präziser Logik: Die Zielmenge im Warenkorb entspricht vom Kunden bezahlte Menge + Belohnungsmenge. Wenn der Kunde eine Einheit hinzufügt, fügt die Engine eine zweite hinzu, damit der Warenkorb zwei Einheiten enthält, und der Rabatt gilt nur für die zweite Einheit. Der Kunde zahlt also den Preis einer Einheit, um zwei in seinem Warenkorb zu haben.

Kumulierung von Losen (Stackable-Option)

Ohne Kumulierung gilt das Angebot nur einmal unabhängig von der Anzahl der Trigger-Lose im Warenkorb. Wenn der Kunde 5 Einheiten eines Produkts mit einem 1+1-Angebot und deaktiviertem Stackable kauft, erhält er 1 kostenlose Einheit (nicht 5).

Mit aktivierter Kumulierung multipliziert die Engine die Anzahl der Belohnungslose mit der ganzzahligen Anzahl der vorhandenen Trigger-Lose. Für dasselbe 1+1-Angebot mit aktivem Stackable und 5 Einheiten im Warenkorb erhält der Kunde 5 kostenlose Einheiten (Endwarenkorb: 10 Einheiten, 5 bezahlt).

Bestand und Nichtverfügbarkeit

Das Hinzufügen der Geschenkprodukte zum Warenkorb erfolgt über Cart::updateQty, das die nativen Bestandsregeln von PrestaShop respektiert. Wenn ein Geschenkprodukt nicht auf Lager ist und der Shop keine Bestellung ohne Lager erlaubt, schlägt das Hinzufügen stillschweigend fehl und der Rabatt wird nicht angewendet — die Bedingung bleibt bereit, sich auszulösen, sobald das Produkt wieder verfügbar ist.

Mehrere gleichzeitige Angebote im selben Warenkorb

Jedes Angebot generiert seine eigene Warenkorbregel mit aktiviertem partial_use. Dies ermöglicht das Stapeln mehrerer gleichzeitiger Angebote im selben Warenkorb ohne Konflikt und ist mit den klassischen Gutscheincodes kompatibel, die Ihre Kunden eingeben können.

Technische Architektur

Verwendete Hooks

• displayProductAdditionalInfo: Banner auf der Produktseite
• displayShoppingCartFooter: detaillierter Footer auf der Warenkorbseite
• displayCartExtraProductActions: Geschenk-Badge auf jeder Warenkorbzeile
• actionCartSave: Bewertungs- und Auto-Add-Engine
• actionFrontControllerSetMedia und actionAdminControllerSetMedia: CSS- und JS-Injektion
• actionObjectProductDeleteAfter: automatische Bereinigung von Angeboten, die auf ein gelöschtes Produkt verweisen

Hinzugefügte Tabellen

• ps_dfoffers_offer: Konfiguration jedes Angebots (Typ, Daten, Priorität, Kumulierung)
• ps_dfoffers_offer_lang: übersetzter Name, Badge und Beschreibung pro Sprache
• ps_dfoffers_trigger: Trigger-Produkte jedes Angebots
• ps_dfoffers_reward: Belohnungsprodukte jedes Angebots
• ps_dfoffers_shop: Angebot-/Shop-Zuordnung im Multi-Shop
• ps_dfoffers_cart_auto: Tracking der automatisch hinzugefügten Einheiten pro Warenkorb und pro Angebot, mit der ID der generierten Warenkorbregel

Alle Tabellen verwenden das in Ihrer PrestaShop-Installation konfigurierte Präfix (ps_ standardmäßig).

Templates in Ihrem Theme überschreiben

Das CSS des Moduls ist unter dem Präfix .dfoffers- isoliert, um Konflikte mit Ihrem Stylesheet zu vermeiden. Wenn Sie das Rendering ändern möchten, kopieren Sie die Templates von /modules/dfoffers/views/templates/hook/ nach /themes/ihr-theme/modules/dfoffers/views/templates/hook/ und passen Sie sie an. Drei Templates sind verfügbar:

• product-banner.tpl: Banner auf der Produktseite
• cart-offer.tpl: Zusammenfassungsblock im Warenkorb-Footer
• cart-line-gift.tpl: Inline-Geschenk-Badge auf Warenkorbzeilen

Modul aktualisieren

Um auf eine neue Version zu aktualisieren, laden Sie einfach das neue ZIP über die Modulverwaltung hoch. PrestaShop erkennt den Versionswechsel in config.xml und führt automatisch die Upgrade-Skripte aus, die in /upgrade/upgrade-X.Y.Z.php vorhanden sind und beispielsweise das Registrieren neuer Hooks zwischen Versionen übernehmen.

Fehlerbehebung

Die Geschenkprodukte werden nicht zum Warenkorb hinzugefügt

1. Leeren Sie den PrestaShop-Cache unter Erweiterte Parameter → Leistung
2. Überprüfen Sie, dass der Hook actionCartSave das Modul unter Design → Positionen enthält
3. Überprüfen Sie, dass das Geschenkprodukt verfügbar ist (nicht ausverkauft, wenn Bestellungen ohne Bestand verboten sind, nicht deaktiviert, dem aktuellen Shop zugewiesen)
4. Konsultieren Sie Erweiterte Parameter → Logs und suchen Sie nach dfoffers: Die Engine protokolliert ihre Ausführung bei jeder Warenkorbänderung

Der Rabatt wird trotz Hinzufügen des Produkts nicht angewendet

Überprüfen Sie in den Logs die Zeile checkValidity, die auf die Erstellung der Warenkorbregel folgt. PrestaShop gibt genau an, warum eine Regel abgelehnt wird (Bestand erschöpft, Kundenbeschränkung, andere Währung usw.).

Das Geschenk-Badge erscheint nicht auf den Warenkorbzeilen

Überprüfen Sie, dass Ihr Theme den Hook displayCartExtraProductActions in cart-detailed-product-line.tpl implementiert. Das Classic-Theme und die meisten kommerziellen Themes enthalten ihn. Wenn Sie ein benutzerdefiniertes Theme verwenden, das ihn nicht implementiert, fügen Sie die folgende Zeile in Ihre Datei cart-detailed-product-line.tpl an der gewünschten Stelle ein:

{hook h='displayCartExtraProductActions' product=$product}

Häufig gestellte Fragen

Ist das Modul mit PrestaShop 9 kompatibel?

Nein, die Version 1.x deckt nur PrestaShop 8.0 bis 8.99 ab. Eine 2.x-Version, die mit PrestaShop 9 kompatibel ist, ist aufgrund der bedeutenden Änderungen an der Controller-API in PS 9 separat geplant.

Welche Auswirkung hat es auf die Performance?

Die Engine führt eine SQL-Abfrage pro aktivem Angebot im Shop aus und bewertet die Bedingungen dann im Speicher. Bei einem Katalog mit etwa zehn aktiven Angeboten dauert die vollständige Bewertung im Durchschnitt weniger als fünfzig Millisekunden.

Kann ich das Modul mit einem Headless-Theme verwenden?

Die Auto-Add-Engine ist Theme-unabhängig und funktioniert für jedes Frontend, das über Cart::updateQty oder die PrestaShop REST API läuft. Das Banner auf der Produktseite und das Geschenk-Badge im Warenkorb sind native Smarty-Hooks, die ein klassisches Theme zur Anzeige benötigen. Für ein Headless-Frontend können Sie die Daten über eine benutzerdefinierte API offenlegen, die direkt ps_dfoffers_offer und ps_dfoffers_cart_auto abfragt.

Verwaltet das Modul mehrere Währungen?

Ja. Die für jedes Angebot generierte Warenkorbregel verwendet die Währung des aktuellen Warenkorbs. Wenn der Kunde die Währung wechselt, wird die Regel beim nächsten actionCartSave mit dem korrekten Wert neu generiert.