WhatsApp
+48608012047
Kowal Product Grid Category Filter para Magento 2
12,50 € 12,50 €
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 paquete kowal/metapackage-loyalty-suite en Magento 2. La guía se basa en el código actual de los módulos, la configuración system.xml, los valores predeterminados config.xml y la documentación del producto.
Requisitos
- Magento Open Source
2.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 módulos parciales se encuentran en packages/, pero la instalación estándar no requiere instalarlos por separado.
Instalación
En el proyecto Magento, ejecute:
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:flushTras la instalación, compruebe que el cron de Magento funciona 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 puede ejecutar:
./scripts/validate-local.shEl script comprueba archivos JSON, PHP, PHTML, XML básicos, registros de módulos y esquemas GraphQL.
Ubicación de la configuración en el panel Magento
La configuración principal se encuentra en:
Stores > Configuration > Kowal > Loyalty & RewardsLa configuración tiene en su mayoría alcance por website. Esto significa que el programa puede activarse para un website y permanecer desactivado para otro.
General
| Campo | Ruta config | Predeterminado | Significado |
|---|---|---|---|
| Enable Loyalty | kowal_loyalty/general/enabled | No | Activa el programa de fidelización para el website seleccionado. Sin esto, los módulos de dominio no deberían tratar al cliente como participante de un programa activo. |
| Debug Mode | kowal_loyalty/general/debug | No | Activa diagnósticos adicionales para el website seleccionado. Úselo en staging o al analizar problemas. |
| Log Retention Days | kowal_loyalty/general/log_retention_days | 30 | Periodo global de conservación de logs de fidelización en días. |
Recomendación: en producción configure Enable Loyalty = Yes solo para el website en el que el programa debe estar activo. Mantenga Debug Mode como No, salvo que esté diagnosticando un problema concreto.
Program
| Campo | Ruta config | Predeterminado | Significado |
|---|---|---|---|
| Program ID | kowal_loyalty/program/program_id | default | Identificador interno del programa. El MVP presupone un programa por website. Normalmente deje default. |
| Program Name | kowal_loyalty/program/name | Loyalty & Rewards | Nombre del programa visible para el cliente en widgets, landing page y panel de cuenta. |
| Short Description | kowal_loyalty/program/short_description | Earn points, unlock rewards and use them on future orders. | Descripción breve del programa utilizada en la presentación frontend. |
| Program Status | kowal_loyalty/program/status | draft | Estado del programa. Solo un programa activo se considera disponible para los clientes. |
| Program Visibility | kowal_loyalty/program/visibility | public | Controla la visibilidad del programa en la capa storefront. |
| Program Terms CMS Page | kowal_loyalty/program/program_terms_cms_page | 0 | Página CMS con los términos del programa de fidelización. El enlace puede ser usado automáticamente por formularios y widgets. |
| Store Terms CMS Page | kowal_loyalty/program/store_terms_cms_page | 0 | Página CMS con los términos de la tienda, requerida especialmente al registrar invitados y crear cuentas. |
Recomendación: antes de activar públicamente el programa, cree páginas CMS con los términos del programa y los términos de la tienda, y luego asígnelas en la configuración.
Points Defaults
| Campo | Ruta config | Predeterminado | Significado |
|---|---|---|---|
| Default Points Expiration Days | kowal_loyalty/points/expiration_days | 365 | Número de días de validez de los puntos contado desde la fecha de activación. |
| Default Rounding Mode | kowal_loyalty/points/rounding_mode | floor | Método de redondeo de puntos: hacia abajo, estándar o hacia arriba. |
| Default Earning Amount Basis | kowal_loyalty/points/earning_amount_basis | base_row_total_incl_tax_after_discount | Base del valor del pedido utilizada para acumular puntos. El envío siempre está excluido. |
| Earn Points After Order Status | kowal_loyalty/points/earning_order_status | complete | Estado del pedido tras el cual se acumulan los puntos de compra. |
| Activate Pending Points After Order Status | kowal_loyalty/points/activation_order_status | complete | Estado del pedido tras el cual los puntos pendientes pueden pasar a estar disponibles. |
| Activation Delay Days | kowal_loyalty/points/activation_delay_days | 0 | Retraso adicional en la activación de puntos. 0 significa activación sin retraso tras cumplirse el estado. |
| Expiration Notification Days | kowal_loyalty/points/expiration_notification_days | 30,7,1 | Umbrales de notificación antes de la caducidad de los puntos, separados por comas. |
Opciones de Default Earning Amount Basis:
| Valor | Significado | Cuándo usarlo |
|---|---|---|
base_row_total_incl_tax_after_discount | Importe bruto después de descuentos | La variante B2C más habitual; el cliente obtiene puntos sobre el valor de productos realmente pagado. |
base_row_total_incl_tax_before_discount | Importe bruto antes de descuentos | Cuando las promociones de precio no deben reducir la cantidad de puntos obtenidos. |
base_row_total_after_discount | Importe neto después de descuentos | Para B2B o tiendas que liquidan la fidelización sobre el valor neto. |
base_row_total_before_discount | Importe neto antes de descuentos | Para programas calculados sobre el valor neto de catálogo de los productos. |
Recomendación: para una tienda B2C típica deje Gross After Discounts, rounding_mode = floor, estados complete y validez de puntos de 365 días.
Point Redemption
| Campo | Ruta config | Predeterminado | Significado |
|---|---|---|---|
| Points | kowal_loyalty/redemption/points | 100 | Número de puntos correspondiente al importe de descuento configurado. |
| Discount Amount | kowal_loyalty/redemption/base_amount | 10 | Importe del descuento en la moneda base del website para el número de puntos indicado. |
| Minimum Points To Redeem | kowal_loyalty/redemption/min_points | 100 | Número mínimo de puntos que el cliente puede usar en el carrito. |
| Minimum Order Amount | kowal_loyalty/redemption/min_order_amount | 100 | Valor mínimo del pedido que permite usar puntos. El envío está excluido de la base de validación. |
| Maximum Order Percent Paid With Points | kowal_loyalty/redemption/max_order_percent | 30 | Porcentaje máximo del valor elegible del pedido que puede cubrirse con puntos. |
Ejemplo: los valores Points = 100 y Discount Amount = 10 significan que 100 puntos proporcionan 10 unidades de la moneda base de descuento. Con Maximum Order Percent Paid With Points = 30, el cliente puede cubrir con puntos como máximo el 30% del valor elegible del carrito.
Recomendación: al empezar, configure un límite conservador, por ejemplo 20-30%, para que el programa no absorba todo el margen del pedido.
Feature Flags
| Campo | Ruta config | Predeterminado | Significado |
|---|---|---|---|
| Program | kowal_loyalty/features/program | Yes | Activa la capa de programa y contexto website. |
| Rules | kowal_loyalty/features/rules | No | Activa la gestión de reglas de acumulación de puntos. |
| Points | kowal_loyalty/features/points | No | Activa el ledger de puntos y la proyección de saldo. |
| Rewards | kowal_loyalty/features/rewards | No | Activa los mecanismos de recompensas y uso de puntos. |
| Checkout | kowal_loyalty/features/checkout | No | Activa la integración con el carrito y el checkout. |
| Content | kowal_loyalty/features/content | No | Activa la capa de content, landing pages, widgets y bloques frontend. |
| Leaderboard | kowal_loyalty/features/leaderboard | No | Activa el ranking de clientes si el módulo está instalado. |
| Gamification | kowal_loyalty/features/gamification | No | Activa las mecánicas promocionales deterministas. |
| Lottery | kowal_loyalty/features/lottery | No | Activa el módulo de sorteos y juegos de azar. |
Las feature flags permiten poner en marcha el paquete por fases. Para la primera configuración, normalmente active: Program, Rules, Points, Rewards, Checkout y Content.
Leaderboard
| Campo | Ruta config | Predeterminado | Significado |
|---|---|---|---|
| Enable Leaderboard | kowal_loyalty/leaderboard/enabled | No | Activa la materialización de rankings mediante cron. Manténgalo desactivado hasta que se acepten las normas de privacidad. |
| Allow Public Leaderboard Widgets | kowal_loyalty/leaderboard/public_enabled | No | Permite mostrar widgets públicos de rankings. Cuando está desactivado, los widgets no renderizan el ranking público. |
| Default Metric | kowal_loyalty/leaderboard/default_metric | points | Métrica predeterminada del ranking: puntos, progreso de retos, recomendaciones u opiniones. |
| Default Widget Limit | kowal_loyalty/leaderboard/default_limit | 10 | Número de posiciones en widgets. El código limita el valor a un máximo de 100. |
Recomendación: use rankings públicos solo cuando tenga aprobada la política de privacidad y la comunicación con el cliente. El módulo usa pseudónimos de forma predeterminada en lugar de datos personales.
Gamification
| Campo | Ruta config | Predeterminado | Significado |
|---|---|---|---|
| Enable Gamification Mechanics | kowal_loyalty/gamification/enabled | No | Activa mecánicas promocionales deterministas, por ejemplo Spin the Wheel y Scratch & Win. |
| Gamification feature flag | kowal_loyalty/features/gamification | No | Feature flag para el área de gamificación. |
Las mecánicas de gamificación no son un sorteo real. La elección de recompensas es determinista o se basa en una secuencia definida, lo que facilita el control legal y presupuestario.
Sorteos y juegos de azar
| Campo | Ruta config | Predeterminado | Significado |
|---|---|---|---|
| Enable Lottery Module | kowal_loyalty/lottery/enabled | No | Activa el módulo de sorteos. Manténgalo desactivado sin verificación legal previa. |
| Allow Public Lottery Widgets | kowal_loyalty/lottery/public_widgets_enabled | No | Permite renderizar widgets públicos de campañas activas con aprobación legal. |
| Lottery feature flag | kowal_loyalty/features/lottery | No | Feature flag para el área de sorteos. |
Recomendación: para promociones habituales use Gamification. Active Lottery solo para campañas que tengan términos propios, aprobación legal y 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:
| Campo | Significado |
|---|---|
| Enabled | Indica si la regla está activa. |
| Program ID | Programa al que se aplica la regla. En el MVP normalmente default. |
| Name | Nombre de la regla visible en la administración. |
| Description | Descripción auxiliar para el administrador. |
| Event Type | Evento por el que se acumulan puntos, por ejemplo compra, newsletter, referral. |
| Points Mode | Método de acumulación de puntos, por ejemplo valor fijo o valor dependiente del importe. |
| Points Value | Número de puntos o conversión utilizada por el modo seleccionado. |
| Priority | Orden de evaluación. Las reglas que coinciden con el evento se suman; la prioridad no detiene las reglas siguientes. |
| Related Landing Page Identifier | Identificador de la página CMS vinculada a la regla. |
| Website IDs | Lista de ID de website separados por comas. Un campo vacío significa todos los website. |
| Customer Group IDs | Lista de ID de grupos de clientes separados por comas. Un campo vacío significa todos los grupos. |
| From Date / To Date | Periodo de vigencia de la regla. |
Ejemplo de 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 acumular puntos según el valor del carrito de acuerdo con la base de la configuración Points Defaults.
Ejemplo de bonificación por newsletter: Event Type = newsletter_signup, Points Mode = fixed, Points Value = 50, periodo sin fecha de finalización. La regla acumula una bonificación única tras la suscripción del cliente a la newsletter si la integración de newsletter dispara el evento correspondiente.
Niveles de clientes
Los niveles se gestionan como entidades administrativas. El formulario de nivel contiene:
| Campo | Significado |
|---|---|
| Enabled | Indica si el nivel está activo. |
| Program ID | Programa al que se aplica el nivel. En el MVP normalmente default. |
| Name | Nombre del nivel, por ejemplo Silver, Gold, VIP. |
| Code | Código técnico del nivel. |
| Sort Order | Orden de los niveles. |
| Minimum Completed Purchase Amount | Valor mínimo de pedidos completados en los últimos 12 meses, sin envío. |
| Minimum Completed Orders | Número mínimo de pedidos completados. |
| Minimum Earned Points | Número mínimo de puntos obtenidos. |
| Bonus Multiplier | Multiplicador de bonificación. 1.25 significa una transacción de bonificación separada de +25% respecto a los puntos base. |
| Website IDs | Lista de ID de website separados por comas. Un campo vacío significa todos los website. |
Niveles predeterminados instalados como plantillas:
| Nivel | Umbral de compras | Multiplicador |
|---|---|---|
| Silver | 1000 | 1.25 |
| Gold | 3000 | 1.5 |
| VIP | 7500 | 2.0 |
Trate los valores predeterminados como punto de partida. Antes de producción, adapte los umbrales al valor medio del pedido, el margen y la frecuencia de compra.
Ejemplos de configuración
1. Programa de puntos sencillo para una tienda 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 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,Contentconfiguradas enYes.
Añada una regla de puntos por compra y pruebe todo el flujo: enrollment, pedido, acumulación 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 reduce 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: acumulación de 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.- Configure
Minimum Order Amountsegún el valor mínimo de pedido B2B, por ejemplo500. - Configure
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:
- Active las feature flags básicas del programa, puntos, reglas y checkout.
- Configure niveles, por ejemplo Silver, Gold, VIP.
- Configure
Bonus Multiplier:1.25,1.5,2.0. - Adapte los umbrales
Minimum Completed Purchase Amounta los datos de ventas.
La bonificación de nivel se guarda como una transacción separada en el ledger. Gracias a ello, los informes pueden separar los puntos base de los puntos de bonificación.
5. Campaña con ranking
Objetivo: mostrar un ranking público de clientes en una 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 tras la aceptación de las normas de privacidad.
Antes de publicar, revise el contenido de los términos, la política de privacidad y la forma de presentar los alias de los clientes.
6. Promoción Spin the Wheel sin sorteo
Objetivo: acción promocional controlada con recompensas sin mecanismo aleatorio.
Ajustes:
Gamification feature flag = Yes.Enable Gamification Mechanics = Yes.- No active
Lotterysi la promoción no es legalmente un sorteo. - Use una mecánica determinista o una secuencia predefinida de recompensas.
- Configure 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 permanecer controladas presupuestariamente y ser auditables.
7. Sorteo 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 tras preparar la campaña.- La campaña debe tener estado activo, website correcto y country scope, así como
legal_approval_status = approved. - Añada términos CMS separados y una landing page de campaña.
No use 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 website adecuados.
- Estado del programa configurado como activo.
- Términos del programa y términos de la tienda asignados a páginas CMS.
- Newsletter descrita claramente como condición para disfrutar de todos los derechos del programa.
- Reglas de puntos verificadas 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, caducidad y rankings.
- Rankings públicos y sorteos aprobados legalmente.
- REST API y GraphQL comprobados en cuanto al acceso solo a datos del cliente correspondiente.
- Importación de correcciones de puntos probada en cuanto a idempotencia.
Lugares útiles en el panel
Stores > Configuration > Kowal > Loyalty & Rewards- configuración principal del programa.Customers > Loyalty & Rewardso menú administrativoKowal Loyalty- participantes, ledger, correcciones manuales e informes, según los módulos activados.- CMS Pages - términos del programa, términos de la tienda y landing pages.
- Cart Price Rules - reglas de descuento utilizadas por 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, el checkout y el panel de administración. No deben editarse 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 separadas. La prioridad de la regla controla el orden y la legibilidad de la auditoría, no la detención de reglas posteriores.
Los puntos usados en el carrito se guardan en quote, se transfieren a order y se liquidan tras realizar el pedido. Las devoluciones y credit memo deben probarse para devoluciones completas y parciales, especialmente cuando la tienda usa puntos como descuento.