DF Samples: Produktmuster bestellen (PrestaShop 8 & 9)

Überblick

DF Samples fügt Ihren Produktseiten eine Schaltfläche „Muster bestellen“ hinzu. Das Muster kann kostenlos sein oder ein paar Euro kosten, für das Produkt oder für die vom Kunden gewählte Variante. Das Modul legt für jedes aufgenommene Produkt ein verstecktes Musterprodukt an, fixiert die Menge auf 1, setzt Limits pro Kunde auf den Warenkorbinhalt durch, misst die Conversion vom Muster zum Kauf und verschickt eine Follow-up-E-Mail mit optionalem Rabattgutschein.

Das Modul unterstützt PrestaShop 8.0 bis 9.x, Multistore und mehrere Sprachen und verwendet keinen Core-Override. Diese Dokumentation beschreibt Version 1.1.0.

Installation

1. Gehen Sie im Back-Office zu Module > Modulmanager.
2. Klicken Sie auf Modul hochladen und ziehen Sie die Datei dfsamples.zip hinein.
3. Öffnen Sie Katalog > Muster (DF): Hier finden Sie die Produktliste, das Dashboard und die Einstellungen.

Bei der Installation legt das Modul an:

• drei Tabellen: dfsamples_product, dfsamples_order und dfsamples_cart;
• eine deaktivierte Kategorie Muster unter Startseite, für alle Kundengruppen zugänglich, die die Musterprodukte aufnimmt;
• seine Standardeinstellungen und ein Sicherheitstoken für den Cronjob;
• den Admin-Tab Katalog > Muster (DF);
• eine Kopie der englischen E-Mail-Vorlage für jede installierte Sprache ohne eigene Vorlage.

Es registriert sich auf 12 Hooks, darunter displayProductActions, displayProductAdditionalInfo, displayDfSamplesButton, actionCartSave, actionCartUpdateQuantityBefore, actionValidateOrder und actionOrderStatusPostUpdate.

Update von Version 1.0.0

Laden Sie das neue ZIP im Modulmanager über das alte. Das Update-Skript:

• fügt die Tabelle dfsamples_cart und die neuen Spalten hinzu;
• registriert die neuen Hooks;
• legt die Kategorie Muster an und verschiebt Ihre bestehenden Musterprodukte dorthin;
• benennt sie im neuen Format um und ergänzt fehlende Bilder (unter PrestaShop 9 hat Version 1.0.0 das Bild nicht kopiert);
• behält Ihre aufgenommenen Produkte, Statistiken und den Follow-up-Verlauf.

Schlägt ein Schritt fehl, synchronisiert die Schaltfläche Musterprodukte neu synchronisieren oben auf der Modulseite alle Musterprodukte erneut.

Ein Produkt ins Musterprogramm aufnehmen

1. Öffnen Sie Katalog > Muster (DF) und klicken Sie auf Produkt hinzufügen.
2. Suchen Sie das Produkt nach Name oder Artikelnummer und wählen Sie es aus. Bereits aufgenommene Produkte und Musterprodukte erscheinen nicht in den Ergebnissen.
3. Geben Sie den Musterpreis (inkl. MwSt.) ein. Geben Sie 0,00 für ein kostenloses Muster ein.
4. Legen Sie das Maximum pro Kunde für dieses Produkt im gleitenden Zeitfenster fest (0 = unbegrenzt).
5. Aktivieren Sie Muster je Variante, wenn das Produkt Varianten hat und der Kunde eine wählen soll (siehe unten).
6. Speichern Sie.

Was das Modul beim Speichern tut

Das Modul legt ein verstecktes Musterprodukt an oder aktualisiert das vorhandene:

• übersetzter Name im Format „Muster: Produktname“ (Échantillon, Sample, Muestra, Campione in den anderen Sprachen);
• Artikelnummer im Format SMPL gefolgt von der ID des Quellprodukts;
• Nettopreis, berechnet aus dem eingegebenen Preis und der Steuerregel des Quellprodukts;
• Titelbild des Quellprodukts, in alle Bildformate kopiert;
• Standardkategorie: die Kategorie Muster;
• Sichtbarkeit „nirgendwo“: Das Produkt erscheint weder in Listen noch in der Suche;
• Bestellung ohne Lagerbestand erlaubt, damit eine Anfrage nie blockiert wird;
• Gewicht aus der globalen Einstellung, von den Versanddiensten verwendet.

Ändern Sie später Preis, Varianten-Option, globales Gewicht oder Aktiv-Status, wird das Musterprodukt neu synchronisiert. Wurde es manuell aus dem Katalog gelöscht, wird es beim nächsten Speichern neu angelegt.

Muster je Variante

