WhatsApp
+48608012047
Kowal Product Grid Category Filter per Magento 2
12,50 € 12,50 €
Istruzioni di installazione e configurazione di Kowal Loyalty & Rewards Suite
Questo documento descrive l'installazione e la configurazione di base del pacchetto kowal/metapackage-loyalty-suite in Magento 2. Le istruzioni si basano sul codice attuale dei moduli, sulla configurazione system.xml, sui valori predefiniti config.xml e sulla documentazione del prodotto.
Requisiti
- Magento Open Source
2.4.9o installazione compatibile Magento 2.4.x. - PHP
^8.3. - Accesso alla console del server Magento.
- Cron Magento abilitato.
- Almeno un website, store e store view configurati.
- Moduli Magento attivi utilizzati dal pacchetto, tra cui Customer, Sales, Quote, Checkout, CMS, Newsletter, SalesRule, Webapi, GraphQl, UI e ImportExport.
Il pacchetto viene installato come un unico root package Composer. I moduli parziali si trovano in packages/, ma l'installazione standard non richiede di installarli separatamente.
Installazione
Nel progetto Magento esegui:
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:flushDopo l'installazione verifica che il cron Magento funzioni correttamente. Il cron è necessario, tra l'altro, per l'attivazione dei punti in attesa, la scadenza dei punti, le notifiche e l'aggiornamento delle classifiche.
Validazione locale del pacchetto
Nel repository del pacchetto puoi eseguire:
./scripts/validate-local.shLo script controlla i file JSON, PHP, PHTML, XML di base, le registrazioni dei moduli e gli schemi GraphQL.
Posizione della configurazione nel pannello Magento
La configurazione principale si trova in:
Stores > Configuration > Kowal > Loyalty & RewardsLa configurazione è per lo più definita per website. Ciò significa che il programma può essere attivato per un website e lasciato disattivato per un altro.
General
| Campo | Percorso config | Predefinito | Significato |
|---|---|---|---|
| Enable Loyalty | kowal_loyalty/general/enabled | No | Attiva il programma fedeltà per il website selezionato. Senza questa opzione, i moduli di dominio non dovrebbero gestire il cliente come partecipante a un programma attivo. |
| Debug Mode | kowal_loyalty/general/debug | No | Attiva diagnostica aggiuntiva per il website selezionato. Da utilizzare su staging o durante l'analisi di problemi. |
| Log Retention Days | kowal_loyalty/general/log_retention_days | 30 | Tempo globale di conservazione dei log loyalty in giorni. |
Raccomandazione: in produzione imposta Enable Loyalty = Yes solo per il website per cui il programma deve essere attivo. Lascia Debug Mode su No, a meno che tu non stia diagnosticando un problema specifico.
Program
| Campo | Percorso config | Predefinito | Significato |
|---|---|---|---|
| Program ID | kowal_loyalty/program/program_id | default | Identificatore interno del programma. L'MVP prevede un programma per website. Di solito lascia default. |
| Program Name | kowal_loyalty/program/name | Loyalty & Rewards | Nome del programma visibile al cliente nei widget, nella landing page e nel pannello account. |
| Short Description | kowal_loyalty/program/short_description | Earn points, unlock rewards and use them on future orders. | Breve descrizione del programma utilizzata nella presentazione frontend. |
| Program Status | kowal_loyalty/program/status | draft | Stato del programma. Solo un programma attivo viene considerato disponibile per i clienti. |
| Program Visibility | kowal_loyalty/program/visibility | public | Controlla la visibilità del programma nel livello storefront. |
| Program Terms CMS Page | kowal_loyalty/program/program_terms_cms_page | 0 | Pagina CMS con il regolamento del programma fedeltà. Il link può essere usato automaticamente da form e widget. |
| Store Terms CMS Page | kowal_loyalty/program/store_terms_cms_page | 0 | Pagina CMS con il regolamento dello store, richiesta soprattutto per la registrazione ospite e la creazione dell'account. |
Raccomandazione: prima di rendere pubblico il programma, crea le pagine CMS con il regolamento del programma e il regolamento dello store, quindi assegnale nella configurazione.
Points Defaults
| Campo | Percorso config | Predefinito | Significato |
|---|---|---|---|
| Default Points Expiration Days | kowal_loyalty/points/expiration_days | 365 | Numero di giorni di validità dei punti calcolato dalla data di attivazione. |
| Default Rounding Mode | kowal_loyalty/points/rounding_mode | floor | Metodo di arrotondamento dei punti: per difetto, standard o per eccesso. |
| Default Earning Amount Basis | kowal_loyalty/points/earning_amount_basis | base_row_total_incl_tax_after_discount | Base del valore dell'ordine utilizzata per l'assegnazione dei punti. La spedizione è sempre esclusa. |
| Earn Points After Order Status | kowal_loyalty/points/earning_order_status | complete | Stato dell'ordine dopo il quale vengono assegnati i punti acquisto. |
| Activate Pending Points After Order Status | kowal_loyalty/points/activation_order_status | complete | Stato dell'ordine dopo il quale i punti in attesa possono diventare disponibili. |
| Activation Delay Days | kowal_loyalty/points/activation_delay_days | 0 | Ritardo aggiuntivo nell'attivazione dei punti. 0 indica attivazione senza ritardo dopo il soddisfacimento dello stato. |
| Expiration Notification Days | kowal_loyalty/points/expiration_notification_days | 30,7,1 | Soglie di notifica prima della scadenza dei punti, separate da virgole. |
Opzioni Default Earning Amount Basis:
| Valore | Significato | Quando usarlo |
|---|---|---|
base_row_total_incl_tax_after_discount | Importo lordo dopo gli sconti | Variante B2C più comune, il cliente guadagna punti sul valore dei prodotti effettivamente pagato. |
base_row_total_incl_tax_before_discount | Importo lordo prima degli sconti | Quando le promozioni di prezzo non devono ridurre il numero di punti guadagnati. |
base_row_total_after_discount | Importo netto dopo gli sconti | Per B2B o store che contabilizzano la loyalty sul valore netto. |
base_row_total_before_discount | Importo netto prima degli sconti | Per programmi calcolati sul valore netto di catalogo dei prodotti. |
Raccomandazione: per un tipico store B2C lascia Gross After Discounts, rounding_mode = floor, stati complete e validità dei punti di 365 giorni.
Point Redemption
| Campo | Percorso config | Predefinito | Significato |
|---|---|---|---|
| Points | kowal_loyalty/redemption/points | 100 | Numero di punti corrispondente all'importo di sconto configurato. |
| Discount Amount | kowal_loyalty/redemption/base_amount | 10 | Importo dello sconto nella valuta base del website per il numero di punti indicato. |
| Minimum Points To Redeem | kowal_loyalty/redemption/min_points | 100 | Numero minimo di punti che il cliente può utilizzare nel carrello. |
| Minimum Order Amount | kowal_loyalty/redemption/min_order_amount | 100 | Valore minimo dell'ordine che qualifica l'utilizzo dei punti. La spedizione è esclusa dalla base di validazione. |
| Maximum Order Percent Paid With Points | kowal_loyalty/redemption/max_order_percent | 30 | Percentuale massima del valore qualificato dell'ordine che può essere coperta con i punti. |
Esempio: i valori Points = 100 e Discount Amount = 10 significano che 100 punti danno 10 unità della valuta base di sconto. Con Maximum Order Percent Paid With Points = 30 il cliente può coprire con i punti al massimo il 30% del valore qualificato del carrello.
Raccomandazione: all'inizio imposta un limite conservativo, ad esempio 20-30%, affinché il programma non assorba tutto il margine dell'ordine.
Feature Flags
| Campo | Percorso config | Predefinito | Significato |
|---|---|---|---|
| Program | kowal_loyalty/features/program | Yes | Attiva il livello del programma e del contesto website. |
| Rules | kowal_loyalty/features/rules | No | Attiva il supporto delle regole di assegnazione dei punti. |
| Points | kowal_loyalty/features/points | No | Attiva il ledger dei punti e la proiezione del saldo. |
| Rewards | kowal_loyalty/features/rewards | No | Attiva i meccanismi di premi e utilizzo dei punti. |
| Checkout | kowal_loyalty/features/checkout | No | Attiva l'integrazione con carrello e checkout. |
| Content | kowal_loyalty/features/content | No | Attiva il livello content, landing pages, widget e blocchi frontend. |
| Leaderboard | kowal_loyalty/features/leaderboard | No | Attiva la classifica clienti, se il modulo è installato. |
| Gamification | kowal_loyalty/features/gamification | No | Attiva meccaniche promozionali deterministiche. |
| Lottery | kowal_loyalty/features/lottery | No | Attiva il modulo lotterie e giochi a sorte. |
Le feature flags consentono di avviare il pacchetto gradualmente. Per la prima configurazione di solito attiva: Program, Rules, Points, Rewards, Checkout e Content.
Leaderboard
| Campo | Percorso config | Predefinito | Significato |
|---|---|---|---|
| Enable Leaderboard | kowal_loyalty/leaderboard/enabled | No | Attiva la materializzazione delle classifiche tramite cron. Lascia disattivato fino all'accettazione delle regole sulla privacy. |
| Allow Public Leaderboard Widgets | kowal_loyalty/leaderboard/public_enabled | No | Consente di mostrare widget pubblici delle classifiche. Quando disattivato, i widget non renderizzano la classifica pubblica. |
| Default Metric | kowal_loyalty/leaderboard/default_metric | points | Metrica predefinita della classifica: punti, avanzamento sfide, referral oppure recensioni. |
| Default Widget Limit | kowal_loyalty/leaderboard/default_limit | 10 | Numero di posizioni nei widget. Il codice limita il valore a un massimo di 100. |
Raccomandazione: usa classifiche pubbliche solo quando hai una privacy policy e una comunicazione al cliente approvate. Il modulo utilizza per impostazione predefinita pseudonimi invece di dati personali.
Gamification
| Campo | Percorso config | Predefinito | Significato |
|---|---|---|---|
| Enable Gamification Mechanics | kowal_loyalty/gamification/enabled | No | Attiva meccaniche promozionali deterministiche, ad esempio Spin the Wheel e Scratch & Win. |
| Gamification feature flag | kowal_loyalty/features/gamification | No | Feature flag per l'area gamification. |
Le meccaniche di gamification non sono una vera lotteria. La scelta dei premi è deterministica oppure basata su una sequenza definita, facilitando il controllo legale e di budget.
Lotterie e giochi a sorte
| Campo | Percorso config | Predefinito | Significato |
|---|---|---|---|
| Enable Lottery Module | kowal_loyalty/lottery/enabled | No | Attiva il modulo lotterie. Lascia disattivato senza una precedente verifica legale. |
| Allow Public Lottery Widgets | kowal_loyalty/lottery/public_widgets_enabled | No | Consente di renderizzare widget pubblici di campagne attive con approvazione legale. |
| Lottery feature flag | kowal_loyalty/features/lottery | No | Feature flag per l'area lotterie. |
Raccomandazione: per le promozioni ordinarie usa Gamification. Attiva Lottery solo per campagne che hanno un regolamento separato, approvazione legale e ambito nazionale conforme alle normative.
Regole punti
Le regole punti sono gestite nel pannello amministrativo del modulo. Il loro form include:
| Campo | Significato |
|---|---|
| Enabled | Indica se la regola è attiva. |
| Program ID | Programma a cui si riferisce la regola. Nell'MVP di solito default. |
| Name | Nome della regola visibile in amministrazione. |
| Description | Descrizione di supporto per l'amministratore. |
| Event Type | Evento per cui vengono assegnati i punti, ad esempio acquisto, newsletter, referral. |
| Points Mode | Metodo di assegnazione dei punti, ad esempio valore fisso o valore dipendente dall'importo. |
| Points Value | Numero di punti o tasso di conversione utilizzato dalla modalità selezionata. |
| Priority | Ordine di valutazione. Le regole corrispondenti all'evento si sommano; la priorità non arresta le regole successive. |
| Related Landing Page Identifier | Identificatore della pagina CMS collegata alla regola. |
| Website IDs | Elenco di ID website separati da virgole. Un campo vuoto indica tutti i website. |
| Customer Group IDs | Elenco di ID dei gruppi cliente separati da virgole. Un campo vuoto indica tutti i gruppi. |
| From Date / To Date | Periodo di validità della regola. |
Esempio di semplice regola di acquisto: Event Type = purchase, Points Mode = amount based, Points Value = 1, attiva per tutti i gruppi e solo per il website selezionato. Ciò significa l'assegnazione di punti in base al valore del carrello secondo la base della configurazione Points Defaults.
Esempio di bonus newsletter: Event Type = newsletter_signup, Points Mode = fixed, Points Value = 50, periodo senza data di fine. La regola assegna un bonus una tantum dopo l'iscrizione del cliente alla newsletter, se l'integrazione newsletter richiama l'evento appropriato.
Livelli cliente
I livelli sono gestiti come entità amministrative. Il form del livello include:
| Campo | Significato |
|---|---|
| Enabled | Indica se il livello è attivo. |
| Program ID | Programma a cui si riferisce il livello. Nell'MVP di solito default. |
| Name | Nome del livello, ad esempio Silver, Gold, VIP. |
| Code | Codice tecnico del livello. |
| Sort Order | Ordine dei livelli. |
| Minimum Completed Purchase Amount | Valore minimo degli ordini completati negli ultimi 12 mesi, senza spedizione. |
| Minimum Completed Orders | Numero minimo di ordini completati. |
| Minimum Earned Points | Numero minimo di punti guadagnati. |
| Bonus Multiplier | Moltiplicatore del bonus. 1.25 indica una transazione bonus separata +25% rispetto ai punti base. |
| Website IDs | Elenco di ID website separati da virgole. Un campo vuoto indica tutti i website. |
Livelli predefiniti installati come template:
| Livello | Soglia acquisti | Moltiplicatore |
|---|---|---|
| Silver | 1000 | 1.25 |
| Gold | 3000 | 1.5 |
| VIP | 7500 | 2.0 |
Tratta i valori predefiniti come punto di partenza. Prima della produzione, adatta le soglie al valore medio dell'ordine, al margine e alla frequenza degli acquisti.
Esempi di configurazione
1. Programma punti semplice per uno store B2C
Obiettivo: il cliente raccoglie punti per gli acquisti e può spenderli nel carrello.
Impostazioni:
Enable Loyalty = Yes.Program Status = active.Program Visibility = public.Program Terms CMS PageeStore Terms CMS Pageindicano pagine CMS corrette.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,Contentimpostate suYes.
Aggiungi una regola punti per l'acquisto e testa l'intero flusso: enrollment, ordine, assegnazione dei punti, utilizzo dei punti nel carrello.
2. Programma con attivazione ritardata dei punti
Obiettivo: i punti diventano disponibili solo dopo il periodo per il reso.
Impostazioni:
Earn Points After Order Status = complete.Activate Pending Points After Order Status = complete.Activation Delay Days = 14oppure30.Default Points Expiration Days = 365.Expiration Notification Days = 30,7,1.
Questa variante riduce il rischio che il cliente spenda punti prima della fine del periodo di reso.
3. Programma B2B calcolato sul valore netto
Obiettivo: assegnazione dei punti sul valore netto dei prodotti, senza spedizione e senza imposte.
Impostazioni:
Default Earning Amount Basis = Net After Discounts.Default Rounding Mode = floor.- Imposta
Minimum Order Amountin base al valore minimo dell'ordine B2B, ad esempio500. - Imposta
Maximum Order Percent Paid With Pointsin modo conservativo, ad esempio10oppure20.
Questa variante è sensata quando la loyalty deve essere contabilizzata più vicino al margine e al valore netto fatturato.
4. Programma VIP con livelli cliente
Obiettivo: i clienti migliori guadagnano punti aggiuntivi.
Impostazioni:
- Attiva le feature flags di base per programma, punti, regole e checkout.
- Configura i livelli, ad esempio Silver, Gold, VIP.
- Imposta
Bonus Multiplier:1.25,1.5,2.0. - Adatta le soglie
Minimum Completed Purchase Amountai dati di vendita.
Il bonus di livello viene registrato come transazione separata nel ledger. In questo modo i report possono separare i punti base dai punti bonus.
5. Campagna con classifica
Obiettivo: visualizzare una classifica pubblica dei clienti nella campagna.
Impostazioni:
Leaderboard feature flag = Yes.Enable Leaderboard = Yes.Default Metric = points,challenge_progress,referralsoppurereviews.Default Widget Limit = 10oppure un altro valore ragionevole.Allow Public Leaderboard Widgets = Yessolo dopo l'accettazione delle regole sulla privacy.
Prima della pubblicazione verifica il contenuto del regolamento, la privacy policy e il modo in cui vengono presentati gli alias dei clienti.
6. Promozione Spin the Wheel senza lotteria
Obiettivo: campagna promozionale controllata con premi senza meccanismo casuale.
Impostazioni:
Gamification feature flag = Yes.Enable Gamification Mechanics = Yes.- Non attivare
Lotteryse la promozione non è legalmente una lotteria. - Usa una meccanica deterministica o una sequenza di premi predefinita.
- Imposta limiti di partecipazione del cliente, e-mail, budget punti e numero di vincite nella configurazione della meccanica.
Questa variante è adatta ad attività marketing che devono risultare attraenti, ma restare controllate a livello di budget e auditabili.
7. Lotteria o gioco a sorte
Obiettivo: avviare una campagna con un reale elemento casuale.
Impostazioni:
Lottery feature flag = Yes.Enable Lottery Module = Yes.Allow Public Lottery Widgets = Yessolo dopo la preparazione della campagna.- La campagna deve avere stato attivo, website e country scope appropriati e
legal_approval_status = approved. - Aggiungi un regolamento CMS separato e una landing page della campagna.
Non usare questa variante senza verifica legale per il Paese in cui opera lo store.
Checklist prima della produzione
- Programma attivato solo per i website corretti.
- Stato del programma impostato su attivo.
- Regolamento del programma e regolamento dello store assegnati a pagine CMS.
- Newsletter descritta chiaramente come condizione per i pieni diritti del programma.
- Regole punti verificate su staging.
- Limiti di utilizzo dei punti calcolati rispetto al margine.
- Resi e credit memo testati manualmente.
- Cron Magento funzionante e in grado di elaborare punti in attesa, scadenze e classifiche.
- Classifiche pubbliche e lotterie approvate legalmente.
- REST API e GraphQL verificati per l'accesso solo ai dati del cliente corretto.
- Import delle correzioni punti testato in termini di idempotenza.
Aree utili nel pannello
Stores > Configuration > Kowal > Loyalty & Rewards- configurazione principale del programma.Customers > Loyalty & Rewardsoppure menu amministrativoKowal Loyalty- partecipanti, ledger, correzioni manuali e report, a seconda dei moduli attivati.- CMS Pages - regolamenti del programma, regolamento dello store e landing pages.
- Cart Price Rules - regole di sconto utilizzate dai premi coupon.
Note operative
Il ledger dei punti è la fonte di verità. La tabella dei saldi è una proiezione per letture rapide nel frontend, nel checkout e nel pannello amministrativo. I saldi non devono essere modificati manualmente senza una transazione nel ledger.
Le regole punti sono cumulative. Se più regole attive corrispondono all'evento, il cliente può ricevere più transazioni punti separate. La priorità della regola controlla l'ordine e la leggibilità dell'audit, non l'arresto delle regole successive.
I punti utilizzati nel carrello vengono salvati sul quote, trasferiti all'order e contabilizzati dopo l'invio dell'ordine. Resi e credit memo devono essere testati per resi completi e parziali, soprattutto quando lo store usa i punti come sconto.