Programme de fidélité Magento 2 - Kowal Loyalty & Rewards Suite

Guide d'installation et de configuration de Kowal Loyalty & Rewards Suite

Ce document décrit l'installation et la configuration de base du package kowal/metapackage-loyalty-suite dans Magento 2. Le guide s'appuie sur le code actuel des modules, la configuration system.xml, les valeurs par défaut config.xml et la documentation produit.

Exigences

• Magento Open Source 2.4.9 ou une installation Magento 2.4.x compatible.
• PHP ^8.3.
• Accès à la console du serveur Magento.
• Cron Magento activé.
• Au moins un website, un store et une store view configurés.
• Modules Magento utilisés par le package actifs, notamment Customer, Sales, Quote, Checkout, CMS, Newsletter, SalesRule, Webapi, GraphQl, UI et ImportExport.

Le package est installé comme un seul root package Composer. Les modules partiels se trouvent dans packages/, mais l'installation standard ne nécessite pas de les installer séparément.

Installation

Dans le projet Magento, exécutez :

Les identifiants d'accès au dépôt Composer, à savoir l'adresse e-mail du client et le token de licence, vous seront envoyés par e-mail après l'achat. Ils sont également disponibles dans l'espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l'adresse e-mail de votre compte et TWOJ_TOKEN par le token reçu. Exécutez les commandes dans le répertoire racine de 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

Après l'installation, vérifiez que cron Magento fonctionne correctement. Cron est nécessaire notamment pour l'activation des points en attente, l'expiration des points, les notifications et l'actualisation des classements.

Validation locale du package

Dans le dépôt du package, vous pouvez exécuter :

./scripts/validate-local.sh

Le script vérifie les fichiers JSON, PHP, PHTML, XML de base, les enregistrements de modules et les schémas GraphQL.

Emplacement de la configuration dans le panneau Magento

La configuration principale se trouve dans :

Stores > Configuration > Kowal > Loyalty & Rewards

La configuration est principalement définie par website. Cela signifie que le programme peut être activé pour un website et rester désactivé pour un autre.

General

Recommandation : en production, définissez Enable Loyalty = Yes uniquement pour le website sur lequel le programme doit être actif. Laissez Debug Mode sur No, sauf si vous diagnostiquez un problème précis.

Program

Recommandation : avant d'activer publiquement le programme, créez les pages CMS avec les conditions du programme et les conditions de la boutique, puis attribuez-les dans la configuration.

Points Defaults

Options Default Earning Amount Basis :

Recommandation : pour une boutique B2C classique, laissez Gross After Discounts, rounding_mode = floor, les statuts complete et une validité des points de 365 jours.

Point Redemption

Exemple : les valeurs Points = 100 et Discount Amount = 10 signifient que 100 points donnent 10 unités de devise de base de remise. Avec Maximum Order Percent Paid With Points = 30, le client peut couvrir avec des points au maximum 30% de la valeur éligible du panier.

Recommandation : au démarrage, définissez une limite prudente, par exemple 20-30%, afin que le programme ne consomme pas toute la marge de la commande.

Feature Flags

Les feature flags permettent de lancer le package par étapes. Pour une première configuration, activez généralement : Program, Rules, Points, Rewards, Checkout et Content.

Leaderboard

Recommandation : utilisez les classements publics uniquement si votre politique de confidentialité et votre communication client ont été validées. Par défaut, le module utilise des pseudonymes au lieu de données personnelles.

Gamification

Les mécaniques de gamification ne sont pas une véritable loterie. Le choix des récompenses est déterministe ou fondé sur une séquence définie, ce qui facilite le contrôle juridique et budgétaire.

Lotteries and Games of Chance

Recommandation : pour les promotions ordinaires, utilisez Gamification. Activez Lottery uniquement pour les campagnes disposant d'un règlement distinct, d'une approbation juridique et d'un périmètre national conforme à la réglementation.

Règles de points

Les règles de points sont gérées dans le panneau d'administration du module. Leur formulaire contient :

Exemple de règle d'achat simple : Event Type = purchase, Points Mode = amount based, Points Value = 1, active pour tous les groupes et uniquement pour le website sélectionné. Cela signifie une attribution de points selon la valeur du panier conformément à la base de la configuration Points Defaults.

Exemple de bonus newsletter : Event Type = newsletter_signup, Points Mode = fixed, Points Value = 50, période sans date de fin. La règle attribue un bonus unique après l'inscription du client à la newsletter, si l'intégration newsletter déclenche l'événement approprié.

Niveaux clients

Les niveaux sont gérés comme des entités administratives. Le formulaire de niveau contient :

Niveaux par défaut installés comme modèles :

Considérez les valeurs par défaut comme un point de départ. Avant la production, ajustez les seuils à la valeur moyenne de commande, à la marge et à la fréquence d'achat.

Exemples de configuration

1. Programme de points simple pour une boutique B2C

Objectif : le client collecte des points pour ses achats et peut les dépenser dans le panier.

Paramètres :

• Enable Loyalty = Yes.
• Program Status = active.
• Program Visibility = public.
• Program Terms CMS Page et Store Terms CMS Page pointent vers les pages CMS correctes.
• 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 définis sur Yes.

