Magento 2 Treueprogramm - Kowal Loyalty & Rewards Suite

Installations- und Konfigurationsanleitung für Kowal Loyalty & Rewards Suite

Dieses Dokument beschreibt die Installation und grundlegende Konfiguration des Paketskowal/metapackage-loyalty-suitein Magento 2. Die Anleitung basiert auf dem aktuellen Modulcode, der Konfigurationsystem.xml, den Standardwerten ausconfig.xmlund der Produktdokumentation.

Anforderungen

• Magento Open Source2.4.9oder eine kompatible Magento-2.4.x-Installation.
• PHP^8.3verwenden.
• Zugriff auf die Konsole des Magento-Servers.
• Aktivierter Magento-Cron.
• Mindestens eine konfigurierte Website, ein Store und eine Store View.
• Aktive Magento-Module, die vom Paket verwendet werden, darunter Customer, Sales, Quote, Checkout, CMS, Newsletter, SalesRule, Webapi, GraphQl, UI und ImportExport.

Das Paket wird als einzelnes Composer-Root-Package installiert. Die Teilmodule befinden sich unterpackages/, müssen bei einer Standardinstallation jedoch nicht separat installiert werden.

Installation

Führen Sie im Magento-Projekt Folgendes aus:

Die Zugangsdaten für das Composer-Repository – E-Mail-Adresse des Kunden und Lizenz-Token – erhalten Sie nach dem Kauf per E-Mail. Sie sind nach der Anmeldung auf kowal.storeebenfalls im Kundenkonto verfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch das erhaltene Token. Führen Sie die Befehle im Magento-Stammverzeichnis aus.

composer config repositories.kowal composer https://repo.kowal.store
composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
composer require kowal/metapackage-loyalty-suite:^0.1
bin/magento module:enable Kowal_Loyalty Kowal_LoyaltyProgram Kowal_LoyaltyRules Kowal_LoyaltyPoints Kowal_LoyaltyRewards Kowal_LoyaltyCheckout Kowal_LoyaltyEnrollment Kowal_LoyaltyConsent Kowal_LoyaltyNewsletter Kowal_LoyaltyContent Kowal_LoyaltyTiers Kowal_LoyaltyCampaigns Kowal_LoyaltyWallet Kowal_LoyaltyCoupons Kowal_LoyaltyChallenges Kowal_LoyaltyBadges Kowal_LoyaltyLeaderboard Kowal_LoyaltyReferrals Kowal_LoyaltyGamification Kowal_LoyaltyLottery Kowal_LoyaltyCommunication Kowal_LoyaltyReports Kowal_LoyaltyAdminUi Kowal_LoyaltyApi Kowal_LoyaltyGraphQl Kowal_LoyaltyImportExport Kowal_LoyaltyIntegration
bin/magento setup:upgrade
bin/magento cache:flush

Prüfen Sie nach der Installation, ob der Magento-Cron ordnungsgemäß funktioniert. Cron wird unter anderem für die Aktivierung ausstehender Punkte, den Punkteverfall, Benachrichtigungen und die Aktualisierung von Ranglisten benötigt.

Lokale Paketvalidierung

Im Paket-Repository können Sie Folgendes ausführen:

./scripts/validate-local.sh

Das Skript prüft grundlegende JSON-, PHP-, PHTML- und XML-Dateien sowie Modulregistrierungen und GraphQL-Schemas.

Konfigurationsbereich im Magento Admin

Die Hauptkonfiguration befindet sich unter:

Stores > Configuration > Kowal > Loyalty & Rewards

Die Konfiguration ist größtenteils auf Website-Ebene definiert. Dadurch kann das Programm für eine Website aktiviert und für eine andere deaktiviert bleiben.

General

Empfehlung: Setzen Sie in der ProduktionsumgebungEnable Loyalty = Yesnur für die Website, auf der das Programm aktiv sein soll. Lassen SieDebug ModeaufNo, sofern Sie nicht ein konkretes Problem untersuchen.

Program

Empfehlung: Erstellen Sie vor der öffentlichen Aktivierung des Programms CMS-Seiten mit den Programmbedingungen und den Geschäftsbedingungen des Shops und weisen Sie diese anschließend in der Konfiguration zu.

Points Defaults

Optionen fürDefault Earning Amount Basisfest:

Empfehlung: Lassen Sie für einen typischen B2C-ShopGross After Discounts,rounding_mode = floor, die Statuswertecompleteund eine Punktegültigkeit von365Tagen eingestellt.

Point Redemption

Beispiel: Die WertePoints = 100undDiscount Amount = 10bedeuten, dass 100 Punkte einen Rabatt von 10 Einheiten der Basiswährung ergeben. BeiMaximum Order Percent Paid With Points = 30kann der Kunde höchstens 30% des qualifizierten Warenkorbwerts mit Punkten abdecken.

Empfehlung: Legen Sie zunächst ein konservatives Limit fest, beispielsweise 20-30%, damit das Programm nicht die gesamte Marge der Bestellung aufzehrt.

