Program de loialitate Magento 2 - Kowal Loyalty & Rewards Suite

Instrucțiuni de instalare și configurare Kowal Loyalty & Rewards Suite

Acest document descrie instalarea și configurarea de bază a pachetului kowal/metapackage-loyalty-suite în Magento 2. Instrucțiunea se bazează pe codul actual al modulelor, configurația system.xml, valorile implicite config.xml și documentația produsului.

Cerințe

• Magento Open Source 2.4.9 sau o instalare compatibilă Magento 2.4.x.
• PHP ^8.3.
• Acces la consola serverului Magento.
• Cron Magento activat.
• Cel puțin un website, store și store view configurate.
• Module Magento active utilizate de pachet, inclusiv Customer, Sales, Quote, Checkout, CMS, Newsletter, SalesRule, Webapi, GraphQl, UI și ImportExport.

Pachetul este instalat ca un singur root package Composer. Modulele parțiale se află în packages/, dar instalarea standard nu necesită instalarea lor separată.

Instalare

În proiectul Magento, rulați:

Datele de acces la repository-ul Composer (adresa de e-mail a clientului și tokenul de licență) le veți primi prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificarea pe kowal.store. Înlocuiți TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului dumneavoastră, iar TWOJ_TOKEN cu tokenul primit. Executați comenzile în directorul rădăcină Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer require kowal/metapackage-loyalty-suite:^0.1bin/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_LoyaltyIntegrationbin/magento setup:upgradebin/magento cache:flush

După instalare, verificați dacă cron Magento funcționează corect. Cron este necesar, printre altele, pentru activarea punctelor în așteptare, expirarea punctelor, notificări și reîmprospătarea clasamentelor.

Validarea locală a pachetului

În repository-ul pachetului puteți rula:

./scripts/validate-local.sh

Scriptul verifică fișierele JSON, PHP, PHTML, XML de bază, înregistrările modulelor și schemele GraphQL.

Locul configurării în panoul Magento

Configurarea principală se află în:

Stores > Configuration > Kowal > Loyalty & Rewards

Configurarea este în mare parte scope-uită per website. Aceasta înseamnă că programul poate fi activat pentru un website și lăsat dezactivat pentru altul.

General

Recomandare: în producție setați Enable Loyalty = Yes doar pentru website-ul pentru care programul trebuie să fie activ. Lăsați Debug Mode ca No, cu excepția cazului în care diagnosticați o problemă concretă.

Program

Recomandare: înainte de activarea publică a programului, creați pagini CMS cu regulamentul programului și termenii magazinului, apoi atribuiți-le în configurare.

Points Defaults

Opțiuni Default Earning Amount Basis:

Recomandare: pentru un magazin B2C tipic, lăsați Gross After Discounts, rounding_mode = floor, statusurile complete și valabilitatea punctelor de 365 zile.

Point Redemption

Exemplu: valorile Points = 100 și Discount Amount = 10 înseamnă că 100 de puncte oferă o reducere de 10 unități ale monedei de bază. Cu Maximum Order Percent Paid With Points = 30, clientul poate acoperi cu puncte maximum 30% din valoarea eligibilă a coșului.

Recomandare: la început setați o limită conservatoare, de ex. 20-30%, pentru ca programul să nu preia întreaga marjă a comenzii.

Feature Flags

Feature flags permit lansarea pachetului etapizat. Pentru prima configurare, de obicei activați: Program, Rules, Points, Rewards, Checkout și Content.

Leaderboard

Recomandare: utilizați clasamente publice doar atunci când aveți politica de confidențialitate și comunicarea cu clientul acceptate. Modulul folosește implicit pseudonime în locul datelor personale.

Gamification

Mecanicile de gamificare nu sunt o loterie reală. Alegerea recompenselor este deterministă sau bazată pe o secvență definită, ceea ce facilitează controlul juridic și bugetar.

Lotteries and Games of Chance

Recomandare: pentru promoțiile obișnuite utilizați Gamification. Activați Lottery doar pentru campaniile care au regulament separat, aprobare juridică și un scope național conform cu legislația.

Reguli de puncte

Regulile de puncte sunt gestionate în panoul de administrare al modulului. Formularul lor include:

Exemplu de regulă simplă de cumpărare: Event Type = purchase, Points Mode = amount based, Points Value = 1, activă pentru toate grupurile și doar pentru website-ul selectat. Aceasta înseamnă acordarea punctelor după valoarea coșului conform bazei din configurarea Points Defaults.

Exemplu de bonus pentru newsletter: Event Type = newsletter_signup, Points Mode = fixed, Points Value = 50, perioadă fără dată de final. Regula acordă un bonus unic după înscrierea clientului la newsletter, dacă integrarea newsletterului declanșează evenimentul corespunzător.

Niveluri de clienți

Nivelurile sunt gestionate ca entități administrative. Formularul nivelului include:

Niveluri implicite instalate ca șabloane:

Tratați valorile implicite ca punct de plecare. Înainte de producție, adaptați pragurile la valoarea medie a comenzii, marjă și frecvența cumpărăturilor.

Exemple de configurare

1. Program simplu de puncte pentru un magazin B2C

Scop: clientul acumulează puncte pentru cumpărături și le poate cheltui în coș.

Setări:

