Programa de fidelización Magento 2 - Kowal Loyalty & Rewards Suite

Instrucciones de instalación y configuración de Kowal Loyalty & Rewards Suite

Este documento describe la instalación y la configuración básica del paquetekowal/metapackage-loyalty-suiteen Magento 2. Las instrucciones se basan en el código actual de los módulos, la configuraciónsystem.xml, los valores predeterminados deconfig.xmly la documentación del producto.

Requisitos

• Magento Open Source2.4.9o una instalación compatible de Magento 2.4.x.
• PHP^8.3.
• Acceso a la consola del servidor Magento.
• Cron de Magento activado.
• Al menos un website, store y store view configurados.
• Módulos Magento activos utilizados por el paquete, entre otros Customer, Sales, Quote, Checkout, CMS, Newsletter, SalesRule, Webapi, GraphQl, UI e ImportExport.

El paquete se instala como un único root package Composer. Los submódulos se encuentran enpackages/, pero la instalación estándar no requiere instalarlos por separado.

Instalación

En el proyecto Magento, ejecuta:

Recibirás por correo electrónico los datos de acceso al repositorio Composer, es decir, el e-mail del cliente y el token de licencia, después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

composer config repositories.kowal composer https://repo.kowal.store
composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
composer require kowal/metapackage-loyalty-suite:^0.1
bin/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_LoyaltyIntegration
bin/magento setup:upgrade
bin/magento cache:flush

Después de la instalación, comprueba que el cron de Magento funcione correctamente. Cron es necesario, entre otras cosas, para activar puntos pendientes, caducar puntos, enviar notificaciones y actualizar rankings.

Validación local del paquete

En el repositorio del paquete puedes ejecutar:

./scripts/validate-local.sh

El script comprueba archivos JSON, PHP, PHTML, XML, registros de módulos y esquemas GraphQL básicos.

Ubicación de la configuración en el panel de Magento

La configuración principal se encuentra en:

Stores > Configuration > Kowal > Loyalty & Rewards

La configuración está en su mayoría limitada por website. Esto significa que el programa puede activarse para un website y mantenerse desactivado para otro.

General

Recomendación: en producción, configuraEnable Loyalty = Yessolo para el website en el que el programa debe estar activo. ManténDebug ModecomoNo, salvo que estés diagnosticando un problema concreto.

Program

Recomendación: antes de activar públicamente el programa, crea páginas CMS con los términos y condiciones del programa y de la tienda, y después asígnalas en la configuración.

Valores predeterminados de puntos

Opciones deDefault Earning Amount Basis:

Recomendación: para una tienda B2C típica, dejaGross After Discounts,rounding_mode = floor, los estadoscompletey la validez de puntos de365días.

Canje de puntos

Ejemplo: los valoresPoints = 100yDiscount Amount = 10significan que 100 puntos proporcionan 10 unidades de la moneda base de descuento. ConMaximum Order Percent Paid With Points = 30, el cliente puede cubrir con puntos como máximo el 30% del valor elegible del carrito.

Recomendación: para empezar, establece un límite conservador, por ejemplo 20-30%, para que el programa no absorba todo el margen del pedido.

Feature Flags

Los feature flags permiten lanzar el paquete por etapas. Para la primera configuración, normalmente activa:Program,Rules,Points,Rewards,CheckoutyContent.

Leaderboard

Recomendación: utiliza rankings públicos solo cuando tengas aceptada la política de privacidad y la comunicación con el cliente. Por defecto, el módulo utiliza seudónimos en lugar de datos personales.

Gamificación

Las mecánicas de gamificación no son una lotería real. La selección de premios es determinista o se basa en una secuencia definida, lo que facilita el control legal y presupuestario.

Loterías y juegos de azar

Recomendación: para promociones habituales, utilizaGamification.Lotterysolo para campañas que tengan términos y condiciones independientes, aprobación legal y un alcance nacional conforme a la normativa.

Reglas de puntos

Las reglas de puntos se gestionan en el panel de administración del módulo. Su formulario contiene:

Ejemplo de una regla de compra sencilla:Event Type = purchase,Points Mode = amount based,Points Value = 1, activa para todos los grupos y solo para el website seleccionado. Esto significa calcular puntos según el valor del carrito conforme a la base de la configuraciónPoints Defaults.

Ejemplo de bonus por newsletter:Event Type = newsletter_signup,Points Mode = fixed,Points Value = 50, periodo sin fecha de finalización. La regla concede un bonus único después de que el cliente se suscriba a la newsletter, si la integración de newsletter invoca el evento correspondiente.

Niveles de clientes

Los niveles se gestionan como entidades administrativas. El formulario de nivel contiene:

Niveles predeterminados instalados como plantillas:

Trata los valores predeterminados como punto de partida. Antes de producción, ajusta los umbrales al valor medio del pedido, el margen y la frecuencia de compra.

Ejemplos de configuración

1. Programa sencillo de puntos para B2C

Objetivo: el cliente acumula puntos por compras y puede gastarlos en el carrito.

Ajustes:

• Enable Loyalty = Yes.
• Program Status = active.
• Program Visibility = public.
• Program Terms CMS PageyStore Terms CMS Pageapuntan a las páginas CMS correctas.
• 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,Contentconfigurados comoYes.