Mit der Option Muster je Variante wählt der Kunde seine Variante auf der Produktseite wie bei einem normalen Kauf und klickt dann auf die Schaltfläche, die nun „Muster dieser Variante bestellen“ lautet.

• Die Variante wird in der Musterposition gespeichert, zum Beispiel „Format: A4, Papier: Gestrichen 300 g“. Sie erscheint in einem Feld „Variante“ im Warenkorb, in der Bestellung, auf der Rechnung und in der Follow-up-E-Mail.
• Jede Variante erhält eine eigene Position. Dieselbe Variante kann nicht zweimal hinzugefügt werden.
• Das Maximum pro Kunde des Produkts wird pro Variante gezählt.
• Der Musterpreis ist für alle Varianten des Produkts gleich.

Einstellungen

Die Einstellungen befinden sich unter der Produktliste auf der Seite Katalog > Muster (DF).

Allgemeine Einstellungen

• Position der Schaltfläche: unter dem Warenkorb-Button (displayProductActions), im Block für Zusatzinformationen (displayProductAdditionalInfo) oder nur eigene Platzierung (displayDfSamplesButton, siehe nächster Abschnitt).
• Standard-Musterpreis (inkl. MwSt.): vorgeschlagener Wert beim Hinzufügen eines Musters.
• Mustergewicht: in Kilogramm, für alle Musterprodukte, für die Versandkosten verwendet.
• Kundenkonto erforderlich: standardmäßig aktiv. Limits pro Kunde lassen sich nur bei identifizierten Kunden zuverlässig durchsetzen.
• Kundengruppen-Rabatte auf Muster: anwenden (PrestaShop-Standard) oder nicht anwenden. Siehe „Preise und Gruppenrabatte“.
• Musterkategorie: Standardkategorie aller Musterprodukte. Lassen Sie sie deaktiviert. Wählen Sie eine andere Kategorie, werden bestehende Muster dorthin verschoben.
• Musterseiten weiterleiten: standardmäßig aktiv. Ein Besucher auf der Seite eines Musterprodukts wird per 301 zum Quellprodukt weitergeleitet.
• Conversion gezählt bei: nur beim Kauf des gemusterten Produkts oder bei jedem späteren Kauf.

Limits

• Maximale Muster pro Warenkorb: 0 = unbegrenzt.
• Maximale Muster pro Kunde und Zeitfenster: alle Musterprodukte zusammen, 0 = unbegrenzt.
• Gleitendes Zeitfenster: in Tagen, standardmäßig 30. Bei 0 gelten die Kundenlimits für alle früheren Bestellungen, ohne zeitliche Begrenzung.

Automatisches Follow-up

• Follow-up-E-Mails aktivieren.
• Frist nach der Musterbestellung: in Tagen, standardmäßig 14.
• Nur Newsletter-Abonnenten: aktivieren, wenn Ihre Rechtsgrundlage für Werbe-E-Mails die Einwilligung ist.
• Rabattgutschein beilegen: Für jedes Follow-up wird ein personalisierter Einmalgutschein erzeugt.
• Gutscheinhöhe: in Prozent, standardmäßig 10.
• Gültigkeit des Gutscheins: in Tagen, standardmäßig 30.

Die Cron-URL wird in diesem Abschnitt und im Dashboard angezeigt.

Schaltfläche mit Creative Elements oder einem eigenen Theme anzeigen

Ist die Produktseite mit einem Page Builder aufgebaut, werden native Hooks nicht immer ausgegeben, oder nicht an der gewünschten Stelle. Das Modul bietet einen eigenen Hook, displayDfSamplesButton.

1. Wählen Sie in den Einstellungen Position der Schaltfläche: Nur eigene Platzierung (displayDfSamplesButton). Die Schaltfläche wird dann nicht mehr in die nativen Hooks eingefügt, so erscheint sie nicht doppelt.
2. Mit Creative Elements: Fügen Sie in der Vorlage der Produktseite das Widget Module an der gewünschten Stelle ein und wählen Sie das Modul DF Samples und den Hook displayDfSamplesButton.
3. In einem eigenen Theme: Fügen Sie {hook h='displayDfSamplesButton'} in das Template der Produktseite ein, zum Beispiel templates/catalog/product.tpl.

Unabhängig von der Platzierung folgt die Schaltfläche der gewählten Variante und aktualisiert sich, wenn der Kunde sie ändert.

Preise und Gruppenrabatte

Der Musterpreis ist vom Quellprodukt unabhängig: Staffelpreise, Sonderpreise und die Mindestmenge des Quellprodukts gelten nicht. Nur eine Katalog-Preisregel, die alle Produkte ohne Unterschied betrifft, würde auch für Muster gelten.

