Magento 2-loyaliteitsprogramma - Kowal Loyalty & Rewards Suite

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 modulecode, de configuratie system.xml, de standaardwaarden config.xml en de productdocumentatie.

Vereisten

• Magento Open Source 2.4.9 of een compatibele Magento 2.4.x-installatie.
• PHP ^8.3.
• Toegang tot de console van de Magento-server.
• Ingeschakelde Magento-cron.
• Ten minste éé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. Deelmodules bevinden zich in packages/, maar bij een standaardinstallatie hoeven ze niet afzonderlijk te worden geïnstalleerd.

Installatie

Voer in het Magento-project uit:

Toegangsgegevens voor de Composer-repository (het e-mailadres van de klant en de licentietoken) ontvangt u per e-mail na aankoop. Ze zijn ook beschikbaar in het klantpaneel na inloggen op kowal.store. Vervang TWOJ_EMAIL_KLIENTA door het e-mailadres van uw account en TWOJ_TOKEN door de ontvangen token. Voer de commando's uit in de hoofdmap van 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

Controleer na installatie of Magento-cron correct werkt. Cron is onder andere nodig voor het activeren van pending punten, het laten vervallen van punten, meldingen en het verversen van ranglijsten.

Lokale pakketvalidatie

In de repository van het pakket kunt u uitvoeren:

./scripts/validate-local.sh

Het script controleert basisbestanden JSON, PHP, PHTML, XML, moduleregistraties en GraphQL-schema's.

Configuratielocatie in het Magento-paneel

De hoofdconfiguratie bevindt zich in:

Stores > Configuration > Kowal > Loyalty & Rewards

De configuratie is grotendeels per website gescopeerd. Dit betekent dat het programma voor één website kan worden ingeschakeld en voor een andere uitgeschakeld kan blijven.

General

Aanbeveling: stel op productie Enable Loyalty = Yes alleen in voor de website waarvoor het programma actief moet zijn. Laat Debug Mode op No staan, tenzij u een specifiek probleem diagnosticeert.

Programma

Aanbeveling: maak vóór publieke inschakeling van het programma CMS-pagina's met de programmavoorwaarden en winkelvoorwaarden en wijs deze vervolgens toe in de configuratie.

Points Defaults

Opties Default Earning Amount Basis:

Aanbeveling: laat voor een typische B2C-webshop Gross After Discounts, rounding_mode = floor, statussen complete en puntgeldigheid van 365 dagen staan.

Point Redemption

Voorbeeld: waarden Points = 100 en Discount Amount = 10 betekenen dat 100 punten 10 eenheden van de basisvaluta korting geven. Bij Maximum Order Percent Paid With Points = 30 kan de klant met punten maximaal 30% van de kwalificerende winkelwagenwaarde betalen.

Aanbeveling: stel bij de start een conservatieve limiet in, bijvoorbeeld 20-30%, zodat het programma niet de volledige marge van de order overneemt.

Feature Flags

Feature flags maken het mogelijk het pakket stapsgewijs te activeren. Voor de eerste configuratie schakelt u meestal in: Program, Rules, Points, Rewards, Checkout en Content.

Leaderboard

Aanbeveling: gebruik publieke ranglijsten alleen wanneer u een goedgekeurd privacybeleid en klantcommunicatie hebt. De module gebruikt standaard pseudoniemen in plaats van persoonsgegevens.

Gamification

Gamificationmechanieken zijn geen echte loterij. De keuze van beloningen is deterministisch of gebaseerd op een gedefinieerde reeks, wat juridische en budgettaire controle eenvoudiger maakt.

Lotteries and Games of Chance

Aanbeveling: gebruik voor gewone promoties Gamification. Schakel Lottery alleen in voor campagnes met aparte voorwaarden, juridische goedkeuring en een landenscope die aan de regelgeving voldoet.

Puntenregels

Puntenregels worden beheerd in het beheerpaneel van de module. Het formulier bevat:

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 newsletterbonus: 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 newsletter, als de newsletterintegratie de juiste gebeurtenis aanroept.