• Enable Loyalty = Yes.
• Program Status = active.
• Program Visibility = public.
• Program Terms CMS Page și Store Terms CMS Page indică pagini CMS corecte.
• 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 setate la Yes.

Adăugați o regulă de puncte pentru cumpărare și testați întregul flux: enrollment, comandă, acordarea punctelor, utilizarea punctelor în coș.

2. Program cu activare întârziată a punctelor

Scop: punctele devin disponibile doar după perioada de retur.

Setări:

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

Această variantă limitează riscul ca punctele să fie cheltuite de client înainte de încheierea perioadei de retur.

3. Program B2B calculat din valoarea netă

Scop: acordarea punctelor din valoarea netă a produselor, fără livrare și fără taxă.

Setări:

• Default Earning Amount Basis = Net After Discounts.
• Default Rounding Mode = floor.
• Minimum Order Amount setați conform valorii minime a comenzii B2B, de ex. 500.
• Maximum Order Percent Paid With Points setați conservator, de ex. 10 sau 20.

Această variantă este potrivită când loialitatea trebuie decontată mai aproape de marjă și de valoarea netă facturată.

4. Program VIP cu niveluri de clienți

Scop: clienții mai buni acumulează puncte suplimentare.

Setări:

• Activați feature flags de bază ale programului, punctelor, regulilor și checkoutului.
• Configurați nivelurile, de ex. Silver, Gold, VIP.
• Setați Bonus Multiplier: 1.25, 1.5, 2.0.
• Adaptați pragurile Minimum Completed Purchase Amount la datele de vânzări.

Bonusul de nivel este salvat ca tranzacție separată în ledger. Datorită acestui lucru, rapoartele pot separa punctele de bază de punctele bonus.

5. Campanie cu clasament

Scop: afișarea unui clasament public al clienților în campanie.

Setări:

• Leaderboard feature flag = Yes.
• Enable Leaderboard = Yes.
• Default Metric = points, challenge_progress, referrals sau reviews.
• Default Widget Limit = 10 sau o altă valoare rezonabilă.
• Allow Public Leaderboard Widgets = Yes doar după acceptarea regulilor de confidențialitate.

Înainte de publicare, verificați conținutul regulamentului, politica de confidențialitate și modul de prezentare a aliasurilor clienților.

6. Promoție Spin the Wheel fără loterie

Scop: acțiune promoțională controlată cu recompense, fără mecanism aleatoriu.

Setări:

• Gamification feature flag = Yes.
• Enable Gamification Mechanics = Yes.
• Nu activați Lottery dacă promoția nu este juridic o loterie.
• Folosiți o mecanică deterministă sau o secvență predefinită de recompense.
• Setați limitele de participare ale clientului, e-mailului, bugetului de puncte și numărului de câștiguri în configurarea mecanicii.

Această variantă este potrivită pentru acțiuni de marketing care trebuie să arate atractiv, dar trebuie să rămână controlate bugetar și auditabile.

7. Loterie sau joc de noroc

Scop: lansarea unei campanii cu un element aleatoriu real.

Setări:

• Lottery feature flag = Yes.
• Enable Lottery Module = Yes.
• Allow Public Lottery Widgets = Yes doar după pregătirea campaniei.
• Campania trebuie să aibă status activ, website-ul și country scope corecte, precum și legal_approval_status = approved.
• Adăugați un regulament CMS separat și landing page-ul campaniei.

Nu utilizați această variantă fără verificare juridică pentru țara în care funcționează magazinul.

Checklist înainte de producție

• Program activat doar pentru website-urile corecte.
• Statusul programului setat ca activ.
• Regulamentul programului și termenii magazinului atribuite paginilor CMS.
• Newsletterul descris clar ca o condiție pentru drepturile complete ale programului.
• Regulile de puncte verificate pe staging.
• Limitele de utilizare a punctelor calculate în raport cu marja.
• Retururile și credit memo testate manual.
• Cron Magento funcționează și procesează punctele în așteptare, expirarea și clasamentele.
• Clasamentele publice și loteriile acceptate juridic.
• REST API și GraphQL verificate din perspectiva accesului doar la datele clientului corect.
• Importul corecțiilor de puncte testat din perspectiva idempotency.

Locuri utile în panou

• Stores > Configuration > Kowal > Loyalty & Rewards - configurarea principală a programului.
• Customers > Loyalty & Rewards sau meniul administrativ Kowal Loyalty - participanți, ledger, corecții manuale și rapoarte, în funcție de modulele activate.
• CMS Pages - regulamentele programului, termenii magazinului și landing pages.
• Cart Price Rules - reguli de reducere utilizate de recompensele pe bază de cupoane.

Observații operaționale

Ledgerul de puncte este sursa adevărului. Tabelul soldurilor este o proiecție pentru citiri rapide în frontend, checkout și panoul de administrare. Soldurile nu trebuie editate manual fără o tranzacție în ledger.

Regulile de puncte sunt cumulative. Dacă mai multe reguli active se potrivesc unui eveniment, clientul poate primi mai multe tranzacții separate de puncte. Prioritatea regulii controlează ordinea și lizibilitatea auditului, nu oprirea regulilor următoare.

Punctele utilizate în coș sunt salvate pe quote, transferate în order și decontate după plasarea comenzii. Retururile și credit memo trebuie testate pentru retururi complete și parțiale, mai ales când magazinul folosește punctele ca reducere.