WhatsApp
+48608012047
Instrukcja instalacji i konfiguracji 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.
Wymagania
- Magento Open Source
2.4.9albo 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.
Instalacja
W projekcie Magento uruchom:
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.
Lokalna walidacja pakietu
W repozytorium pakietu możesz uruchomić:
./scripts/validate-local.sh
Skrypt sprawdza podstawowe pliki JSON, PHP, PHTML, XML, rejestracje modułów i schematy GraphQL.
Miejsce konfiguracji w panelu Magento
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.
General
| Pole | Ścieżka config | Domyślnie | Znaczenie |
|---|---|---|---|
| Enable Loyalty | kowal_loyalty/general/enabled |
No |
Włącza program lojalnościowy dla wybranego website. Bez tego moduły domenowe nie powinny obsługiwać klienta jako uczestnika aktywnego programu. |
| Debug Mode | kowal_loyalty/general/debug |
No |
Włącza dodatkową diagnostykę dla wybranego website. Używaj na stagingu albo przy analizie problemów. |
| Log Retention Days | kowal_loyalty/general/log_retention_days |
30 |
Globalny czas przechowywania logów lojalnościowych w dniach. |
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.
Program
| Pole | Ścieżka config | Domyślnie | Znaczenie |
|---|---|---|---|
| Program ID | kowal_loyalty/program/program_id |
default |
Wewnętrzny identyfikator programu. MVP zakłada jeden program per website. Najczęściej zostaw default. |
| Program Name | kowal_loyalty/program/name |
Loyalty & Rewards |
Nazwa programu widoczna dla klienta w widgetach, landing page i panelu konta. |
| Short Description | kowal_loyalty/program/short_description |
Earn points, unlock rewards and use them on future orders. |
Krótki opis programu używany w prezentacji frontendowej. |
| Program Status | kowal_loyalty/program/status |
draft |
Status programu. Tylko aktywny program jest traktowany jako dostępny dla klientów. |
| Program Visibility | kowal_loyalty/program/visibility |
public |
Steruje widocznością programu w warstwie storefront. |
| Program Terms CMS Page | kowal_loyalty/program/program_terms_cms_page |
0 |
Strona CMS z regulaminem programu lojalnościowego. Link może być używany automatycznie przez formularze i widgety. |
| Store Terms CMS Page | kowal_loyalty/program/store_terms_cms_page |
0 |
Strona CMS z regulaminem sklepu, wymagana szczególnie przy zapisie gościa i tworzeniu konta. |
Rekomendacja: przed włączeniem programu publicznie utwórz strony CMS z regulaminem programu i regulaminem sklepu, a następnie przypisz je w konfiguracji.
Points Defaults
| Pole | Ścieżka config | Domyślnie | Znaczenie |
|---|---|---|---|
| Default Points Expiration Days | kowal_loyalty/points/expiration_days |
365 |
Liczba dni ważności punktów liczona od daty aktywacji. |
| Default Rounding Mode | kowal_loyalty/points/rounding_mode |
floor |
Sposób zaokrąglania punktów: w dół, standardowo albo w górę. |
| Default Earning Amount Basis | kowal_loyalty/points/earning_amount_basis |
base_row_total_incl_tax_after_discount |
Podstawa wartości zamówienia używana do naliczania punktów. Wysyłka jest zawsze wyłączona. |
| Earn Points After Order Status | kowal_loyalty/points/earning_order_status |
complete |
Status zamówienia, po którym punkty zakupowe są naliczane. |
| Activate Pending Points After Order Status | kowal_loyalty/points/activation_order_status |
complete |
Status zamówienia, po którym punkty oczekujące mogą stać się dostępne. |
| Activation Delay Days | kowal_loyalty/points/activation_delay_days |
0 |
Dodatkowe opóźnienie aktywacji punktów. 0 oznacza aktywację bez opóźnienia po spełnieniu statusu. |
| Expiration Notification Days | kowal_loyalty/points/expiration_notification_days |
30,7,1 |
Progi powiadomień przed wygaśnięciem punktów, oddzielone przecinkami. |
Opcje Default Earning Amount Basis:
| Wartość | Znaczenie | Kiedy użyć |
|---|---|---|
base_row_total_incl_tax_after_discount |
Kwota brutto po rabatach | Najczęstszy wariant B2C, klient zdobywa punkty od realnie zapłaconej wartości produktów. |
base_row_total_incl_tax_before_discount |
Kwota brutto przed rabatami | Gdy promocje cenowe nie mają zmniejszać liczby zdobywanych punktów. |
base_row_total_after_discount |
Kwota netto po rabatach | Dla B2B lub sklepów, które rozliczają lojalność na wartości netto. |
base_row_total_before_discount |
Kwota netto przed rabatami | Dla programów liczonych od katalogowej wartości netto produktów. |
Rekomendacja: dla typowego sklepu B2C zostaw Gross After Discounts, rounding_mode = floor, statusy complete i ważność punktów 365 dni.
Point Redemption
| Pole | Ścieżka config | Domyślnie | Znaczenie |
|---|---|---|---|
| Points | kowal_loyalty/redemption/points |
100 |
Liczba punktów odpowiadająca skonfigurowanej kwocie rabatu. |
| Discount Amount | kowal_loyalty/redemption/base_amount |
10 |
Kwota rabatu w walucie bazowej website dla wskazanej liczby punktów. |
| Minimum Points To Redeem | kowal_loyalty/redemption/min_points |
100 |
Minimalna liczba punktów, którą klient może wykorzystać w koszyku. |
| Minimum Order Amount | kowal_loyalty/redemption/min_order_amount |
100 |
Minimalna wartość zamówienia kwalifikująca użycie punktów. Wysyłka jest wyłączona z podstawy walidacji. |
| Maximum Order Percent Paid With Points | kowal_loyalty/redemption/max_order_percent |
30 |
Maksymalny procent kwalifikowanej wartości zamówienia, który może zostać pokryty punktami. |
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
| Pole | Ścieżka config | Domyślnie | Znaczenie |
|---|---|---|---|
| Program | kowal_loyalty/features/program |
Yes |
Włącza warstwę programu i kontekstu website. |
| Rules | kowal_loyalty/features/rules |
No |
Włącza obsługę reguł naliczania punktów. |
| Points | kowal_loyalty/features/points |
No |
Włącza ledger punktów i projekcję salda. |
| Rewards | kowal_loyalty/features/rewards |
No |
Włącza mechanizmy nagród i wykorzystania punktów. |
| Checkout | kowal_loyalty/features/checkout |
No |
Włącza integrację z koszykiem i checkoutem. |
| Content | kowal_loyalty/features/content |
No |
Włącza warstwę contentu, landing pages, widgety i bloki frontendowe. |
| Leaderboard | kowal_loyalty/features/leaderboard |
No |
Włącza ranking klientów, jeżeli moduł jest zainstalowany. |
| Gamification | kowal_loyalty/features/gamification |
No |
Włącza deterministyczne mechaniki promocyjne. |
| Lottery | kowal_loyalty/features/lottery |
No |
Włącza moduł loterii i gier losowych. |
Feature flags pozwalają uruchamiać pakiet etapowo. Dla pierwszej konfiguracji zwykle włącz: Program, Rules, Points, Rewards, Checkout i Content.
Leaderboard
| Pole | Ścieżka config | Domyślnie | Znaczenie |
|---|---|---|---|
| Enable Leaderboard | kowal_loyalty/leaderboard/enabled |
No |
Włącza materializację rankingów przez cron. Pozostaw wyłączone do czasu akceptacji zasad prywatności. |
| Allow Public Leaderboard Widgets | kowal_loyalty/leaderboard/public_enabled |
No |
Pozwala wyświetlać publiczne widgety rankingów. Gdy wyłączone, widgety nie renderują publicznego rankingu. |
| Default Metric | kowal_loyalty/leaderboard/default_metric |
points |
Domyślna metryka rankingu: punkty, postęp wyzwań, polecenia albo opinie. |
| Default Widget Limit | kowal_loyalty/leaderboard/default_limit |
10 |
Liczba pozycji w widgetach. Kod ogranicza wartość do maksymalnie 100. |
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.
Gamification
| Pole | Ścieżka config | Domyślnie | Znaczenie |
|---|---|---|---|
| Enable Gamification Mechanics | kowal_loyalty/gamification/enabled |
No |
Włącza deterministyczne mechaniki promocyjne, np. Spin the Wheel i Scratch & Win. |
| Gamification feature flag | kowal_loyalty/features/gamification |
No |
Flaga funkcji dla obszaru gamifikacji. |
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ą.
Lotteries and Games of Chance
| Pole | Ścieżka config | Domyślnie | Znaczenie |
|---|---|---|---|
| Enable Lottery Module | kowal_loyalty/lottery/enabled |
No |
Włącza moduł loterii. Pozostaw wyłączone bez wcześniejszej weryfikacji prawnej. |
| Allow Public Lottery Widgets | kowal_loyalty/lottery/public_widgets_enabled |
No |
Pozwala renderować publiczne widgety aktywnych kampanii z zatwierdzeniem prawnym. |
| Lottery feature flag | kowal_loyalty/features/lottery |
No |
Flaga funkcji dla obszaru loterii. |
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
Reguły punktowe są zarządzane w panelu administracyjnym modułu. Ich formularz zawiera:
| Pole | Znaczenie |
|---|---|
| Enabled | Czy reguła jest aktywna. |
| Program ID | Program, którego dotyczy reguła. W MVP zwykle default. |
| Name | Nazwa reguły widoczna w administracji. |
| Description | Opis pomocniczy dla administratora. |
| Event Type | Zdarzenie, za które naliczane są punkty, np. zakup, newsletter, referral. |
| Points Mode | Sposób naliczania punktów, np. stała wartość albo wartość zależna od kwoty. |
| Points Value | Liczba punktów albo przelicznik używany przez wybrany tryb. |
| Priority | Kolejność ewaluacji. Reguły pasujące do zdarzenia sumują się; priorytet nie zatrzymuje kolejnych reguł. |
| Related Landing Page Identifier | Identyfikator strony CMS powiązanej z regułą. |
| Website IDs | Lista ID website oddzielona przecinkami. Puste pole oznacza wszystkie website. |
| Customer Group IDs | Lista ID grup klientów oddzielona przecinkami. Puste pole oznacza wszystkie grupy. |
| From Date / To Date | Okres obowiązywania reguły. |
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 klientów
Poziomy są zarządzane jako encje administracyjne. Formularz poziomu zawiera:
| Pole | Znaczenie |
|---|---|
| Enabled | Czy poziom jest aktywny. |
| Program ID | Program, którego dotyczy poziom. W MVP zwykle default. |
| Name | Nazwa poziomu, np. Silver, Gold, VIP. |
| Code | Techniczny kod poziomu. |
| Sort Order | Kolejność poziomów. |
| Minimum Completed Purchase Amount | Minimalna wartość zakończonych zamówień z ostatnich 12 miesięcy, bez wysyłki. |
| Minimum Completed Orders | Minimalna liczba zakończonych zamówień. |
| Minimum Earned Points | Minimalna liczba zdobytych punktów. |
| Bonus Multiplier | Mnożnik bonusu. 1.25 oznacza osobną transakcję bonusową +25% względem bazowych punktów. |
| Website IDs | Lista ID website oddzielona przecinkami. Puste pole oznacza wszystkie website. |
Domyślne poziomy instalowane jako szablony:
| Poziom | Próg zakupów | Mnożnik |
|---|---|---|
| Silver | 1000 |
1.25 |
| Gold | 3000 |
1.5 |
| VIP | 7500 |
2.0 |
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.
Przykłady konfiguracji
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 PageiStore Terms CMS Pagewskazują 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,Contentustawione naYes.
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 = 14albo30.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 Amountustaw zgodnie z minimalną wartością zamówienia B2B, np.500.Maximum Order Percent Paid With Pointsustaw konserwatywnie, np.10albo20.
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 Amountdo 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,referralsalboreviews.Default Widget Limit = 10albo inna rozsądna wartość.Allow Public Leaderboard Widgets = Yesdopiero 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 = Yesdopiero 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.
Checklist przed produkcją
- 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.
Przydatne miejsca w panelu
Stores > Configuration > Kowal > Loyalty & Rewards- główna konfiguracja programu.Customers > Loyalty & Rewardsalbo menu administracyjneKowal 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.
Uwagi operacyjne
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.