Ein Kundengruppen-Rabatt (Kunden > Gruppen, zum Beispiel -15 % für Händler) gilt standardmäßig für alle Produkte, Muster eingeschlossen. Mit Nicht anwenden: Muster behalten ihren Preis nimmt das Modul die Musterprodukte vom Rabatt jeder Gruppe aus: Ihre Händler zahlen den festgelegten Musterpreis, und der Rabatt gilt weiter für den restlichen Katalog. Später angelegte Gruppen werden automatisch berücksichtigt.

Die Schaltfläche zeigt den Preis, den der angemeldete Kunde zahlt, inklusive Gruppenrabatt und MwSt.

Limits und Warenkorbkontrolle

Die Regeln werden bei jedem Speichern des Warenkorbs geprüft, nicht nur beim Klick auf die Schaltfläche. Hinzufügen über die Schaltflächen + und – im Warenkorb, über eine direkte URL, über „Erneut bestellen“ oder durch das Zusammenführen von Warenkörben beim Login durchläuft dieselben Prüfungen:

1. Positionen deaktivierter Muster werden entfernt;
2. Duplikate werden entfernt (gleiches Muster oder gleiche Variante im Variantenmodus);
3. die Menge jeder Position wird auf 1 zurückgesetzt;
4. das Maximum pro Warenkorb wird angewendet;
5. das Maximum pro Produkt und das globale Maximum pro Kunde werden im gleitenden Zeitfenster angewendet.

Muss eine Position weichen, wird die jüngste entfernt. Der Kunde sieht eine Meldung auf der Warenkorb- oder Bestellseite. Stornierte, erstattete Bestellungen oder Bestellungen mit Zahlungsfehler zählen nicht zu den Limits. Warenkörbe, die ein Mitarbeiter im Back-Office anlegt, unterliegen keinen Limits.

Cronjob einrichten

Follow-ups werden über einen Cronjob verschickt. Planen Sie die in den Einstellungen angezeigte URL stündlich ein. Crontab-Beispiel:

0 * * * * wget -q -O /dev/null "https://ihr-shop.de/module/dfsamples/cron?token=IHR_TOKEN"

Jeder Lauf verarbeitet bis zu 50 Bestellungen und liefert eine JSON-Zusammenfassung: processed, sent, skipped, waiting und retry.

Regeln des Cronjobs

• Eine E-Mail pro Bestellung, auch wenn sie mehrere Muster enthält. Sie listet die getesteten Produkte auf und enthält höchstens einen Gutschein.
• Berücksichtigt werden nur nicht konvertierte Muster ohne bisheriges Follow-up, sobald die Frist abgelaufen ist.
• Die Musterbestellung muss einen bezahlten, versandten oder zugestellten Status erreicht haben. Eine noch unbezahlte Bestellung wird später erneut geprüft und verworfen, wenn sie 60 Tage nach dem Fälligkeitsdatum des Follow-ups noch immer nicht bezahlt ist.
• Stornierte, erstattete Bestellungen oder Bestellungen mit Zahlungsfehler werden ignoriert.
• Ein Muster, dessen Produkt in derselben Bestellung gekauft wurde, erhält kein Follow-up.
• Bei aktiver Newsletter-Option erhalten nicht angemeldete Kunden kein Follow-up.
• Schlägt der Versand fehl, versucht es das Modul in späteren Läufen erneut, höchstens dreimal und mit mindestens sechs Stunden Abstand. Der für eine nicht versandte E-Mail erzeugte Gutschein wird gelöscht.
• Zwei gleichzeitige Läufe können nicht dieselbe E-Mail senden: Jede Bestellung wird vor der Verarbeitung reserviert.

Conversion-Tracking

Bei der Validierung einer Bestellung mit Muster speichert das Modul den Kunden, seine E-Mail, das Quellprodukt, die Variante, die Sprache und den Shop.

Bestellt dieser Kunde später, werden die passenden Muster als konvertiert markiert:

• im Modus Produkt (Standard): wenn die Bestellung das gemusterte Produkt enthält;
• im Modus jeder Kauf: sobald die Bestellung ein echtes Produkt enthält.

Eine Conversion zählt erst, wenn die Kaufbestellung einen validierten Status erreicht (zum Beispiel Zahlung akzeptiert). Eine per Überweisung bezahlte Bestellung zählt also bei Zahlungseingang. Ein Kauf in derselben Bestellung wie das Muster ist keine Conversion.

Dashboard

Das Panel über der Produktliste zeigt:

• Bestellte Muster: Anzahl der erfassten Musterpositionen;
• Conversions: Anzahl der Muster mit anschließendem Kauf und die Conversion-Rate;
• Umsatz aus Conversions: Bruttosumme der Conversion-Bestellungen, in die Standardwährung umgerechnet;
• Ausstehende Follow-ups.

Die Produktliste zeigt außerdem pro Produkt die Anzahl bestellter Muster, die Anzahl der Conversions und ob der Variantenmodus aktiv ist.

