WhatsApp
+48608012047
Kowal Product Grid Category Filter voor Magento 2
€ 12,50 € 12,50
Installatie- en configuratiehandleiding voor Kowal Loyalty & Rewards Suite
Dit document beschrijft de installatie en basisconfiguratie van het pakket kowal/metapackage-loyalty-suite in Magento 2. De handleiding is gebaseerd op de actuele code van de modules, de configuratie system.xml, standaardwaarden config.xml en de productdocumentatie.
Vereisten
- Magento Open Source
2.4.9of een compatibele Magento 2.4.x-installatie. - PHP
^8.3. - Toegang tot de console van de Magento-server.
- Ingeschakelde Magento-cron.
- Minimaal één geconfigureerde website, store en store view.
- Actieve Magento-modules die door het pakket worden gebruikt, waaronder Customer, Sales, Quote, Checkout, CMS, Newsletter, SalesRule, Webapi, GraphQl, UI en ImportExport.
Het pakket wordt geïnstalleerd als één root package Composer. De deelmodules bevinden zich in packages/, maar voor een standaardinstallatie hoeven ze niet afzonderlijk te worden geïnstalleerd.
Installatie
Voer in het Magento-project uit:
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:flushControleer na de installatie of Magento-cron correct werkt. Cron is onder andere nodig voor het activeren van wachtende punten, het laten vervallen van punten, meldingen en het vernieuwen van ranglijsten.
Lokale validatie van het pakket
In de repository van het pakket kunt u uitvoeren:
./scripts/validate-local.shHet script controleert basisbestanden JSON, PHP, PHTML, XML, module-registraties en GraphQL-schema's.
Configuratielocatie in het Magento-paneel
De hoofdconfiguratie bevindt zich in:
Stores > Configuration > Kowal > Loyalty & RewardsDe configuratie is grotendeels per website gescoped. Dit betekent dat het programma voor één website kan worden ingeschakeld en voor een andere uitgeschakeld kan blijven.
General
| Veld | Config-pad | Standaard | Betekenis |
|---|---|---|---|
| Enable Loyalty | kowal_loyalty/general/enabled | No | Schakelt het loyaliteitsprogramma in voor de geselecteerde website. Zonder dit zouden domeinmodules de klant niet als deelnemer aan een actief programma moeten verwerken. |
| Debug Mode | kowal_loyalty/general/debug | No | Schakelt extra diagnostiek in voor de geselecteerde website. Gebruik dit op staging of bij het analyseren van problemen. |
| Log Retention Days | kowal_loyalty/general/log_retention_days | 30 | Globale bewaartermijn voor loyaliteitslogs in dagen. |
Aanbeveling: stel in productie Enable Loyalty = Yes alleen in voor de website waarvoor het programma actief moet zijn. Laat Debug Mode op No, tenzij u een specifiek probleem diagnosticeert.
Program
| Veld | Config-pad | Standaard | Betekenis |
|---|---|---|---|
| Program ID | kowal_loyalty/program/program_id | default | Interne programma-ID. De MVP gaat uit van één programma per website. Laat meestal default staan. |
| Program Name | kowal_loyalty/program/name | Loyalty & Rewards | Naam van het programma die zichtbaar is voor de klant in widgets, landing page en accountpaneel. |
| Short Description | kowal_loyalty/program/short_description | Earn points, unlock rewards and use them on future orders. | Korte beschrijving van het programma die wordt gebruikt in de frontendpresentatie. |
| Program Status | kowal_loyalty/program/status | draft | Status van het programma. Alleen een actief programma wordt als beschikbaar voor klanten beschouwd. |
| Program Visibility | kowal_loyalty/program/visibility | public | Beheert de zichtbaarheid van het programma in de storefront-laag. |
| Program Terms CMS Page | kowal_loyalty/program/program_terms_cms_page | 0 | CMS-pagina met de voorwaarden van het loyaliteitsprogramma. De link kan automatisch door formulieren en widgets worden gebruikt. |
| Store Terms CMS Page | kowal_loyalty/program/store_terms_cms_page | 0 | CMS-pagina met de winkelvoorwaarden, vooral vereist bij gastregistratie en het aanmaken van een account. |
Aanbeveling: maak voordat u het programma openbaar inschakelt CMS-pagina's aan met de programmavoorwaarden en winkelvoorwaarden en wijs deze vervolgens toe in de configuratie.
Points Defaults
| Veld | Config-pad | Standaard | Betekenis |
|---|---|---|---|
| Default Points Expiration Days | kowal_loyalty/points/expiration_days | 365 | Aantal dagen geldigheid van punten, gerekend vanaf de activeringsdatum. |
| Default Rounding Mode | kowal_loyalty/points/rounding_mode | floor | Manier van afronden van punten: naar beneden, standaard of naar boven. |
| Default Earning Amount Basis | kowal_loyalty/points/earning_amount_basis | base_row_total_incl_tax_after_discount | Basis van de bestelwaarde die wordt gebruikt voor het toekennen van punten. Verzending is altijd uitgesloten. |
| Earn Points After Order Status | kowal_loyalty/points/earning_order_status | complete | Bestelstatus waarna aankooppunten worden toegekend. |
| Activate Pending Points After Order Status | kowal_loyalty/points/activation_order_status | complete | Bestelstatus waarna wachtende punten beschikbaar kunnen worden. |
| Activation Delay Days | kowal_loyalty/points/activation_delay_days | 0 | Extra vertraging voor activering van punten. 0 betekent activering zonder vertraging nadat aan de status is voldaan. |
| Expiration Notification Days | kowal_loyalty/points/expiration_notification_days | 30,7,1 | Meldingsdrempels vóór het vervallen van punten, gescheiden door komma's. |
Opties voor Default Earning Amount Basis:
| Waarde | Betekenis | Wanneer gebruiken |
|---|---|---|
base_row_total_incl_tax_after_discount | Brutobedrag na kortingen | Meest voorkomende B2C-variant; de klant verdient punten over de daadwerkelijk betaalde productwaarde. |
base_row_total_incl_tax_before_discount | Brutobedrag vóór kortingen | Wanneer prijsacties het aantal verdiende punten niet mogen verminderen. |
base_row_total_after_discount | Nettobedrag na kortingen | Voor B2B of winkels die loyaliteit afrekenen op nettowaarde. |
base_row_total_before_discount | Nettobedrag vóór kortingen | Voor programma's die worden berekend over de catalogusnettowaarde van producten. |
Aanbeveling: laat voor een typische B2C-winkel Gross After Discounts, rounding_mode = floor, statussen complete en puntengeldigheid van 365 dagen staan.
Point Redemption
| Veld | Config-pad | Standaard | Betekenis |
|---|---|---|---|
| Points | kowal_loyalty/redemption/points | 100 | Aantal punten dat overeenkomt met het geconfigureerde kortingsbedrag. |
| Discount Amount | kowal_loyalty/redemption/base_amount | 10 | Kortingsbedrag in de basisvaluta van de website voor het aangegeven aantal punten. |
| Minimum Points To Redeem | kowal_loyalty/redemption/min_points | 100 | Minimumaantal punten dat de klant in de winkelwagen kan gebruiken. |
| Minimum Order Amount | kowal_loyalty/redemption/min_order_amount | 100 | Minimale bestelwaarde die het gebruik van punten kwalificeert. Verzending is uitgesloten van de validatiebasis. |
| Maximum Order Percent Paid With Points | kowal_loyalty/redemption/max_order_percent | 30 | Maximaal percentage van de gekwalificeerde bestelwaarde dat met punten kan worden gedekt. |
Voorbeeld: de waarden Points = 100 en Discount Amount = 10 betekenen dat 100 punten 10 eenheden van de basisvaluta aan korting geven. Bij Maximum Order Percent Paid With Points = 30 kan de klant maximaal 30% van de gekwalificeerde winkelwagenwaarde met punten dekken.
Aanbeveling: stel in het begin een conservatieve limiet in, bijvoorbeeld 20-30%, zodat het programma niet de volledige marge van de bestelling overneemt.
Feature Flags
| Veld | Config-pad | Standaard | Betekenis |
|---|---|---|---|
| Program | kowal_loyalty/features/program | Yes | Schakelt de programma- en websitecontextlaag in. |
| Rules | kowal_loyalty/features/rules | No | Schakelt ondersteuning voor puntenregels in. |
| Points | kowal_loyalty/features/points | No | Schakelt de puntenledger en saldoprojectie in. |
| Rewards | kowal_loyalty/features/rewards | No | Schakelt mechanismen voor beloningen en puntengebruik in. |
| Checkout | kowal_loyalty/features/checkout | No | Schakelt integratie met winkelwagen en checkout in. |
| Content | kowal_loyalty/features/content | No | Schakelt de contentlaag, landing pages, widgets en frontendblokken in. |
| Leaderboard | kowal_loyalty/features/leaderboard | No | Schakelt de klantenranglijst in als de module is geïnstalleerd. |
| Gamification | kowal_loyalty/features/gamification | No | Schakelt deterministische promotiemechanismen in. |
| Lottery | kowal_loyalty/features/lottery | No | Schakelt de module voor loterijen en kansspelen in. |
Feature flags maken het mogelijk het pakket gefaseerd te starten. Voor de eerste configuratie schakelt u doorgaans Program, Rules, Points, Rewards, Checkout en Content in.
Leaderboard
| Veld | Config-pad | Standaard | Betekenis |
|---|---|---|---|
| Enable Leaderboard | kowal_loyalty/leaderboard/enabled | No | Schakelt materialisatie van ranglijsten via cron in. Laat uitgeschakeld totdat de privacyregels zijn geaccepteerd. |
| Allow Public Leaderboard Widgets | kowal_loyalty/leaderboard/public_enabled | No | Maakt het mogelijk openbare ranglijstwidgets weer te geven. Als dit is uitgeschakeld, renderen widgets geen openbare ranglijst. |
| Default Metric | kowal_loyalty/leaderboard/default_metric | points | Standaardmetriek van de ranglijst: punten, voortgang van challenges, referrals of reviews. |
| Default Widget Limit | kowal_loyalty/leaderboard/default_limit | 10 | Aantal posities in widgets. De code beperkt de waarde tot maximaal 100. |
Aanbeveling: gebruik openbare ranglijsten alleen wanneer u een geaccepteerd privacybeleid en klantcommunicatie heeft. De module gebruikt standaard pseudoniemen in plaats van persoonsgegevens.
Gamification
| Veld | Config-pad | Standaard | Betekenis |
|---|---|---|---|
| Enable Gamification Mechanics | kowal_loyalty/gamification/enabled | No | Schakelt deterministische promotiemechanismen in, bijvoorbeeld Spin the Wheel en Scratch & Win. |
| Gamification feature flag | kowal_loyalty/features/gamification | No | Feature flag voor het gamification-gebied. |
Gamification-mechanismen zijn geen echte loterij. De keuze van beloningen is deterministisch of gebaseerd op een gedefinieerde reeks, wat juridische en budgettaire controle eenvoudiger maakt.
Loterijen en kansspelen
| Veld | Config-pad | Standaard | Betekenis |
|---|---|---|---|
| Enable Lottery Module | kowal_loyalty/lottery/enabled | No | Schakelt de loterijmodule in. Laat uitgeschakeld zonder voorafgaande juridische verificatie. |
| Allow Public Lottery Widgets | kowal_loyalty/lottery/public_widgets_enabled | No | Maakt het mogelijk openbare widgets van actieve campagnes met juridische goedkeuring te renderen. |
| Lottery feature flag | kowal_loyalty/features/lottery | No | Feature flag voor het loterijgebied. |
Aanbeveling: gebruik voor gewone promoties Gamification. Schakel Lottery alleen in voor campagnes met aparte voorwaarden, juridische goedkeuring en een landelijk bereik dat aan de regelgeving voldoet.
Puntenregels
Puntenregels worden beheerd in het adminpaneel van de module. Het formulier bevat:
| Veld | Betekenis |
|---|---|
| Enabled | Of de regel actief is. |
| Program ID | Programma waarop de regel betrekking heeft. In de MVP meestal default. |
| Name | Naam van de regel zichtbaar in de administratie. |
| Description | Ondersteunende beschrijving voor de beheerder. |
| Event Type | Event waarvoor punten worden toegekend, bijvoorbeeld aankoop, nieuwsbrief, referral. |
| Points Mode | Manier van punten toekennen, bijvoorbeeld vaste waarde of waarde afhankelijk van het bedrag. |
| Points Value | Aantal punten of omrekenfactor die door de gekozen modus wordt gebruikt. |
| Priority | Volgorde van evaluatie. Regels die bij het event passen worden opgeteld; prioriteit stopt volgende regels niet. |
| Related Landing Page Identifier | Identifier van de CMS-pagina die aan de regel is gekoppeld. |
| Website IDs | Lijst met website-ID's, gescheiden door komma's. Een leeg veld betekent alle websites. |
| Customer Group IDs | Lijst met klantgroep-ID's, gescheiden door komma's. Een leeg veld betekent alle groepen. |
| From Date / To Date | Geldigheidsperiode van de regel. |
Voorbeeld van een eenvoudige aankoopregel: Event Type = purchase, Points Mode = amount based, Points Value = 1, actief voor alle groepen en alleen voor de geselecteerde website. Dit betekent puntentoekenning op basis van de winkelwagenwaarde volgens de basis uit de configuratie Points Defaults.
Voorbeeld van een nieuwsbriefbonus: Event Type = newsletter_signup, Points Mode = fixed, Points Value = 50, periode zonder einddatum. De regel kent een eenmalige bonus toe na inschrijving van de klant op de nieuwsbrief, als de nieuwsbriefintegratie het juiste event aanroept.
Klantniveaus
Niveaus worden beheerd als administratieve entiteiten. Het niveauformulier bevat:
| Veld | Betekenis |
|---|---|
| Enabled | Of het niveau actief is. |
| Program ID | Programma waarop het niveau betrekking heeft. In de MVP meestal default. |
| Name | Naam van het niveau, bijvoorbeeld Silver, Gold, VIP. |
| Code | Technische code van het niveau. |
| Sort Order | Volgorde van de niveaus. |
| Minimum Completed Purchase Amount | Minimale waarde van voltooide bestellingen uit de laatste 12 maanden, zonder verzending. |
| Minimum Completed Orders | Minimumaantal voltooide bestellingen. |
| Minimum Earned Points | Minimumaantal verdiende punten. |
| Bonus Multiplier | Bonusvermenigvuldiger. 1.25 betekent een aparte bonustransactie van +25% ten opzichte van de basispunten. |
| Website IDs | Lijst met website-ID's, gescheiden door komma's. Een leeg veld betekent alle websites. |
Standaardniveaus die als templates worden geïnstalleerd:
| Niveau | Aankoopdrempel | Vermenigvuldiger |
|---|---|---|
| Silver | 1000 | 1.25 |
| Gold | 3000 | 1.5 |
| VIP | 7500 | 2.0 |
Behandel de standaardwaarden als startpunt. Stem vóór productie de drempels af op de gemiddelde bestelwaarde, marge en aankoopfrequentie.
Configuratievoorbeelden
1. Eenvoudig puntenprogramma voor een B2C-winkel
Doel: de klant verzamelt punten voor aankopen en kan ze in de winkelwagen besteden.
Instellingen:
Enable Loyalty = Yes.Program Status = active.Program Visibility = public.Program Terms CMS PageenStore Terms CMS Pageverwijzen naar correcte CMS-pagina's.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,Contentingesteld opYes.
Voeg een puntenregel voor aankopen toe en test de volledige flow: enrollment, bestelling, puntentoekenning, gebruik van punten in de winkelwagen.
2. Programma met vertraagde puntactivering
Doel: punten worden pas beschikbaar na de retourtermijn.
Instellingen:
Earn Points After Order Status = complete.Activate Pending Points After Order Status = complete.Activation Delay Days = 14of30.Default Points Expiration Days = 365.Expiration Notification Days = 30,7,1.
Deze variant beperkt het risico dat de klant punten uitgeeft voordat de retourperiode is afgerond.
3. B2B-programma berekend op nettowaarde
Doel: punten toekennen op basis van de nettowaarde van producten, zonder verzending en zonder belasting.
Instellingen:
Default Earning Amount Basis = Net After Discounts.Default Rounding Mode = floor.- Stel
Minimum Order Amountin volgens de minimale B2B-bestelwaarde, bijvoorbeeld500. - Stel
Maximum Order Percent Paid With Pointsconservatief in, bijvoorbeeld10of20.
Deze variant is zinvol wanneer loyaliteit dichter bij de marge en de gefactureerde nettowaarde moet worden afgerekend.
4. VIP-programma met klantniveaus
Doel: betere klanten verdienen extra punten.
Instellingen:
- Schakel de basis feature flags in voor programma, punten, regels en checkout.
- Configureer niveaus, bijvoorbeeld Silver, Gold, VIP.
- Stel
Bonus Multiplierin:1.25,1.5,2.0. - Stem de drempels
Minimum Completed Purchase Amountaf op verkoopgegevens.
De niveaubonus wordt als aparte transactie in de ledger opgeslagen. Daardoor kunnen rapportages basispunten scheiden van bonuspunten.
5. Campagne met ranglijst
Doel: een openbare klantenranglijst in een campagne weergeven.
Instellingen:
Leaderboard feature flag = Yes.Enable Leaderboard = Yes.Default Metric = points,challenge_progress,referralsofreviews.Default Widget Limit = 10of een andere redelijke waarde.Allow Public Leaderboard Widgets = Yespas na acceptatie van de privacyregels.
Controleer vóór publicatie de inhoud van de voorwaarden, het privacybeleid en de manier waarop klantaliassen worden gepresenteerd.
6. Spin the Wheel-promotie zonder loterij
Doel: een gecontroleerde promotieactie met beloningen zonder kansmechanisme.
Instellingen:
Gamification feature flag = Yes.Enable Gamification Mechanics = Yes.- Schakel
Lotteryniet in als de promotie juridisch geen loterij is. - Gebruik een deterministisch mechanisme of een vooraf gedefinieerde beloningsreeks.
- Stel limieten in voor deelname van klant, e-mail, puntenbudget en aantal winsten in de configuratie van het mechanisme.
Deze variant is geschikt voor marketingacties die er aantrekkelijk uit moeten zien, maar budgettair gecontroleerd en auditeerbaar moeten blijven.
7. Loterij of kansspel
Doel: een campagne met een echt kanselement starten.
Instellingen:
Lottery feature flag = Yes.Enable Lottery Module = Yes.Allow Public Lottery Widgets = Yespas na voorbereiding van de campagne.- De campagne moet een actieve status, de juiste website en country scope hebben en
legal_approval_status = approved. - Voeg aparte CMS-voorwaarden en een landing page voor de campagne toe.
Gebruik deze variant niet zonder juridische verificatie voor het land waarin de winkel actief is.
Checklist vóór productie
- Programma alleen ingeschakeld voor de juiste websites.
- Programmastatus ingesteld op actief.
- Programmavoorwaarden en winkelvoorwaarden toegewezen aan CMS-pagina's.
- Nieuwsbrief duidelijk beschreven als voorwaarde voor volledige programmarechten.
- Puntenregels gecontroleerd op staging.
- Limieten voor puntengebruik berekend ten opzichte van de marge.
- Retouren en credit memo's handmatig getest.
- Magento-cron werkt en verwerkt wachtende punten, verval en ranglijsten.
- Openbare ranglijsten en loterijen juridisch goedgekeurd.
- REST API en GraphQL gecontroleerd op toegang tot alleen de gegevens van de juiste klant.
- Import van puntcorrecties getest op idempotentie.
Nuttige locaties in het paneel
Stores > Configuration > Kowal > Loyalty & Rewards- hoofdconfiguratie van het programma.Customers > Loyalty & Rewardsof het administratiemenuKowal Loyalty- deelnemers, ledger, handmatige correcties en rapportages, afhankelijk van de ingeschakelde modules.- CMS Pages - programmavoorwaarden, winkelvoorwaarden en landing pages.
- Cart Price Rules - kortingsregels die door couponbeloningen worden gebruikt.
Operationele opmerkingen
De puntenledger is de bron van waarheid. De saldotabel is een projectie voor snelle uitlezingen in de frontend, checkout en het adminpaneel. Saldi mogen niet handmatig worden bewerkt zonder ledgertransactie.
Puntenregels zijn cumulatief. Als meerdere actieve regels bij een event passen, kan de klant meerdere aparte puntentransacties ontvangen. De prioriteit van de regel bepaalt de volgorde en leesbaarheid van de audit, niet het stoppen van verdere regels.
Punten die in de winkelwagen worden gebruikt, worden op de quote opgeslagen, naar de order overgedragen en na het plaatsen van de bestelling verrekend. Retouren en credit memo's moeten worden getest voor volledige en gedeeltelijke retouren, vooral wanneer de winkel punten als korting gebruikt.