WhatsApp
+48608012047
Kowal Product Grid Category Filter pentru Magento 2
12,50 EUR 12,50 EUR
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.9sau 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 configurat.
- 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 componente se află în packages/, dar instalarea standard nu necesită instalarea lor separată.
Instalare
În proiectul Magento rulați:
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:flushDupă 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 actualizarea clasamentelor.
Validarea locală a pachetului
În repository-ul pachetului puteți rula:
./scripts/validate-local.shScriptul verifică fișierele JSON, PHP, PHTML, XML de bază, înregistrările modulelor și schemele GraphQL.
Locul configurării în panoul Magento
Configurația principală se află în:
Stores > Configuration > Kowal > Loyalty & RewardsConfigurația este în mare parte delimitată per website. Aceasta înseamnă că programul poate fi activat pentru un website și lăsat dezactivat pentru altul.
General
| Câmp | Cale config | Implicit | Semnificație |
|---|---|---|---|
| Enable Loyalty | kowal_loyalty/general/enabled | No | Activează programul de loialitate pentru website-ul selectat. Fără aceasta, modulele de domeniu nu ar trebui să gestioneze clientul ca participant al unui program activ. |
| Debug Mode | kowal_loyalty/general/debug | No | Activează diagnosticare suplimentară pentru website-ul selectat. Utilizați pe staging sau la analiza problemelor. |
| Log Retention Days | kowal_loyalty/general/log_retention_days | 30 | Perioada globală de păstrare a logurilor de loialitate în zile. |
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
| Câmp | Cale config | Implicit | Semnificație |
|---|---|---|---|
| Program ID | kowal_loyalty/program/program_id | default | Identificator intern al programului. MVP presupune un program per website. Cel mai des se lasă default. |
| Program Name | kowal_loyalty/program/name | Loyalty & Rewards | Numele programului vizibil pentru client în widgeturi, landing page și panoul contului. |
| Short Description | kowal_loyalty/program/short_description | Earn points, unlock rewards and use them on future orders. | Scurtă descriere a programului utilizată în prezentarea frontend. |
| Program Status | kowal_loyalty/program/status | draft | Statusul programului. Doar un program activ este tratat ca disponibil pentru clienți. |
| Program Visibility | kowal_loyalty/program/visibility | public | Controlează vizibilitatea programului în stratul storefront. |
| Program Terms CMS Page | kowal_loyalty/program/program_terms_cms_page | 0 | Pagina CMS cu regulamentul programului de loialitate. Linkul poate fi utilizat automat de formulare și widgeturi. |
| Store Terms CMS Page | kowal_loyalty/program/store_terms_cms_page | 0 | Pagina CMS cu regulamentul magazinului, necesară în special la înscrierea unui invitat și la crearea contului. |
Recomandare: înainte de activarea publică a programului, creați pagini CMS cu regulamentul programului și regulamentul magazinului, apoi atribuiți-le în configurație.
Points Defaults
| Câmp | Cale config | Implicit | Semnificație |
|---|---|---|---|
| Default Points Expiration Days | kowal_loyalty/points/expiration_days | 365 | Numărul de zile de valabilitate a punctelor, calculat de la data activării. |
| Default Rounding Mode | kowal_loyalty/points/rounding_mode | floor | Modul de rotunjire a punctelor: în jos, standard sau în sus. |
| Default Earning Amount Basis | kowal_loyalty/points/earning_amount_basis | base_row_total_incl_tax_after_discount | Baza valorii comenzii utilizată pentru acumularea punctelor. Livrarea este întotdeauna exclusă. |
| Earn Points After Order Status | kowal_loyalty/points/earning_order_status | complete | Statusul comenzii după care sunt acumulate punctele de achiziție. |
| Activate Pending Points After Order Status | kowal_loyalty/points/activation_order_status | complete | Statusul comenzii după care punctele în așteptare pot deveni disponibile. |
| Activation Delay Days | kowal_loyalty/points/activation_delay_days | 0 | Întârziere suplimentară pentru activarea punctelor. 0 înseamnă activare fără întârziere după îndeplinirea statusului. |
| Expiration Notification Days | kowal_loyalty/points/expiration_notification_days | 30,7,1 | Praguri de notificare înainte de expirarea punctelor, separate prin virgule. |
Opțiuni Default Earning Amount Basis:
| Valoare | Semnificație | Când se utilizează |
|---|---|---|
base_row_total_incl_tax_after_discount | Sumă brută după reduceri | Cea mai frecventă variantă B2C, clientul câștigă puncte pe baza valorii produselor plătite efectiv. |
base_row_total_incl_tax_before_discount | Sumă brută înainte de reduceri | Când promoțiile de preț nu trebuie să reducă numărul de puncte câștigate. |
base_row_total_after_discount | Sumă netă după reduceri | Pentru B2B sau magazine care decontează loialitatea pe baza valorii nete. |
base_row_total_before_discount | Sumă netă înainte de reduceri | Pentru programe calculate de la valoarea netă de catalog a produselor. |
Recomandare: pentru un magazin B2C tipic, lăsați Gross After Discounts, rounding_mode = floor, statusurile complete și valabilitatea punctelor 365 de zile.
Point Redemption
| Câmp | Cale config | Implicit | Semnificație |
|---|---|---|---|
| Points | kowal_loyalty/redemption/points | 100 | Numărul de puncte corespunzător sumei configurate a reducerii. |
| Discount Amount | kowal_loyalty/redemption/base_amount | 10 | Valoarea reducerii în moneda de bază a website-ului pentru numărul indicat de puncte. |
| Minimum Points To Redeem | kowal_loyalty/redemption/min_points | 100 | Numărul minim de puncte pe care clientul le poate utiliza în coș. |
| Minimum Order Amount | kowal_loyalty/redemption/min_order_amount | 100 | Valoarea minimă a comenzii care califică utilizarea punctelor. Livrarea este exclusă din baza de validare. |
| Maximum Order Percent Paid With Points | kowal_loyalty/redemption/max_order_percent | 30 | Procentul maxim din valoarea eligibilă a comenzii care poate fi acoperit cu puncte. |
Exemplu: valorile Points = 100 și Discount Amount = 10 înseamnă că 100 de puncte oferă 10 unități din moneda de bază ca reducere. 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 exemplu 20-30%, pentru ca programul să nu preia întreaga marjă a comenzii.
Feature Flags
| Câmp | Cale config | Implicit | Semnificație |
|---|---|---|---|
| Program | kowal_loyalty/features/program | Yes | Activează stratul programului și contextul website. |
| Rules | kowal_loyalty/features/rules | No | Activează gestionarea regulilor de acumulare a punctelor. |
| Points | kowal_loyalty/features/points | No | Activează ledgerul de puncte și proiecția soldului. |
| Rewards | kowal_loyalty/features/rewards | No | Activează mecanismele de recompense și utilizare a punctelor. |
| Checkout | kowal_loyalty/features/checkout | No | Activează integrarea cu coșul și checkoutul. |
| Content | kowal_loyalty/features/content | No | Activează stratul de content, landing pages, widgeturi și blocuri frontend. |
| Leaderboard | kowal_loyalty/features/leaderboard | No | Activează clasamentul clienților, dacă modulul este instalat. |
| Gamification | kowal_loyalty/features/gamification | No | Activează mecanicile promoționale deterministe. |
| Lottery | kowal_loyalty/features/lottery | No | Activează modulul de loterii și jocuri de noroc. |
Feature flags permit lansarea pachetului etapizat. Pentru prima configurare, de obicei activați: Program, Rules, Points, Rewards, Checkout și Content.
Leaderboard
| Câmp | Cale config | Implicit | Semnificație |
|---|---|---|---|
| Enable Leaderboard | kowal_loyalty/leaderboard/enabled | No | Activează materializarea clasamentelor prin cron. Lăsați dezactivat până la acceptarea regulilor de confidențialitate. |
| Allow Public Leaderboard Widgets | kowal_loyalty/leaderboard/public_enabled | No | Permite afișarea widgeturilor publice de clasamente. Când este dezactivat, widgeturile nu randează clasamentul public. |
| Default Metric | kowal_loyalty/leaderboard/default_metric | points | Metrica implicită a clasamentului: puncte, progresul provocărilor, recomandări sau opinii. |
| Default Widget Limit | kowal_loyalty/leaderboard/default_limit | 10 | Numărul de poziții în widgeturi. Codul limitează valoarea la maximum 100. |
Recomandare: utilizați clasamente publice doar atunci când aveți o politică de confidențialitate și o comunicare cu clientul acceptate. Modulul folosește implicit pseudonime în locul datelor personale.
Gamification
| Câmp | Cale config | Implicit | Semnificație |
|---|---|---|---|
| Enable Gamification Mechanics | kowal_loyalty/gamification/enabled | No | Activează mecanici promoționale deterministe, de exemplu Spin the Wheel și Scratch & Win. |
| Gamification feature flag | kowal_loyalty/features/gamification | No | Feature flag pentru zona de gamificare. |
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.
Loterii și jocuri de noroc
| Câmp | Cale config | Implicit | Semnificație |
|---|---|---|---|
| Enable Lottery Module | kowal_loyalty/lottery/enabled | No | Activează modulul de loterie. Lăsați dezactivat fără verificare juridică prealabilă. |
| Allow Public Lottery Widgets | kowal_loyalty/lottery/public_widgets_enabled | No | Permite randarea widgeturilor publice ale campaniilor active cu aprobare juridică. |
| Lottery feature flag | kowal_loyalty/features/lottery | No | Feature flag pentru zona de loterie. |
Recomandare: pentru promoții obișnuite utilizați Gamification. Activați Lottery doar pentru campanii care au regulament separat, aprobare juridică și un scope național conform legislației.
Reguli de puncte
Regulile de puncte sunt gestionate în panoul de administrare al modulului. Formularul lor include:
| Câmp | Semnificație |
|---|---|
| Enabled | Dacă regula este activă. |
| Program ID | Programul la care se aplică regula. În MVP, de obicei default. |
| Name | Numele regulii vizibil în administrare. |
| Description | Descriere auxiliară pentru administrator. |
| Event Type | Evenimentul pentru care sunt acumulate puncte, de exemplu cumpărare, newsletter, referral. |
| Points Mode | Modul de acumulare a punctelor, de exemplu valoare fixă sau valoare dependentă de sumă. |
| Points Value | Numărul de puncte sau rata de conversie utilizată de modul selectat. |
| Priority | Ordinea de evaluare. Regulile care se potrivesc evenimentului se cumulează; prioritatea nu oprește regulile următoare. |
| Related Landing Page Identifier | Identificatorul paginii CMS asociate regulii. |
| Website IDs | Lista ID-urilor website separate prin virgule. Câmpul gol înseamnă toate website-urile. |
| Customer Group IDs | Lista ID-urilor grupurilor de clienți separate prin virgule. Câmpul gol înseamnă toate grupurile. |
| From Date / To Date | Perioada de valabilitate a regulii. |
Exemplu de regulă simplă pentru cumpărături: Event Type = purchase, Points Mode = amount based, Points Value = 1, activă pentru toate grupurile și doar pentru website-ul selectat. Aceasta înseamnă acumularea punctelor în funcție de valoarea coșului, conform bazei din configurația Points Defaults.
Exemplu de bonus pentru newsletter: Event Type = newsletter_signup, Points Mode = fixed, Points Value = 50, perioadă fără dată de final. Regula acumulează 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:
| Câmp | Semnificație |
|---|---|
| Enabled | Dacă nivelul este activ. |
| Program ID | Programul la care se aplică nivelul. În MVP, de obicei default. |
| Name | Numele nivelului, de exemplu Silver, Gold, VIP. |
| Code | Codul tehnic al nivelului. |
| Sort Order | Ordinea nivelurilor. |
| Minimum Completed Purchase Amount | Valoarea minimă a comenzilor finalizate din ultimele 12 luni, fără livrare. |
| Minimum Completed Orders | Numărul minim de comenzi finalizate. |
| Minimum Earned Points | Numărul minim de puncte câștigate. |
| Bonus Multiplier | Multiplicatorul bonusului. 1.25 înseamnă o tranzacție bonus separată de +25% față de punctele de bază. |
| Website IDs | Lista ID-urilor website separate prin virgule. Câmpul gol înseamnă toate website-urile. |
Niveluri implicite instalate ca șabloane:
| Nivel | Prag de cumpărături | Multiplicator |
|---|---|---|
| Silver | 1000 | 1.25 |
| Gold | 3000 | 1.5 |
| VIP | 7500 | 2.0 |
Tratați valorile implicite ca punct de plecare. Înainte de producție, ajustaț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
Obiectiv: clientul colectează 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șiStore Terms CMS Pageindică 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,Contentsetate peYes.
Adăugați o regulă de puncte pentru cumpărare și testați întregul flux: enrollment, comandă, acumulare puncte, utilizarea punctelor în coș.
2. Program cu activare întârziată a punctelor
Obiectiv: 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 = 14sau30.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 de la valoarea netă
Obiectiv: acumularea punctelor din valoarea netă a produselor, fără livrare și fără taxe.
Setări:
Default Earning Amount Basis = Net After Discounts.Default Rounding Mode = floor.Minimum Order Amountsetați conform valorii minime a comenzii B2B, de exemplu500.Maximum Order Percent Paid With Pointssetați conservator, de exemplu10sau20.
Această variantă este potrivită atunci când loialitatea trebuie decontată mai aproape de marjă și de valoarea netă facturată.
4. Program VIP cu niveluri de clienți
Obiectiv: clienții mai buni câștigă puncte suplimentare.
Setări:
- Activați feature flags de bază ale programului, punctelor, regulilor și checkoutului.
- Configurați nivelurile, de exemplu Silver, Gold, VIP.
- Setați
Bonus Multiplier:1.25,1.5,2.0. - Adaptați pragurile
Minimum Completed Purchase Amountla datele de vânzări.
Bonusul nivelului este salvat ca tranzacție separată în ledger. Astfel, rapoartele pot separa punctele de bază de punctele bonus.
5. Campanie cu clasament
Obiectiv: afișarea unui clasament public al clienților în campanie.
Setări:
Leaderboard feature flag = Yes.Enable Leaderboard = Yes.Default Metric = points,challenge_progress,referralssaureviews.Default Widget Limit = 10sau altă valoare rezonabilă.Allow Public Leaderboard Widgets = Yesdoar 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
Obiectiv: campanie promoțională controlată cu recompense, fără mecanism aleatoriu.
Setări:
Gamification feature flag = Yes.Enable Gamification Mechanics = Yes.- Nu activați
Lotterydacă promoția nu este juridic o loterie. - Utilizaț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 configurația mecanicii.
Această variantă este potrivită pentru acțiuni de marketing care trebuie să arate atractiv, dar să rămână controlate bugetar și auditabile.
7. Loterie sau joc de noroc
Obiectiv: lansarea unei campanii cu un element aleatoriu real.
Setări:
Lottery feature flag = Yes.Enable Lottery Module = Yes.Allow Public Lottery Widgets = Yesdoar după pregătirea campaniei.- Campania trebuie să aibă status activ, website și country scope corespunzătoare și
legal_approval_status = approved. - Adăugați regulament CMS separat și landing page al 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 corespunzătoare.
- Statusul programului setat ca activ.
- Regulamentul programului și regulamentul magazinului atribuite paginilor CMS.
- Newsletterul descris clar ca o condiție pentru drepturile complete ale programului.
- Reguli 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 corespunzător.
- Importul corecțiilor de puncte testat din perspectiva idempotentei.
Locuri utile în panou
Stores > Configuration > Kowal > Loyalty & Rewards- configurația principală a programului.Customers > Loyalty & Rewardssau meniul administrativKowal Loyalty- participanți, ledger, corecții manuale și rapoarte, în funcție de modulele activate.- CMS Pages - regulamentele programului, regulamentul magazinului și landing pages.
- Cart Price Rules - reguli de reducere utilizate de recompensele sub formă 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 evenimentului, clientul poate primi mai multe tranzacții separate cu 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, în special atunci când magazinul folosește punctele ca reducere.