Feature Flags

Feature Flags ermöglichen die schrittweise Aktivierung des Pakets. Für die erste Konfiguration werden üblicherweiseProgram,Rules,Points,Rewards,CheckoutundContentverwenden.

Leaderboard

Empfehlung: Verwenden Sie öffentliche Ranglisten nur, wenn eine freigegebene Datenschutzrichtlinie und eine entsprechende Kundenkommunikation vorhanden sind. Das Modul verwendet standardmäßig Pseudonyme anstelle personenbezogener Daten.

Gamification

Gamification-Mechanismen sind keine echte Lotterie. Die Auswahl der Prämien erfolgt deterministisch oder anhand einer definierten Reihenfolge, was die rechtliche und budgetäre Kontrolle erleichtert.

Lotteries and Games of Chance

Empfehlung: Verwenden Sie für gewöhnliche AktionenGamificationverwenden.Lotterynur für Kampagnen mit eigenen Teilnahmebedingungen, rechtlicher Freigabe und einem rechtskonformen Geltungsbereich.

Punkteregeln

Punkteregeln werden im Admin-Bereich des Moduls verwaltet. Das Formular enthält:

Beispiel für eine einfache Einkaufsregel:Event Type = purchase,Points Mode = amount based,Points Value = 1, aktiv für alle Gruppen und nur für die ausgewählte Website. Dadurch werden Punkte entsprechend dem Warenkorbwert und der unterPoints Defaultsverwenden.

Beispiel für einen Newsletter-Bonus:Event Type = newsletter_signup,Points Mode = fixed,Points Value = 50, ohne Enddatum. Die Regel vergibt einen einmaligen Bonus nach der Newsletter-Anmeldung des Kunden, sofern die Newsletter-Integration das entsprechende Ereignis auslöst.

Kundenstufen

Stufen werden als administrative Entitäten verwaltet. Das Stufenformular enthält:

Standardmäßig als Vorlagen installierte Stufen:

Betrachten Sie die Standardwerte als Ausgangspunkt. Passen Sie die Schwellenwerte vor dem Produktivbetrieb an den durchschnittlichen Bestellwert, die Marge und die Kaufhäufigkeit an.

Konfigurationsbeispiele

1. Einfaches B2C-Punkteprogramm

Ziel: Der Kunde sammelt Punkte für Einkäufe und kann sie im Warenkorb einlösen.

Einstellungen:

• Enable Loyalty = Yesverwenden.
• Program Status = activeverwenden.
• Program Visibility = publicverwenden.
• Program Terms CMS PageundStore Terms CMS Pageverweisen auf die richtigen CMS-Seiten.
• Default Earning Amount Basis = Gross After Discountsverwenden.
• Earn Points After Order Status = completeverwenden.
• Activate Pending Points After Order Status = completeverwenden.
• Activation Delay Days = 0verwenden.
• Default Points Expiration Days = 365verwenden.
• Points = 100,Discount Amount = 10verwenden.
• Minimum Points To Redeem = 100verwenden.
• Minimum Order Amount = 100verwenden.
• Maximum Order Percent Paid With Points = 30verwenden.
• Feature Flags:Program,Rules,Points,Rewards,Checkout,ContentaufYesverwenden.

Fügen Sie eine Punkteregel für Einkäufe hinzu und testen Sie den gesamten Ablauf: Anmeldung, Bestellung, Punktegutschrift und Einlösung der Punkte im Warenkorb.

2. Programm mit verzögerter Punkteaktivierung

Ziel: Punkte werden erst nach Ablauf der Rückgabefrist verfügbar.

Einstellungen:

• Earn Points After Order Status = completeverwenden.
• Activate Pending Points After Order Status = completeverwenden.
• Activation Delay Days = 14oder30verwenden.
• Default Points Expiration Days = 365verwenden.
• Expiration Notification Days = 30,7,1verwenden.

Diese Variante reduziert das Risiko, dass Kunden Punkte vor Ablauf der Rückgabefrist einlösen.

3. B2B-Programm auf Nettowertbasis

Ziel: Punkteberechnung auf Grundlage des Nettoproduktwerts, ohne Versandkosten und Steuern.

Einstellungen:

• Default Earning Amount Basis = Net After Discountsverwenden.
• Default Rounding Mode = floorverwenden.
• Minimum Order Amountentsprechend dem B2B-Mindestbestellwert fest, beispielsweise500verwenden.
• Maximum Order Percent Paid With Pointskonservativ fest, beispielsweise auf10oder20verwenden.

Diese Variante eignet sich, wenn das Treueprogramm näher an der Marge und dem fakturierten Nettowert ausgerichtet werden soll.

4. VIP-Programm mit Kundenstufen

Ziel: Bessere Kunden erhalten zusätzliche Punkte.

Einstellungen:

• Aktivieren Sie die grundlegenden Feature Flags für Programm, Punkte, Regeln und Checkout.
• Konfigurieren Sie Stufen wie Silver, Gold und VIP.
• Legen SieBonus Multiplierfest:1.25,1.5,2.0verwenden.
• Passen Sie die Schwellenwerte fürMinimum Completed Purchase Amountan die Verkaufsdaten an.