Ajoutez une règle de points pour l'achat et testez l'ensemble du flux : enrollment, commande, attribution des points, utilisation des points dans le panier.

2. Programme avec activation différée des points

Objectif : les points deviennent disponibles seulement après le délai de retour.

Paramètres :

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

Cette variante limite le risque que le client dépense des points avant la fin de la période de retour.

3. Programme B2B calculé sur la valeur nette

Objectif : attribuer des points sur la valeur nette des produits, hors livraison et hors taxe.

Paramètres :

• Default Earning Amount Basis = Net After Discounts.
• Default Rounding Mode = floor.
• Définissez Minimum Order Amount conformément à la valeur minimale de commande B2B, par exemple 500.
• Définissez Maximum Order Percent Paid With Points de manière prudente, par exemple 10 ou 20.

Cette variante est pertinente lorsque la fidélité doit être calculée au plus près de la marge et de la valeur nette facturée.

4. Programme VIP avec niveaux clients

Objectif : les meilleurs clients gagnent des points supplémentaires.

Paramètres :

• Activez les feature flags de base du programme, des points, des règles et du checkout.
• Configurez les niveaux, par exemple Silver, Gold, VIP.
• Définissez Bonus Multiplier : 1.25, 1.5, 2.0.
• Adaptez les seuils Minimum Completed Purchase Amount aux données de vente.

Le bonus de niveau est enregistré comme une transaction distincte dans le ledger. Les rapports peuvent ainsi séparer les points de base des points bonus.

5. Campagne avec classement

Objectif : afficher un classement public des clients dans une campagne.

Paramètres :

• Leaderboard feature flag = Yes.
• Enable Leaderboard = Yes.
• Default Metric = points, challenge_progress, referrals ou reviews.
• Default Widget Limit = 10 ou une autre valeur raisonnable.
• Allow Public Leaderboard Widgets = Yes seulement après validation des règles de confidentialité.

Avant publication, vérifiez le contenu du règlement, la politique de confidentialité et la façon de présenter les alias des clients.

6. Promotion Spin the Wheel sans loterie

Objectif : une action promotionnelle contrôlée avec récompenses sans mécanisme aléatoire.

Paramètres :

• Gamification feature flag = Yes.
• Enable Gamification Mechanics = Yes.
• N'activez pas Lottery si la promotion n'est pas juridiquement une loterie.
• Utilisez une mécanique déterministe ou une séquence de récompenses prédéfinie.
• Définissez les limites de participation par client, par e-mail, le budget de points et le nombre de gains dans la configuration de la mécanique.

Cette variante convient aux actions marketing qui doivent être attractives tout en restant maîtrisées sur le plan budgétaire et auditables.

7. Loterie ou jeu de hasard

Objectif : lancer une campagne avec un véritable élément aléatoire.

Paramètres :

• Lottery feature flag = Yes.
• Enable Lottery Module = Yes.
• Allow Public Lottery Widgets = Yes seulement après préparation de la campagne.
• La campagne doit avoir un statut actif, le bon website et country scope ainsi que legal_approval_status = approved.
• Ajoutez un règlement CMS distinct et une landing page de campagne.

N'utilisez pas cette variante sans vérification juridique pour le pays dans lequel la boutique opère.

Checklist avant production

• Programme activé uniquement pour les websites appropriés.
• Statut du programme défini comme actif.
• Conditions du programme et conditions de la boutique attribuées aux pages CMS.
• Newsletter clairement décrite comme condition d'obtention de droits complets au programme.
• Règles de points vérifiées en staging.
• Limites d'utilisation des points calculées par rapport à la marge.
• Retours et credit memos testés manuellement.
• Cron Magento fonctionne et traite les points en attente, les expirations et les classements.
• Classements publics et loteries validés juridiquement.
• REST API et GraphQL vérifiés pour garantir l'accès uniquement aux données du client concerné.
• Import des corrections de points testé du point de vue de l'idempotence.

Emplacements utiles dans le panneau

• Stores > Configuration > Kowal > Loyalty & Rewards - configuration principale du programme.
• Customers > Loyalty & Rewards ou menu d'administration Kowal Loyalty - participants, ledger, corrections manuelles et rapports, selon les modules activés.
• CMS Pages - conditions du programme, conditions de la boutique et landing pages.
• Cart Price Rules - règles de remise utilisées par les récompenses sous forme de coupon.

Notes opérationnelles

Le ledger de points est la source de vérité. La table des soldes est une projection destinée à des lectures rapides dans le frontend, le checkout et le panneau d'administration. Les soldes ne doivent pas être modifiés manuellement sans transaction ledger.

Les règles de points sont cumulatives. Si plusieurs règles actives correspondent à l'événement, le client peut recevoir plusieurs transactions de points distinctes. La priorité de la règle contrôle l'ordre et la lisibilité de l'audit, et non l'arrêt des règles suivantes.

Les points utilisés dans le panier sont enregistrés sur le quote, transférés vers la order et comptabilisés après la passation de la commande. Les retours et les credit memos doivent être testés pour les retours complets et partiels, en particulier lorsque la boutique utilise les points comme remise.