Añade una regla de puntos por compra y prueba todo el flujo: enrollment, pedido, cálculo de puntos, uso de puntos en el carrito.

2. Programa con activación diferida de puntos

Objetivo: los puntos pasan a estar disponibles solo después del plazo de devolución.

Ajustes:

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

Esta variante limita el riesgo de que el cliente gaste puntos antes de que finalice el periodo de devolución.

3. Programa B2B calculado sobre el valor neto

Objetivo: calcular puntos sobre el valor neto de los productos, sin envío ni impuestos.

Ajustes:

• Default Earning Amount Basis = Net After Discounts.
• Default Rounding Mode = floor.
• Minimum Order Amountsegún el valor mínimo de pedido B2B, por ejemplo500.
• Maximum Order Percent Paid With Pointsde forma conservadora, por ejemplo10o20.

Esta variante tiene sentido cuando la fidelización debe liquidarse más cerca del margen y del valor neto facturado.

4. Programa VIP con niveles de clientes

Objetivo: los mejores clientes obtienen puntos adicionales.

Ajustes:

• Activa los feature flags básicos del programa, puntos, reglas y checkout.
• Configura los niveles, por ejemplo Silver, Gold, VIP.
• ConfiguraBonus Multiplier:1.25,1.5,2.0.
• Ajusta los umbrales deMinimum Completed Purchase Amounta los datos de ventas.

El bonus de nivel se registra como una transacción independiente en el ledger. Gracias a ello, los informes pueden separar los puntos base de los puntos de bonus.

5. Campaña con clasificación

Objetivo: mostrar un ranking público de clientes en la campaña.

Ajustes:

• Leaderboard feature flag = Yes.
• Enable Leaderboard = Yes.
• Default Metric = points,challenge_progress,referralsoreviews.
• Default Widget Limit = 10u otro valor razonable.
• Allow Public Leaderboard Widgets = Yessolo después de la aceptación de las normas de privacidad.

Antes de publicar, comprueba el contenido de los términos y condiciones, la política de privacidad y la forma de presentar los alias de los clientes.

6. Promoción Spin the Wheel sin lotería

Objetivo: acción promocional controlada con premios sin mecanismo aleatorio.

Ajustes:

• Gamification feature flag = Yes.
• Enable Gamification Mechanics = Yes.
• No activesLotterysi la promoción no es legalmente una lotería.
• Utiliza una mecánica determinista o una secuencia predefinida de premios.
• Configura límites de participación del cliente, e-mail, presupuesto de puntos y número de premios en la configuración de la mecánica.

Esta variante es adecuada para acciones de marketing que deben resultar atractivas, pero al mismo tiempo mantenerse controladas en presupuesto y auditables.

7. Lotería o juego de azar

Objetivo: lanzar una campaña con un elemento aleatorio real.

Ajustes:

• Lottery feature flag = Yes.
• Enable Lottery Module = Yes.
• Allow Public Lottery Widgets = Yessolo después de preparar la campaña.
• La campaña debe tener estado activo, el website correcto y country scope, así comolegal_approval_status = approved.
• Añade términos y condiciones CMS independientes y una landing page de campaña.

No utilices esta variante sin verificación legal para el país en el que opera la tienda.

Checklist antes de producción

• Programa activado solo para los websites correctos.
• Estado del programa configurado como activo.
• Términos y condiciones del programa y de la tienda asignados a páginas CMS.
• Newsletter descrita claramente como condición para obtener todos los derechos del programa.
• Reglas de puntos comprobadas en staging.
• Límites de uso de puntos calculados en relación con el margen.
• Devoluciones y credit memo probados manualmente.
• Cron de Magento funciona y procesa puntos pendientes, caducidades y rankings.
• Rankings públicos y loterías aceptados legalmente.
• REST API y GraphQL comprobados en cuanto al acceso únicamente a los datos del cliente correcto.
• Importación de ajustes de puntos probada en cuanto a idempotencia.

Ubicaciones útiles en el panel

• Stores > Configuration > Kowal > Loyalty & Rewards- configuración principal del programa.
• Customers > Loyalty & Rewardso el menú administrativoKowal Loyalty- participantes, ledger, ajustes manuales e informes, según los módulos activados.
• CMS Pages - términos y condiciones del programa, términos y condiciones de la tienda y landing pages.
• Cart Price Rules - reglas de descuento utilizadas por las recompensas con cupones.

Notas operativas

El ledger de puntos es la fuente de verdad. La tabla de saldos es una proyección para lecturas rápidas en el frontend, checkout y panel de administración. No se deben editar manualmente los saldos sin una transacción de ledger.

Las reglas de puntos son acumulativas. Si varias reglas activas coinciden con el evento, el cliente puede recibir varias transacciones de puntos independientes. La prioridad de la regla controla el orden y la claridad de la auditoría, no la detención de las reglas posteriores.

Los puntos utilizados en el carrito se guardan en quote, se transfieren a order y se liquidan después de realizar el pedido. Las devoluciones y credit memo deben probarse para devoluciones completas y parciales, especialmente cuando la tienda utiliza puntos como descuento.