Program lojalnościowy Magento 2 - Kowal Loyalty & Rewards Suite

Ten dokument opisuje instalację oraz podstawową konfigurację pakietu kowal/metapackage-loyalty-suite w Magento 2. Instrukcja bazuje na aktualnym kodzie modułów, konfiguracji system.xml, wartościach domyślnych config.xml oraz dokumentacji produktu.

• Magento Open Source 2.4.9 albo zgodna instalacja Magento 2.4.x.
• PHP ^8.3.
• Dostęp do konsoli serwera Magento.
• Włączony cron Magento.
• Skonfigurowany co najmniej jeden website, store i store view.
• Aktywne moduły Magento używane przez pakiet, m.in. Customer, Sales, Quote, Checkout, CMS, Newsletter, SalesRule, Webapi, GraphQl, UI i ImportExport.

Pakiet jest instalowany jako jeden root package Composer. Moduły cząstkowe znajdują się w packages/, ale standardowa instalacja nie wymaga instalowania ich osobno.

W projekcie Magento uruchom:

Dane dostępowe do repozytorium Composer (adres e-mail klienta i token licencyjny) otrzymasz e-mailem po zakupie. Są również dostępne w panelu klienta po zalogowaniu na kowal.store. Zastąp TWOJ_EMAIL_KLIENTA adresem e-mail swojego konta, a TWOJ_TOKEN otrzymanym tokenem. Polecenia wykonaj w katalogu głównym Magento.

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

Po instalacji sprawdź, czy cron Magento działa poprawnie. Cron jest potrzebny m.in. do aktywacji punktów oczekujących, wygasania punktów, powiadomień i odświeżania rankingów.

W repozytorium pakietu możesz uruchomić:

./scripts/validate-local.sh

Skrypt sprawdza podstawowe pliki JSON, PHP, PHTML, XML, rejestracje modułów i schematy GraphQL.

Główna konfiguracja znajduje się w:

Stores > Configuration > Kowal > Loyalty & Rewards

Konfiguracja jest w większości zakresowana per website. Oznacza to, że program można włączyć dla jednego website i pozostawić wyłączony dla innego.

Rekomendacja: na produkcji ustaw Enable Loyalty = Yes tylko dla website, dla którego program ma być aktywny. Debug Mode pozostaw jako No, chyba że diagnozujesz konkretny problem.

Rekomendacja: przed włączeniem programu publicznie utwórz strony CMS z regulaminem programu i regulaminem sklepu, a następnie przypisz je w konfiguracji.

Opcje Default Earning Amount Basis:

Rekomendacja: dla typowego sklepu B2C zostaw Gross After Discounts, rounding_mode = floor, statusy complete i ważność punktów 365 dni.

Przykład: wartości Points = 100 i Discount Amount = 10 oznaczają, że 100 punktów daje 10 jednostek waluty bazowej rabatu. Przy Maximum Order Percent Paid With Points = 30 klient może punktami pokryć maksymalnie 30% kwalifikowanej wartości koszyka.

Rekomendacja: na start ustaw konserwatywny limit, np. 20-30%, żeby program nie przejmował całej marży zamówienia.

Feature flags pozwalają uruchamiać pakiet etapowo. Dla pierwszej konfiguracji zwykle włącz: Program, Rules, Points, Rewards, Checkout i Content.

Rekomendacja: używaj publicznych rankingów tylko wtedy, gdy masz zaakceptowaną politykę prywatności i komunikację z klientem. Moduł domyślnie używa pseudonimów zamiast danych osobowych.

Mechaniki gamifikacyjne nie są prawdziwą loterią. Wybór nagród jest deterministyczny albo oparty na zdefiniowanej sekwencji, co ułatwia kontrolę prawną i budżetową.

Rekomendacja: dla zwykłych promocji używaj Gamification. Lottery włączaj tylko dla kampanii, które mają osobny regulamin, zatwierdzenie prawne i krajowy zakres zgodny z przepisami.

Reguły punktowe są zarządzane w panelu administracyjnym modułu. Ich formularz zawiera:

Przykład prostej reguły zakupowej: Event Type = purchase, Points Mode = amount based, Points Value = 1, aktywna dla wszystkich grup i tylko dla wybranego website. Oznacza to naliczanie punktów według wartości koszyka zgodnie z podstawą z konfiguracji Points Defaults.

Przykład bonusu newsletterowego: Event Type = newsletter_signup, Points Mode = fixed, Points Value = 50, okres bez daty końcowej. Reguła nalicza jednorazowy bonus po zapisie klienta do newslettera, jeśli integracja newslettera wywoła odpowiednie zdarzenie.

Poziomy są zarządzane jako encje administracyjne. Formularz poziomu zawiera:

Domyślne poziomy instalowane jako szablony:

Wartości domyślne traktuj jako punkt startowy. Przed produkcją dopasuj progi do średniej wartości zamówienia, marży i częstotliwości zakupów.

1. Prosty program punktowy dla sklepu B2C

Cel: klient zbiera punkty za zakupy i może je wydać w koszyku.

Ustawienia:

• Enable Loyalty = Yes.
• Program Status = active.
• Program Visibility = public.
• Program Terms CMS Page i Store Terms CMS Page wskazują poprawne strony CMS.
• Default Earning Amount Basis = Gross After Discounts.
• Earn Points After Order Status = complete.
• Activate Pending Points After Order Status = complete.
• Activation Delay Days = 0.
• Default Points Expiration Days = 365.
• Points = 100, Discount Amount = 10.
• Minimum Points To Redeem = 100.
• Minimum Order Amount = 100.
• Maximum Order Percent Paid With Points = 30.
• Feature flags: Program, Rules, Points, Rewards, Checkout, Content ustawione na Yes.