Follow-up-E-Mails

Die Vorlagen liegen im Ordner mails des Moduls, auf Französisch, Englisch, Spanisch, Deutsch und Italienisch, als HTML- und Textversion (dfsamples_followup). Für weitere installierte Sprachen wird bei der Installation die englische Vorlage kopiert: Übersetzen Sie sie im Ordner mails/ gefolgt vom Sprachcode, zum Beispiel mails/nl/.

Verfügbare Variablen:

• {firstname} und {lastname};
• {product_name}: das oder die getesteten Produkte, durch Kommas getrennt;
• {product_link}: Link zur Seite des ersten Produkts;
• {voucher_block}: formatierter Gutschein für die HTML-Version, leer wenn der Gutschein deaktiviert ist;
• {voucher_text}: derselbe Inhalt für die Textversion;
• {shop_name}.

Rabattgutscheine

Ist die Option aktiv, erzeugt jedes Follow-up eine PrestaShop-Warenkorb-Preisregel:

• Code im Format SMPL gefolgt von acht zufälligen Zeichen;
• auf den Empfänger beschränkt, einmal nutzbar;
• prozentualer Rabatt, einstellbare Gültigkeit.

Die Gutscheine stehen unter Katalog > Rabatte > Warenkorb-Preisregeln.

Katalog, Sitemap und Produktfeeds

Musterprodukte haben die Sichtbarkeit „nirgendwo“ und liegen in der deaktivierten Kategorie Muster. Sie erscheinen nicht in Listen, Suche oder Hervorhebungsblöcken, und ihre Seite leitet zum Quellprodukt weiter. Die meisten Sitemap- und Feed-Module überspringen diese Produkte. Bezieht Ihres sie ein, schließen Sie in dessen Einstellungen die Kategorie Muster oder Artikelnummern mit dem Präfix SMPL aus.

Kompatibilität mit dem Bestellprozess

Das Modul greift nicht in den Bestellprozess ein: Ein Muster ist eine normale Produktposition. Es funktioniert mit dem nativen Checkout und mit One-Page-Checkouts, die die nativen PrestaShop-Schritte übernehmen. Die Meldung über ein entferntes Muster erscheint auf Warenkorb- und Bestellseite.

Deinstallation

Die Deinstallation entfernt Tabellen, Einstellungen und Tab des Moduls. Musterprodukte werden deaktiviert, nicht gelöscht, und die Kategorie Muster bleibt erhalten, damit Ihr Bestellverlauf konsistent bleibt. Eine Neuinstallation verwendet diese Kategorie wieder. Sie können diese Produkte und die Kategorie manuell löschen, wenn Sie sie nicht mehr brauchen.

Fehlerbehebung

Die Schaltfläche erscheint nicht auf der Produktseite

Prüfen Sie, ob das Produkt in Katalog > Muster (DF) aufgenommen und aktiv ist. Ändern Sie dann die Position der Schaltfläche: Manche Themes geben displayProductActions nicht aus. Mit einem Page Builder verwenden Sie den Hook displayDfSamplesButton.

Statt der Schaltfläche erscheint eine Meldung

„Sie haben das Musterlimit für dieses Produkt erreicht“: Der Kunde hat sein Maximum im gleitenden Zeitfenster erreicht. „Ihr Warenkorb enthält bereits das Maximum von N Mustern pro Bestellung“: Das Maximum pro Warenkorb ist erreicht. Passen Sie die Limits bei Bedarf an.

Musterprodukte haben kein Bild

Das betraf Muster, die Version 1.0.0 unter PrestaShop 9 angelegt hat. Klicken Sie auf Musterprodukte neu synchronisieren: Fehlende Bilder werden ergänzt.

Der angezeigte Preis ist nicht der erwartete

Der Preis wird inklusive MwSt. eingegeben und über die Steuerregel des Quellprodukts umgerechnet. Bei einem Kunden aus einer rabattierten Gruppe prüfen Sie die Einstellung „Kundengruppen-Rabatte auf Muster“. Eine globale Katalog-Preisregel gilt auch für Muster.

Follow-ups werden nicht verschickt

Öffnen Sie die Cron-URL im Browser und lesen Sie die JSON-Zusammenfassung. enabled: false bedeutet, dass Follow-ups deaktiviert sind. waiting zählt noch unbezahlte Musterbestellungen. Prüfen Sie außerdem die Frist, die Newsletter-Option und die E-Mail-Konfiguration des Shops (Erweiterte Einstellungen > E-Mail).

Ein Muster verschwindet aus dem Warenkorb

Das ist die Warenkorbkontrolle: Duplikat, Maximum pro Warenkorb oder Kundenlimit erreicht. Der Kunde sieht eine Meldung auf der Warenkorbseite.