WhatsApp
+48608012047
Kowal Product Grid Category Filter pour Magento 2
12,50 € 12,50 €
Instructions 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. Les instructions s’appuient sur le code actuel des modules, la configuration system.xml, les valeurs par défaut config.xml ainsi que la documentation du produit.
Prérequis
- Magento Open Source
2.4.9ou 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 un store view configurés.
- Modules Magento utilisés par le package activés, 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 :
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:flushAprès l’installation, vérifiez que le cron Magento fonctionne correctement. Le 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.shLe 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 & RewardsLa 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
| Champ | Chemin config | Par défaut | Signification |
|---|---|---|---|
| Enable Loyalty | kowal_loyalty/general/enabled | No | Active le programme de fidélité pour le website sélectionné. Sans cela, les modules de domaine ne devraient pas traiter le client comme participant à un programme actif. |
| Debug Mode | kowal_loyalty/general/debug | No | Active des diagnostics supplémentaires pour le website sélectionné. À utiliser sur staging ou lors de l’analyse de problèmes. |
| Log Retention Days | kowal_loyalty/general/log_retention_days | 30 | Durée globale de conservation des logs de fidélité en jours. |
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.
Programme
| Champ | Chemin config | Par défaut | Signification |
|---|---|---|---|
| Program ID | kowal_loyalty/program/program_id | default | Identifiant interne du programme. Le MVP suppose un programme par website. Le plus souvent, laissez default. |
| Program Name | kowal_loyalty/program/name | Loyalty & Rewards | Nom du programme visible par le client dans les widgets, la landing page et l’espace compte. |
| Short Description | kowal_loyalty/program/short_description | Earn points, unlock rewards and use them on future orders. | Brève description du programme utilisée dans la présentation frontend. |
| Program Status | kowal_loyalty/program/status | draft | Statut du programme. Seul un programme actif est considéré comme disponible pour les clients. |
| Program Visibility | kowal_loyalty/program/visibility | public | Contrôle la visibilité du programme dans la couche storefront. |
| Program Terms CMS Page | kowal_loyalty/program/program_terms_cms_page | 0 | Page CMS contenant le règlement du programme de fidélité. Le lien peut être utilisé automatiquement par les formulaires et les widgets. |
| Store Terms CMS Page | kowal_loyalty/program/store_terms_cms_page | 0 | Page CMS contenant les conditions générales de la boutique, requise notamment lors de l’inscription d’un invité et de la création d’un compte. |
Recommandation : avant d’activer publiquement le programme, créez des pages CMS avec le règlement du programme et les conditions générales de la boutique, puis assignez-les dans la configuration.
Points Defaults
| Champ | Chemin config | Par défaut | Signification |
|---|---|---|---|
| Default Points Expiration Days | kowal_loyalty/points/expiration_days | 365 | Nombre de jours de validité des points, calculé à partir de la date d’activation. |
| Default Rounding Mode | kowal_loyalty/points/rounding_mode | floor | Mode d’arrondi des points : vers le bas, standard ou vers le haut. |
| Default Earning Amount Basis | kowal_loyalty/points/earning_amount_basis | base_row_total_incl_tax_after_discount | Base de valeur de commande utilisée pour l’attribution des points. La livraison est toujours exclue. |
| Earn Points After Order Status | kowal_loyalty/points/earning_order_status | complete | Statut de commande après lequel les points d’achat sont attribués. |
| Activate Pending Points After Order Status | kowal_loyalty/points/activation_order_status | complete | Statut de commande après lequel les points en attente peuvent devenir disponibles. |
| Activation Delay Days | kowal_loyalty/points/activation_delay_days | 0 | Délai supplémentaire d’activation des points. 0 signifie une activation sans délai après satisfaction du statut. |
| Expiration Notification Days | kowal_loyalty/points/expiration_notification_days | 30,7,1 | Seuils de notification avant l’expiration des points, séparés par des virgules. |
Options Default Earning Amount Basis :
| Valeur | Signification | Quand l’utiliser |
|---|---|---|
base_row_total_incl_tax_after_discount | Montant TTC après remises | Variante B2C la plus fréquente, le client gagne des points sur la valeur réellement payée des produits. |
base_row_total_incl_tax_before_discount | Montant TTC avant remises | Lorsque les promotions de prix ne doivent pas réduire le nombre de points gagnés. |
base_row_total_after_discount | Montant HT après remises | Pour le B2B ou les boutiques qui calculent la fidélité sur la valeur nette. |
base_row_total_before_discount | Montant HT avant remises | Pour les programmes calculés sur la valeur nette catalogue des produits. |
Recommandation : pour une boutique B2C typique, laissez Gross After Discounts, rounding_mode = floor, les statuts complete et une validité des points de 365 jours.
Point Redemption
| Champ | Chemin config | Par défaut | Signification |
|---|---|---|---|
| Points | kowal_loyalty/redemption/points | 100 | Nombre de points correspondant au montant de remise configuré. |
| Discount Amount | kowal_loyalty/redemption/base_amount | 10 | Montant de remise dans la devise de base du website pour le nombre de points indiqué. |
| Minimum Points To Redeem | kowal_loyalty/redemption/min_points | 100 | Nombre minimal de points que le client peut utiliser dans le panier. |
| Minimum Order Amount | kowal_loyalty/redemption/min_order_amount | 100 | Valeur minimale de commande permettant l’utilisation des points. La livraison est exclue de la base de validation. |
| Maximum Order Percent Paid With Points | kowal_loyalty/redemption/max_order_percent | 30 | Pourcentage maximal de la valeur de commande éligible pouvant être couvert par des points. |
Exemple : les valeurs Points = 100 et Discount Amount = 10 signifient que 100 points donnent 10 unités de la devise de base en 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 n’absorbe pas toute la marge de la commande.
Feature Flags
| Champ | Chemin config | Par défaut | Signification |
|---|---|---|---|
| Program | kowal_loyalty/features/program | Yes | Active la couche programme et le contexte website. |
| Rules | kowal_loyalty/features/rules | No | Active la gestion des règles d’attribution de points. |
| Points | kowal_loyalty/features/points | No | Active le ledger de points et la projection du solde. |
| Rewards | kowal_loyalty/features/rewards | No | Active les mécanismes de récompenses et d’utilisation des points. |
| Checkout | kowal_loyalty/features/checkout | No | Active l’intégration avec le panier et le checkout. |
| Content | kowal_loyalty/features/content | No | Active la couche de contenu, les landing pages, les widgets et les blocs frontend. |
| Leaderboard | kowal_loyalty/features/leaderboard | No | Active le classement clients, si le module est installé. |
| Gamification | kowal_loyalty/features/gamification | No | Active les mécaniques promotionnelles déterministes. |
| Lottery | kowal_loyalty/features/lottery | No | Active le module de loteries et jeux de hasard. |
Les feature flags permettent de lancer le package progressivement. Pour une première configuration, activez généralement : Program, Rules, Points, Rewards, Checkout et Content.
Leaderboard
| Champ | Chemin config | Par défaut | Signification |
|---|---|---|---|
| Enable Leaderboard | kowal_loyalty/leaderboard/enabled | No | Active la matérialisation des classements par cron. Laissez désactivé jusqu’à l’acceptation des règles de confidentialité. |
| Allow Public Leaderboard Widgets | kowal_loyalty/leaderboard/public_enabled | No | Permet d’afficher des widgets de classement publics. Lorsque cette option est désactivée, les widgets ne rendent pas de classement public. |
| Default Metric | kowal_loyalty/leaderboard/default_metric | points | Métrique par défaut du classement : points, progression des défis, parrainages ou avis. |
| Default Widget Limit | kowal_loyalty/leaderboard/default_limit | 10 | Nombre de positions dans les widgets. Le code limite la valeur à 100 au maximum. |
Recommandation : utilisez les classements publics uniquement si votre politique de confidentialité et votre communication client ont été validées. Le module utilise par défaut des pseudonymes au lieu de données personnelles.
Gamification
| Champ | Chemin config | Par défaut | Signification |
|---|---|---|---|
| Enable Gamification Mechanics | kowal_loyalty/gamification/enabled | No | Active les mécaniques promotionnelles déterministes, par exemple Spin the Wheel et Scratch & Win. |
| Gamification feature flag | kowal_loyalty/features/gamification | No | Feature flag pour le domaine de la gamification. |
Les mécaniques de gamification ne sont pas une vraie loterie. Le choix des récompenses est déterministe ou basé sur une séquence définie, ce qui facilite le contrôle juridique et budgétaire.
Loteries et jeux de hasard
| Champ | Chemin config | Par défaut | Signification |
|---|---|---|---|
| Enable Lottery Module | kowal_loyalty/lottery/enabled | No | Active le module de loterie. Laissez désactivé sans vérification juridique préalable. |
| Allow Public Lottery Widgets | kowal_loyalty/lottery/public_widgets_enabled | No | Permet de rendre des widgets publics de campagnes actives disposant d’une approbation juridique. |
| Lottery feature flag | kowal_loyalty/features/lottery | No | Feature flag pour le domaine des loteries. |
Recommandation : pour les promotions ordinaires, utilisez Gamification. Activez Lottery uniquement pour les campagnes disposant d’un règlement séparé, 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 :
| Champ | Signification |
|---|---|
| Enabled | Indique si la règle est active. |
| Program ID | Programme concerné par la règle. Dans le MVP, généralement default. |
| Name | Nom de la règle visible dans l’administration. |
| Description | Description auxiliaire pour l’administrateur. |
| Event Type | Événement pour lequel les points sont attribués, par exemple achat, newsletter, referral. |
| Points Mode | Mode d’attribution des points, par exemple valeur fixe ou valeur dépendant du montant. |
| Points Value | Nombre de points ou taux de conversion utilisé par le mode sélectionné. |
| Priority | Ordre d’évaluation. Les règles correspondant à l’événement se cumulent ; la priorité n’arrête pas les règles suivantes. |
| Related Landing Page Identifier | Identifiant de la page CMS associée à la règle. |
| Website IDs | Liste d’ID website séparés par des virgules. Un champ vide signifie tous les website. |
| Customer Group IDs | Liste d’ID de groupes clients séparés par des virgules. Un champ vide signifie tous les groupes. |
| From Date / To Date | Période de validité de la règle. |
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 l’attribution de points selon la valeur du panier conformément à la base définie dans 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 :
| Champ | Signification |
|---|---|
| Enabled | Indique si le niveau est actif. |
| Program ID | Programme concerné par le niveau. Dans le MVP, généralement default. |
| Name | Nom du niveau, par exemple Silver, Gold, VIP. |
| Code | Code technique du niveau. |
| Sort Order | Ordre des niveaux. |
| Minimum Completed Purchase Amount | Valeur minimale des commandes terminées sur les 12 derniers mois, hors livraison. |
| Minimum Completed Orders | Nombre minimal de commandes terminées. |
| Minimum Earned Points | Nombre minimal de points gagnés. |
| Bonus Multiplier | Multiplicateur de bonus. 1.25 signifie une transaction bonus distincte de +25% par rapport aux points de base. |
| Website IDs | Liste d’ID website séparés par des virgules. Un champ vide signifie tous les website. |
Niveaux par défaut installés comme modèles :
| Niveau | Seuil d’achats | Multiplicateur |
|---|---|---|
| Silver | 1000 | 1.25 |
| Gold | 3000 | 1.5 |
| VIP | 7500 | 2.0 |
Considérez les valeurs par défaut comme un point de départ. Avant la production, adaptez les seuils à la valeur moyenne des commandes, à 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 PageetStore Terms CMS Pagepointent 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,Contentdéfinis surYes.
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 ne deviennent disponibles qu’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 = 14ou30.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 Amountselon la valeur minimale de commande B2B, par exemple500. - Définissez
Maximum Order Percent Paid With Pointsde manière prudente, par exemple10ou20.
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 Amountaux données de vente.
Le bonus de niveau est enregistré comme une transaction séparée dans le ledger. Les rapports peuvent ainsi distinguer 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,referralsoureviews.Default Widget Limit = 10ou une autre valeur raisonnable.Allow Public Leaderboard Widgets = Yesuniquement après acceptation des règles de confidentialité.
Avant publication, vérifiez le contenu du règlement, la politique de confidentialité et la manière de présenter les alias clients.
6. Promotion Spin the Wheel sans loterie
Objectif : une action promotionnelle contrôlée avec des récompenses sans mécanisme aléatoire.
Paramètres :
Gamification feature flag = Yes.Enable Gamification Mechanics = Yes.- N’activez pas
Lotterysi 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, e-mail, budget de points et nombre de gains dans la configuration de la mécanique.
Cette variante est adaptée aux actions marketing qui doivent être attractives, tout en restant contrôlé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 = Yesuniquement après préparation de la campagne.- La campagne doit avoir un statut actif, le website et le country scope appropriés ainsi que
legal_approval_status = approved. - Ajoutez un règlement CMS séparé 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 mise en production
- Programme activé uniquement pour les website appropriés.
- Statut du programme défini comme actif.
- Règlement du programme et conditions générales de la boutique assignés à des pages CMS.
- Newsletter décrite clairement comme condition d’accès complet aux droits du programme.
- Règles de points vérifiées sur staging.
- Limites d’utilisation des points calculées par rapport à la marge.
- Retours et credit memo testés manuellement.
- Cron Magento opérationnel et traitant les points en attente, l’expiration et les classements.
- Classements publics et loteries approuvé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é pour l’idempotence.
Emplacements utiles dans le panneau
Stores > Configuration > Kowal > Loyalty & Rewards- configuration principale du programme.Customers > Loyalty & Rewardsou menu d’administrationKowal Loyalty- participants, ledger, corrections manuelles et rapports, selon les modules activés.- CMS Pages - règlements du programme, conditions générales de la boutique et landing pages.
- Cart Price Rules - règles de remise utilisées par les récompenses sous forme de coupons.
Notes opérationnelles
Le ledger des points est la source de vérité. La table des soldes est une projection destinée aux lectures rapides dans le frontend, le checkout et le panneau d’administration. Les soldes ne doivent pas être modifiés manuellement sans transaction de ledger.
Les règles de points sont cumulatives. Si plusieurs règles actives correspondent à un é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 dans le quote, transférés vers l’order et comptabilisés après la passation de la commande. Les retours et les credit memo doivent être testés pour les retours complets et partiels, en particulier lorsque la boutique utilise les points comme remise.