Der Stufenbonus wird als separate Transaktion im Ledger gespeichert. Dadurch können Berichte Basispunkte und Bonuspunkte getrennt darstellen.

5. Kampagne mit Rangliste

Ziel: Anzeige einer öffentlichen Kundenrangliste innerhalb einer Kampagne.

Einstellungen:

• Leaderboard feature flag = Yesverwenden.
• Enable Leaderboard = Yesverwenden.
• Default Metric = points,challenge_progress,referralsoderreviewsverwenden.
• Default Widget Limit = 10oder einen anderen angemessenen Wert.
• Allow Public Leaderboard Widgets = Yeserst nach Freigabe der Datenschutzregeln.

Prüfen Sie vor der Veröffentlichung die Teilnahmebedingungen, die Datenschutzrichtlinie und die Darstellung der Kunden-Aliase.

6. Spin-the-Wheel-Aktion ohne Lotterie

Ziel: Kontrollierte Werbeaktion mit Prämien ohne Zufallsmechanismus.

Einstellungen:

• Gamification feature flag = Yesverwenden.
• Enable Gamification Mechanics = Yesverwenden.
• Aktivieren SieLotterynicht, wenn die Aktion rechtlich keine Lotterie ist.
• Verwenden Sie einen deterministischen Mechanismus oder eine vordefinierte Prämienfolge.
• Legen Sie in der Mechanikkonfiguration Limits für Kunden- und E-Mail-Teilnahmen, Punktebudget und Anzahl der Gewinne fest.

Diese Variante eignet sich für Marketingaktionen, die attraktiv wirken sollen, zugleich aber budgetär kontrollierbar und revisionsfähig bleiben müssen.

7. Lotterie oder Glücksspiel

Ziel: Start einer Kampagne mit einem echten Zufallselement.

Einstellungen:

• Lottery feature flag = Yesverwenden.
• Enable Lottery Module = Yesverwenden.
• Allow Public Lottery Widgets = Yeserst nach Vorbereitung der Kampagne.
• Die Kampagne muss aktiv sein, die richtige Website und den richtigen country scope besitzen sowielegal_approval_status = approvedverwenden.
• Fügen Sie separate CMS-Teilnahmebedingungen und eine Kampagnen-Landingpage hinzu.

Verwenden Sie diese Variante nicht ohne rechtliche Prüfung für das Land, in dem der Shop betrieben wird.

Checkliste vor dem Produktivbetrieb

• Das Programm ist nur für die richtigen Websites aktiviert.
• Der Programmstatus ist auf aktiv gesetzt.
• Programmbedingungen und Geschäftsbedingungen des Shops sind CMS-Seiten zugeordnet.
• Der Newsletter wird eindeutig als Voraussetzung für die vollständigen Programmrechte beschrieben.
• Punkteregeln wurden in der Staging-Umgebung geprüft.
• Einlösungslimits für Punkte wurden im Verhältnis zur Marge berechnet.
• Rückgaben und Credit Memos wurden manuell getestet.
• Magento-Cron funktioniert und verarbeitet ausstehende Punkte, Verfall und Ranglisten.
• Öffentliche Ranglisten und Lotterien wurden rechtlich freigegeben.
• REST API und GraphQL wurden darauf geprüft, dass nur auf Daten des jeweiligen Kunden zugegriffen werden kann.
• Der Import von Punktekorrekturen wurde auf Idempotenz geprüft.

Nützliche Bereiche im Admin

• Stores > Configuration > Kowal > Loyalty & Rewards– Hauptkonfiguration des Programms.
• Customers > Loyalty & Rewardsoder das Admin-MenüKowal Loyalty– Teilnehmer, Ledger, manuelle Korrekturen und Berichte, abhängig von den aktivierten Modulen.
• CMS Pages – Programmbedingungen, Geschäftsbedingungen des Shops und Landingpages.
• Cart Price Rules – Rabattregeln für Couponprämien.

Betriebliche Hinweise

Das Punkte-Ledger ist die maßgebliche Datenquelle. Die Guthabentabelle ist eine Projektion für schnelle Abfragen im Frontend, Checkout und Admin-Bereich. Guthaben dürfen nicht ohne eine Ledger-Transaktion manuell bearbeitet werden.

Punkteregeln sind kumulativ. Wenn mehrere aktive Regeln auf ein Ereignis zutreffen, kann der Kunde mehrere separate Punktetransaktionen erhalten. Die Regelpriorität steuert die Reihenfolge und Nachvollziehbarkeit der Prüfung, nicht das Anhalten nachfolgender Regeln.

Im Warenkorb eingelöste Punkte werden im Quote gespeichert, in die Bestellung übertragen und nach der Bestellaufgabe abgerechnet. Rückgaben und Credit Memos sollten für vollständige und teilweise Erstattungen getestet werden, insbesondere wenn der Shop Punkte als Rabatt verwendet.