Dodaj regułę punktową za zakup i przetestuj cały przepływ: enrollment, zamówienie, naliczenie punktów, użycie punktów w koszyku.

2. Program z opóźnioną aktywacją punktów

Cel: punkty stają się dostępne dopiero po czasie na zwrot.

Ustawienia:

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

Ten wariant ogranicza ryzyko wydania punktów przez klienta przed zakończeniem okresu zwrotu.

3. Program B2B liczony od wartości netto

Cel: naliczanie punktów od wartości netto produktów, bez wysyłki i bez podatku.

Ustawienia:

• Default Earning Amount Basis = Net After Discounts.
• Default Rounding Mode = floor.
• Minimum Order Amount ustaw zgodnie z minimalną wartością zamówienia B2B, np. 500.
• Maximum Order Percent Paid With Points ustaw konserwatywnie, np. 10 albo 20.

Ten wariant jest sensowny, gdy lojalność ma być rozliczana bliżej marży i fakturowanej wartości netto.

4. Program VIP z poziomami klientów

Cel: lepsi klienci zdobywają dodatkowe punkty.

Ustawienia:

• Włącz podstawowe feature flags programu, punktów, reguł i checkoutu.
• Skonfiguruj poziomy, np. Silver, Gold, VIP.
• Ustaw Bonus Multiplier: 1.25, 1.5, 2.0.
• Dopasuj progi Minimum Completed Purchase Amount do danych sprzedażowych.

Bonus poziomu jest zapisywany jako osobna transakcja w ledgerze. Dzięki temu raporty mogą oddzielić bazowe punkty od punktów bonusowych.

5. Kampania z rankingiem

Cel: wyświetlanie publicznego rankingu klientów w kampanii.

Ustawienia:

• Leaderboard feature flag = Yes.
• Enable Leaderboard = Yes.
• Default Metric = points, challenge_progress, referrals albo reviews.
• Default Widget Limit = 10 albo inna rozsądna wartość.
• Allow Public Leaderboard Widgets = Yes dopiero po akceptacji zasad prywatności.

Przed publikacją sprawdź treść regulaminu, politykę prywatności i sposób prezentacji aliasów klientów.

6. Promocja Spin the Wheel bez loterii

Cel: kontrolowana akcja promocyjna z nagrodami bez mechanizmu losowego.

Ustawienia:

• Gamification feature flag = Yes.
• Enable Gamification Mechanics = Yes.
• Nie włączaj Lottery, jeśli promocja nie jest prawnie loterią.
• Użyj mechaniki deterministycznej albo predefiniowanej sekwencji nagród.
• Ustaw limity udziału klienta, e-maila, budżetu punktów i liczby wygranych w konfiguracji mechaniki.

Ten wariant jest właściwy dla akcji marketingowych, które mają wyglądać atrakcyjnie, ale muszą pozostać kontrolowane budżetowo i audytowalne.

7. Loteria lub gra losowa

Cel: uruchomienie kampanii z realnym elementem losowym.

Ustawienia:

• Lottery feature flag = Yes.
• Enable Lottery Module = Yes.
• Allow Public Lottery Widgets = Yes dopiero po przygotowaniu kampanii.
• Kampania musi mieć status aktywny, właściwy website i country scope oraz legal_approval_status = approved.
• Dodaj osobny regulamin CMS i landing page kampanii.

Nie używaj tego wariantu bez weryfikacji prawnej dla kraju, w którym działa sklep.

• Program włączony tylko dla właściwych website.
• Status programu ustawiony na aktywny.
• Regulamin programu i regulamin sklepu przypisane do stron CMS.
• Newsletter opisany jasno jako warunek pełnych praw programu.
• Reguły punktowe sprawdzone na stagingu.
• Limity wykorzystania punktów policzone względem marży.
• Zwroty i credit memo przetestowane ręcznie.
• Cron Magento działa i przetwarza punkty oczekujące, wygasanie oraz rankingi.
• Publiczne rankingi i loterie zaakceptowane prawnie.
• REST API i GraphQL sprawdzone pod kątem dostępu tylko do danych właściwego klienta.
• Import korekt punktowych przetestowany pod kątem idempotencji.

• Stores > Configuration > Kowal > Loyalty & Rewards - główna konfiguracja programu.
• Customers > Loyalty & Rewards albo menu administracyjne Kowal Loyalty - uczestnicy, ledger, ręczne korekty i raporty, zależnie od włączonych modułów.
• CMS Pages - regulaminy programu, regulamin sklepu i landing pages.
• Cart Price Rules - reguły rabatowe używane przez nagrody kuponowe.

Ledger punktów jest źródłem prawdy. Tabela sald jest projekcją do szybkich odczytów w frontendzie, checkoutcie i panelu administracyjnym. Nie należy ręcznie edytować sald bez transakcji ledgerowej.

Reguły punktowe są kumulatywne. Jeżeli kilka aktywnych reguł pasuje do zdarzenia, klient może otrzymać kilka osobnych transakcji punktowych. Priorytet reguły steruje kolejnością i czytelnością audytu, a nie zatrzymaniem dalszych reguł.

Punkty wykorzystane w koszyku są zapisywane na quote, przenoszone do order i rozliczane po złożeniu zamówienia. Zwroty oraz credit memo powinny być testowane dla pełnych i częściowych zwrotów, szczególnie gdy sklep używa punktów jako rabatu.