Programma fedeltà Magento 2 - Kowal Loyalty & Rewards Suite

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.9 oppure un’installazione Magento 2.4.x compatibile.
• PHP ^8.3.
• Accesso alla console del server Magento.
• Cron Magento abilitato.
• Almeno un website, store e store view configurati.
• Moduli Magento utilizzati dal pacchetto attivi, 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:

Riceverai via e-mail i dati di accesso al repository Composer, ovvero indirizzo e-mail del cliente e token di licenza, dopo l’acquisto. Sono disponibili anche nel pannello cliente dopo il login su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l’indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di 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

Dopo l’installazione verifica che cron Magento funzioni correttamente. Cron è necessario, tra l’altro, per attivare i punti in attesa, gestire la scadenza dei punti, inviare notifiche e aggiornare le classifiche.

Validazione locale del pacchetto

Nel repository del pacchetto puoi eseguire:

./scripts/validate-local.sh

Lo script verifica 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 & Rewards

La configurazione è per lo più scoped per website. Ciò significa che il programma può essere abilitato per un website e lasciato disabilitato per un altro.

General

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

Raccomandazione: prima di abilitare pubblicamente il programma, crea pagine CMS con il regolamento del programma e i termini dello store, quindi assegnale nella configurazione.

Points Defaults

Opzioni Default Earning Amount Basis:

Raccomandazione: per un tipico store B2C lascia Gross After Discounts, rounding_mode = floor, gli stati complete e la validità dei punti di 365 giorni.

Point Redemption

Esempio: i valori Points = 100 e Discount Amount = 10 significano che 100 punti danno 10 unità di valuta base di sconto. Con Maximum Order Percent Paid With Points = 30, il cliente può coprire con punti al massimo il 30% del valore qualificante 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

I feature flags consentono di avviare il pacchetto per fasi. Per la prima configurazione di solito abilita: Program, Rules, Points, Rewards, Checkout e Content.

Leaderboard

Raccomandazione: usa classifiche pubbliche solo quando hai una privacy policy e una comunicazione al cliente approvate. Il modulo utilizza di default pseudonimi al posto dei dati personali.

Gamification

Le meccaniche di gamification non sono una vera lotteria. La selezione dei premi è deterministica oppure basata su una sequenza definita, il che facilita il controllo legale e di budget.

Lotteries and Games of Chance

Raccomandazione: per le normali promozioni usa Gamification. Abilita 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 di amministrazione del modulo. Il loro form include:

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 accumulo 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 accredita un bonus una tantum dopo l’iscrizione del cliente alla newsletter, se l’integrazione newsletter richiama l’evento corretto.

Livelli cliente

I livelli sono gestiti come entità amministrative. Il form del livello include:

Livelli predefiniti installati come template:

Considera 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 Page e Store Terms CMS Page puntano alle 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, Content impostati su Yes.

Aggiungi una regola punti per l’acquisto e testa l’intero flusso: enrollment, ordine, accredito punti, uso dei punti nel carrello.

2. Programma con attivazione differita dei punti

Obiettivo: i punti diventano disponibili solo dopo il periodo di reso.

Impostazioni:

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

Questa variante riduce il rischio che il cliente spenda punti prima della conclusione del periodo di reso.

3. Programma B2B calcolato sul valore netto

Obiettivo: accumulo 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 Amount in base al valore minimo d’ordine B2B, ad esempio 500.
• Imposta Maximum Order Percent Paid With Points in modo conservativo, ad esempio 10 oppure 20.

Questa variante è utile quando la fedeltà deve essere contabilizzata più vicino al margine e al valore netto fatturato.

4. Programma VIP con livelli cliente

Obiettivo: i clienti migliori accumulano punti aggiuntivi.

Impostazioni:

• Abilita i feature flags di base del programma, dei punti, delle regole e del checkout.
• Configura i livelli, ad esempio Silver, Gold, VIP.
• Imposta Bonus Multiplier: 1.25, 1.5, 2.0.
• Adatta le soglie Minimum Completed Purchase Amount ai dati di vendita.

Il bonus di livello viene salvato come transazione separata nel ledger. Grazie a questo, i report possono separare i punti base dai punti bonus.

5. Campagna con classifica

Obiettivo: visualizzare una classifica pubblica dei clienti in una campagna.

Impostazioni:

• Leaderboard feature flag = Yes.
• Enable Leaderboard = Yes.
• Default Metric = points, challenge_progress, referrals oppure reviews.
• Default Widget Limit = 10 oppure un altro valore ragionevole.
• Allow Public Leaderboard Widgets = Yes solo 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: azione promozionale controllata con premi senza meccanismo casuale.

Impostazioni:

• Gamification feature flag = Yes.
• Enable Gamification Mechanics = Yes.
• Non abilitare Lottery se la promozione non è legalmente una lotteria.
• Usa una meccanica deterministica oppure una sequenza predefinita di premi.
• Imposta limiti di partecipazione per cliente, e-mail, budget punti e numero di vincite nella configurazione della meccanica.

Questa variante è adatta per azioni marketing che devono apparire coinvolgenti, ma restare controllate dal punto di vista del 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 = Yes solo dopo la preparazione della campagna.
• La campagna deve avere stato attivo, website e country scope corretti 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 abilitato solo per i website corretti.
• Stato del programma impostato su attivo.
• Regolamento del programma e termini dello store assegnati alle pagine CMS.
• Newsletter descritta chiaramente come condizione per i pieni diritti del programma.
• Regole punti verificate in staging.
• Limiti di utilizzo dei punti calcolati rispetto al margine.
• Resi e credit memo testati manualmente.
• Cron Magento funziona ed elabora punti in attesa, scadenze e classifiche.
• Classifiche pubbliche e lotterie approvate legalmente.
• REST API e GraphQL verificati in termini di accesso solo ai dati del cliente corretto.
• Import delle rettifiche punti testato per idempotenza.

Aree utili nel pannello

• Stores > Configuration > Kowal > Loyalty & Rewards - configurazione principale del programma.
• Customers > Loyalty & Rewards oppure menu amministrativo Kowal Loyalty - partecipanti, ledger, rettifiche manuali e report, a seconda dei moduli abilitati.
• CMS Pages - regolamenti del programma, termini dello store e landing page.
• Cart Price Rules - regole di sconto usate 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 di amministrazione. I saldi non devono essere modificati manualmente senza una transazione ledger.

Le regole punti sono cumulative. Se più regole attive corrispondono a un evento, il cliente può ricevere più transazioni punti separate. La priorità della regola controlla l’ordine e la leggibilità dell’audit, non l’interruzione delle regole successive.

I punti utilizzati nel carrello vengono salvati sulla 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 utilizza i punti come sconto.