Klantniveaus

Niveaus worden beheerd als administratieve entiteiten. Het niveauformulier bevat:

Standaardniveaus die als sjablonen worden geïnstalleerd:

Behandel de standaardwaarden als startpunt. Stem de drempels vóór productie af op de gemiddelde orderwaarde, marge en aankoopfrequentie.

Configuratievoorbeelden

1. Eenvoudig puntenprogramma voor een B2C-webshop

Doel: de klant spaart punten voor aankopen en kan ze in de winkelwagen besteden.

Instellingen:

• Enable Loyalty = Yes.
• Program Status = active.
• Program Visibility = public.
• Program Terms CMS Page en Store Terms CMS Page verwijzen naar de juiste 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, Content ingesteld op Yes.

Voeg een puntenregel voor aankoop toe en test de volledige flow: enrollment, order, puntentoekenning, gebruik van punten in de winkelwagen.

2. Programma met vertraagde puntactivatie

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 = 14 of 30.
• Default Points Expiration Days = 365.
• Expiration Notification Days = 30,7,1.

Deze variant beperkt het risico dat een klant punten besteedt voordat de retourperiode is afgelopen.

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 Amount in overeenkomstig de minimale B2B-orderwaarde, bijvoorbeeld 500.
• Stel Maximum Order Percent Paid With Points conservatief in, bijvoorbeeld 10 of 20.

Deze variant is zinvol wanneer loyaliteit dichter bij de marge en gefactureerde nettowaarde moet worden afgerekend.

4. VIP-programma met klantniveaus

Doel: betere klanten verdienen extra punten.

Instellingen:

• Schakel de basis-feature flags voor programma, punten, regels en checkout in.
• Configureer niveaus, bijvoorbeeld Silver, Gold, VIP.
• Stel Bonus Multiplier in: 1.25, 1.5, 2.0.
• Stem drempels Minimum Completed Purchase Amount af op verkoopgegevens.

De niveaubonus wordt als aparte transactie in de ledger opgeslagen. Daardoor kunnen rapporten basispunten scheiden van bonuspunten.

5. Campagne met ranglijst

Doel: een publieke klantenranglijst in een campagne tonen.

Instellingen:

• Leaderboard feature flag = Yes.
• Enable Leaderboard = Yes.
• Default Metric = points, challenge_progress, referrals of reviews.
• Default Widget Limit = 10 of een andere redelijke waarde.
• Allow Public Leaderboard Widgets = Yes pas 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 Lottery niet in als de promotie juridisch geen loterij is.
• Gebruik een deterministische mechaniek of een vooraf gedefinieerde beloningsreeks.
• Stel deelname-, e-mail-, puntenbudget- en winlimieten in binnen de configuratie van de mechaniek.

Deze variant is geschikt voor marketingacties die aantrekkelijk moeten ogen, 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 = Yes pas nadat de campagne is voorbereid.
• De campagne moet een actieve status, de juiste website en country scope hebben, evenals 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 webshop 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.
• Newsletter duidelijk beschreven als voorwaarde voor volledige programmarechten.
• Puntenregels gecontroleerd op staging.
• Limieten voor puntgebruik berekend ten opzichte van marge.
• Retouren en credit memo's handmatig getest.
• Magento-cron werkt en verwerkt pending punten, verval en ranglijsten.
• Publieke ranglijsten en loterijen juridisch goedgekeurd.
• REST API en GraphQL gecontroleerd op toegang uitsluitend tot 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 & Rewards of administratiemenu Kowal Loyalty - deelnemers, ledger, handmatige correcties en rapporten, 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 frontend, checkout en beheerpaneel. Saldi mogen niet handmatig worden aangepast zonder ledgertransactie.

Puntenregels zijn cumulatief. Als meerdere actieve regels bij een gebeurtenis passen, kan de klant meerdere afzonderlijke punttransacties ontvangen. Regelprioriteit stuurt 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 order afgerekend. Retouren en credit memo's moeten worden getest voor volledige en gedeeltelijke retouren, vooral wanneer de webshop punten als korting gebruikt.