Smart Offers — Vollständige Dokumentation

Smart Offers ist ein mit PrestaShop 8 und 9 kompatibles 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.

Kompatibilität mit PrestaShop 8 und 9

Seit Version 2.0.0 deckt eine einzige ZIP-Datei PrestaShop 8.0 bis 9.x ab. Beim Download muss kein separater Zweig gewählt werden: Das Modul erkennt die Shop-Version zur Laufzeit und passt seine Aufrufe an die APIs an, die sich zwischen den beiden Generationen geändert haben.

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. Seit 2.0.0 wird ein unlesbares Datum abgelehnt, statt als 1. Januar 1970 gespeichert zu werden, und das Enddatum muss nach dem Startdatum liegen.
• 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

Seit 2.0.0 gelten nur actionCartSave und actionFrontControllerSetMedia als für die Installation unverzichtbar. Anzeige-Hooks, die ein Theme nicht implementiert, werden protokolliert, ohne die Installation scheitern zu lassen.

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). Das Schema ist auf PrestaShop 8 und 9 identisch, was die Migration transparent macht.

Die Klasse DfOfferCompat

Alle API-Unterschiede zwischen PrestaShop 8 und 9 sind in classes/DfOfferCompat.php konzentriert. Der Rest des Moduls prüft die PrestaShop-Version nie direkt. Die von dieser Klasse aufgefangenen Punkte:

• Auslesen der Varianten: PrestaShop 9 hat das Sprachargument aus Product::getAttributeCombinations() entfernt, wo der erste Parameter nun das boolesche Gruppierungs-Flag ist.
• AJAX-URL des Backoffice: Auf PrestaShop 9 muss das Paar ajax und action über das vierte Argument von getAdminLink() laufen, da das Token vor dem Zusammenführen der Parameter berechnet wird.
• JSON-Antwort: Die Sendemethode trägt bewusst einen anderen Namen als ajaxRender(), dessen übergeordnete Signatur nicht überschrieben werden darf.
• Admin-Reiter: PrestaShop 9 hat zusätzliche Übersetzungsspalten eingeführt, die unter einer Prüfung gefüllt werden, damit auf PrestaShop 8 keine dynamische Eigenschaft entsteht.

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.

Einen Shop von PrestaShop 8 auf PrestaShop 9 migrieren

Da das Datenbankschema identisch ist, überstehen Ihre Angebote, Ihre Übersetzungen und Ihre Shop-Zuordnungen die Migration ohne Transformation. Das empfohlene Vorgehen:

1. Bringen Sie das Modul auf 2.0.0, bevor Sie den Shop migrieren, während er noch unter PrestaShop 8 läuft. Version 2.0.0 funktioniert auf beiden Generationen, so reduzieren Sie die Anzahl der Variablen, falls etwas schiefgeht.
2. Migrieren Sie den Shop nach dem offiziellen PrestaShop-Verfahren auf PrestaShop 9.
3. Gehen Sie zu Design → Positionen und prüfen Sie, ob die sechs Hooks des Moduls noch angehängt sind. Eine Migration kann einige verlieren.
4. Wenn Hooks fehlen, laden Sie das ZIP 2.0.0 erneut hoch: Das Skript upgrade-2.0.0.php registriert jeden fehlenden Hook erneut und bereinigt Tracking-Zeilen, deren Warenkorb nicht mehr existiert.

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. Die Classic-Themes von PrestaShop 8 und 9 sowie 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}

Die Produktsuche im Backoffice liefert nach einer Migration auf PrestaShop 9 nichts zurück

Leeren Sie den PrestaShop-Cache und laden Sie die Seite zur Angebotserstellung neu. Die URL des Such-Endpoints wird beim Rendern des Formulars serverseitig erzeugt; eine vor der Migration zwischengespeicherte Seite kann noch eine alte URL tragen. Wenn das Problem bestehen bleibt, öffnen Sie die Browserkonsole: Eine 404-Antwort auf die Suchanfrage bedeutet, dass der Modul-Reiter nicht korrekt neu erstellt wurde, und eine Neuinstallation des Moduls behebt das, ohne die Angebote zu verlieren.

Die Installation scheint zu gelingen, aber es lässt sich kein Angebot erstellen

Vor 2.0.0 war ein Fehlschlag bei der Tabellenerstellung während der Installation stumm, und das Modul erschien als installiert. Seit 2.0.0 lässt diese Situation die Installation mit einer expliziten Meldung scheitern. Wenn Sie darauf in einer älteren Version stoßen, prüfen Sie die Rechte des MySQL-Benutzers zur Tabellenerstellung, deinstallieren Sie dann das Modul und installieren Sie es in 2.0.0 neu.

Häufig gestellte Fragen

Ist das Modul mit PrestaShop 9 kompatibel?

Ja, seit Version 2.0.0. Dieselbe ZIP-Datei lässt sich auf PrestaShop 8.0 wie auf PrestaShop 9.x installieren. Die API-Unterschiede fängt die interne Klasse DfOfferCompat ab, es muss beim Download also kein separater Zweig gewählt werden. Die 1.x-Versionen blieben auf PrestaShop 8.0 bis 8.99 beschränkt.

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. Dieser Wert ist auf PrestaShop 8 und 9 identisch.

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.

Was passiert, wenn ich in der Modulverwaltung auf Zurücksetzen klicke?

Das Modul wird in derselben Anfrage deinstalliert und neu installiert, wodurch die Tabellen gelöscht und neu erstellt werden: Alle Ihre Angebote gehen verloren. Seit 2.0.0 erstellt dieser Vorgang die Tabellen korrekt neu, während frühere Versionen den Shop ganz ohne Tabellen zurückließen. Sichern Sie in beiden Fällen vor dem Zurücksetzen.