WhatsApp
+48608012047
Kowal Product Grid Category Filter para Magento 2
12,50 € 12,50 €
Instruções de instalação e configuração do Kowal Loyalty & Rewards Suite
Este documento descreve a instalação e a configuração básica do pacote kowal/metapackage-loyalty-suite em Magento 2. As instruções baseiam-se no código atual dos módulos, na configuração system.xml, nos valores predefinidos config.xml e na documentação do produto.
Requisitos
- Magento Open Source
2.4.9ou uma instalação Magento 2.4.x compatível. - PHP
^8.3. - Acesso à consola do servidor Magento.
- Cron Magento ativado.
- Pelo menos um website, store e store view configurados.
- Módulos Magento ativos utilizados pelo pacote, incluindo Customer, Sales, Quote, Checkout, CMS, Newsletter, SalesRule, Webapi, GraphQl, UI e ImportExport.
O pacote é instalado como um único root package Composer. Os módulos parciais encontram-se em packages/, mas a instalação padrão não exige que sejam instalados separadamente.
Instalação
No projeto Magento, execute:
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:flushApós a instalação, verifique se o cron Magento está a funcionar corretamente. O cron é necessário, entre outros, para ativar pontos pendentes, expirar pontos, enviar notificações e atualizar rankings.
Validação local do pacote
No repositório do pacote, pode executar:
./scripts/validate-local.shO script verifica ficheiros JSON, PHP, PHTML, XML, registos de módulos e schemas GraphQL básicos.
Local da configuração no painel Magento
A configuração principal encontra-se em:
Stores > Configuration > Kowal > Loyalty & RewardsA configuração é, na sua maioria, definida por website. Isto significa que o programa pode ser ativado para um website e permanecer desativado para outro.
General
| Campo | Caminho config | Predefinição | Significado |
|---|---|---|---|
| Enable Loyalty | kowal_loyalty/general/enabled | No | Ativa o programa de fidelização para o website selecionado. Sem isto, os módulos de domínio não devem tratar o cliente como participante de um programa ativo. |
| Debug Mode | kowal_loyalty/general/debug | No | Ativa diagnóstico adicional para o website selecionado. Utilize em staging ou na análise de problemas. |
| Log Retention Days | kowal_loyalty/general/log_retention_days | 30 | Tempo global de retenção de logs de fidelização em dias. |
Recomendação: em produção, defina Enable Loyalty = Yes apenas para o website onde o programa deve estar ativo. Mantenha Debug Mode como No, exceto se estiver a diagnosticar um problema específico.
Program
| Campo | Caminho config | Predefinição | Significado |
|---|---|---|---|
| Program ID | kowal_loyalty/program/program_id | default | Identificador interno do programa. O MVP assume um programa por website. Normalmente, mantenha default. |
| Program Name | kowal_loyalty/program/name | Loyalty & Rewards | Nome do programa visível para o cliente em widgets, landing page e painel da conta. |
| Short Description | kowal_loyalty/program/short_description | Earn points, unlock rewards and use them on future orders. | Descrição curta do programa utilizada na apresentação frontend. |
| Program Status | kowal_loyalty/program/status | draft | Estado do programa. Apenas um programa ativo é tratado como disponível para os clientes. |
| Program Visibility | kowal_loyalty/program/visibility | public | Controla a visibilidade do programa na camada storefront. |
| Program Terms CMS Page | kowal_loyalty/program/program_terms_cms_page | 0 | Página CMS com os termos do programa de fidelização. O link pode ser usado automaticamente por formulários e widgets. |
| Store Terms CMS Page | kowal_loyalty/program/store_terms_cms_page | 0 | Página CMS com os termos da loja, exigida especialmente no registo de convidado e na criação de conta. |
Recomendação: antes de ativar o programa publicamente, crie páginas CMS com os termos do programa e os termos da loja e depois atribua-as na configuração.
Points Defaults
| Campo | Caminho config | Predefinição | Significado |
|---|---|---|---|
| Default Points Expiration Days | kowal_loyalty/points/expiration_days | 365 | Número de dias de validade dos pontos contado a partir da data de ativação. |
| Default Rounding Mode | kowal_loyalty/points/rounding_mode | floor | Forma de arredondamento dos pontos: para baixo, padrão ou para cima. |
| Default Earning Amount Basis | kowal_loyalty/points/earning_amount_basis | base_row_total_incl_tax_after_discount | Base do valor da encomenda utilizada para atribuir pontos. O envio está sempre excluído. |
| Earn Points After Order Status | kowal_loyalty/points/earning_order_status | complete | Estado da encomenda após o qual são atribuídos pontos de compra. |
| Activate Pending Points After Order Status | kowal_loyalty/points/activation_order_status | complete | Estado da encomenda após o qual os pontos pendentes podem ficar disponíveis. |
| Activation Delay Days | kowal_loyalty/points/activation_delay_days | 0 | Atraso adicional na ativação dos pontos. 0 significa ativação sem atraso após o estado ser cumprido. |
| Expiration Notification Days | kowal_loyalty/points/expiration_notification_days | 30,7,1 | Limiares de notificação antes da expiração dos pontos, separados por vírgulas. |
Opções de Default Earning Amount Basis:
| Valor | Significado | Quando usar |
|---|---|---|
base_row_total_incl_tax_after_discount | Valor bruto após descontos | Variante B2C mais comum, o cliente ganha pontos sobre o valor dos produtos efetivamente pago. |
base_row_total_incl_tax_before_discount | Valor bruto antes de descontos | Quando as promoções de preço não devem reduzir o número de pontos ganhos. |
base_row_total_after_discount | Valor líquido após descontos | Para B2B ou lojas que calculam a fidelização sobre o valor líquido. |
base_row_total_before_discount | Valor líquido antes de descontos | Para programas calculados sobre o valor líquido de catálogo dos produtos. |
Recomendação: para uma loja B2C típica, mantenha Gross After Discounts, rounding_mode = floor, estados complete e validade dos pontos de 365 dias.
Point Redemption
| Campo | Caminho config | Predefinição | Significado |
|---|---|---|---|
| Points | kowal_loyalty/redemption/points | 100 | Número de pontos correspondente ao valor de desconto configurado. |
| Discount Amount | kowal_loyalty/redemption/base_amount | 10 | Valor de desconto na moeda base do website para o número de pontos indicado. |
| Minimum Points To Redeem | kowal_loyalty/redemption/min_points | 100 | Número mínimo de pontos que o cliente pode utilizar no carrinho. |
| Minimum Order Amount | kowal_loyalty/redemption/min_order_amount | 100 | Valor mínimo da encomenda que qualifica a utilização de pontos. O envio está excluído da base de validação. |
| Maximum Order Percent Paid With Points | kowal_loyalty/redemption/max_order_percent | 30 | Percentagem máxima do valor qualificado da encomenda que pode ser coberta por pontos. |
Exemplo: os valores Points = 100 e Discount Amount = 10 significam que 100 pontos dão 10 unidades da moeda base de desconto. Com Maximum Order Percent Paid With Points = 30, o cliente pode cobrir com pontos no máximo 30% do valor qualificado do carrinho.
Recomendação: no início, defina um limite conservador, por exemplo 20-30%, para que o programa não absorva toda a margem da encomenda.
Feature Flags
| Campo | Caminho config | Predefinição | Significado |
|---|---|---|---|
| Program | kowal_loyalty/features/program | Yes | Ativa a camada do programa e do contexto de website. |
| Rules | kowal_loyalty/features/rules | No | Ativa o suporte para regras de atribuição de pontos. |
| Points | kowal_loyalty/features/points | No | Ativa o ledger de pontos e a projeção de saldo. |
| Rewards | kowal_loyalty/features/rewards | No | Ativa os mecanismos de recompensas e utilização de pontos. |
| Checkout | kowal_loyalty/features/checkout | No | Ativa a integração com o carrinho e o checkout. |
| Content | kowal_loyalty/features/content | No | Ativa a camada de conteúdo, landing pages, widgets e blocos frontend. |
| Leaderboard | kowal_loyalty/features/leaderboard | No | Ativa o ranking de clientes, se o módulo estiver instalado. |
| Gamification | kowal_loyalty/features/gamification | No | Ativa mecânicas promocionais determinísticas. |
| Lottery | kowal_loyalty/features/lottery | No | Ativa o módulo de lotarias e jogos de azar. |
As feature flags permitem lançar o pacote por fases. Para a primeira configuração, normalmente ative: Program, Rules, Points, Rewards, Checkout e Content.
Leaderboard
| Campo | Caminho config | Predefinição | Significado |
|---|---|---|---|
| Enable Leaderboard | kowal_loyalty/leaderboard/enabled | No | Ativa a materialização de rankings através do cron. Mantenha desativado até à aceitação das regras de privacidade. |
| Allow Public Leaderboard Widgets | kowal_loyalty/leaderboard/public_enabled | No | Permite apresentar widgets públicos de rankings. Quando desativado, os widgets não renderizam o ranking público. |
| Default Metric | kowal_loyalty/leaderboard/default_metric | points | Métrica padrão do ranking: pontos, progresso de desafios, recomendações ou avaliações. |
| Default Widget Limit | kowal_loyalty/leaderboard/default_limit | 10 | Número de posições nos widgets. O código limita o valor a um máximo de 100. |
Recomendação: use rankings públicos apenas quando tiver uma política de privacidade e comunicação com o cliente aprovadas. Por predefinição, o módulo utiliza pseudónimos em vez de dados pessoais.
Gamification
| Campo | Caminho config | Predefinição | Significado |
|---|---|---|---|
| Enable Gamification Mechanics | kowal_loyalty/gamification/enabled | No | Ativa mecânicas promocionais determinísticas, por exemplo Spin the Wheel e Scratch & Win. |
| Gamification feature flag | kowal_loyalty/features/gamification | No | Feature flag para a área de gamificação. |
As mecânicas de gamificação não são uma verdadeira lotaria. A seleção de recompensas é determinística ou baseada numa sequência definida, o que facilita o controlo legal e orçamental.
Lotarias e jogos de azar
| Campo | Caminho config | Predefinição | Significado |
|---|---|---|---|
| Enable Lottery Module | kowal_loyalty/lottery/enabled | No | Ativa o módulo de lotaria. Mantenha desativado sem verificação legal prévia. |
| Allow Public Lottery Widgets | kowal_loyalty/lottery/public_widgets_enabled | No | Permite renderizar widgets públicos de campanhas ativas com aprovação legal. |
| Lottery feature flag | kowal_loyalty/features/lottery | No | Feature flag para a área de lotaria. |
Recomendação: para promoções comuns, use Gamification. Ative Lottery apenas para campanhas que tenham regulamento separado, aprovação legal e âmbito nacional em conformidade com a legislação.
Regras de pontos
As regras de pontos são geridas no painel administrativo do módulo. O respetivo formulário contém:
| Campo | Significado |
|---|---|
| Enabled | Indica se a regra está ativa. |
| Program ID | Programa ao qual a regra se aplica. No MVP, normalmente default. |
| Name | Nome da regra visível na administração. |
| Description | Descrição auxiliar para o administrador. |
| Event Type | Evento pelo qual os pontos são atribuídos, por exemplo compra, newsletter, referral. |
| Points Mode | Forma de atribuição de pontos, por exemplo valor fixo ou valor dependente do montante. |
| Points Value | Número de pontos ou conversão utilizada pelo modo selecionado. |
| Priority | Ordem de avaliação. As regras que correspondem ao evento acumulam-se; a prioridade não impede regras seguintes. |
| Related Landing Page Identifier | Identificador da página CMS associada à regra. |
| Website IDs | Lista de ID de website separados por vírgulas. Um campo vazio significa todos os website. |
| Customer Group IDs | Lista de ID de grupos de clientes separados por vírgulas. Um campo vazio significa todos os grupos. |
| From Date / To Date | Período de vigência da regra. |
Exemplo de regra de compra simples: Event Type = purchase, Points Mode = amount based, Points Value = 1, ativa para todos os grupos e apenas para o website selecionado. Isto significa atribuir pontos de acordo com o valor do carrinho, segundo a base da configuração Points Defaults.
Exemplo de bónus de newsletter: Event Type = newsletter_signup, Points Mode = fixed, Points Value = 50, período sem data de fim. A regra atribui um bónus único após a subscrição da newsletter pelo cliente, se a integração da newsletter acionar o evento adequado.
Níveis de clientes
Os níveis são geridos como entidades administrativas. O formulário de nível contém:
| Campo | Significado |
|---|---|
| Enabled | Indica se o nível está ativo. |
| Program ID | Programa ao qual o nível se aplica. No MVP, normalmente default. |
| Name | Nome do nível, por exemplo Silver, Gold, VIP. |
| Code | Código técnico do nível. |
| Sort Order | Ordem dos níveis. |
| Minimum Completed Purchase Amount | Valor mínimo de encomendas concluídas dos últimos 12 meses, sem envio. |
| Minimum Completed Orders | Número mínimo de encomendas concluídas. |
| Minimum Earned Points | Número mínimo de pontos ganhos. |
| Bonus Multiplier | Multiplicador de bónus. 1.25 significa uma transação de bónus separada de +25% face aos pontos base. |
| Website IDs | Lista de ID de website separados por vírgulas. Um campo vazio significa todos os website. |
Níveis predefinidos instalados como modelos:
| Nível | Limiar de compras | Multiplicador |
|---|---|---|
| Silver | 1000 | 1.25 |
| Gold | 3000 | 1.5 |
| VIP | 7500 | 2.0 |
Trate os valores predefinidos como ponto de partida. Antes da produção, ajuste os limiares ao valor médio da encomenda, à margem e à frequência de compra.
Exemplos de configuração
1. Programa de pontos simples para uma loja B2C
Objetivo: o cliente acumula pontos por compras e pode gastá-los no carrinho.
Definições:
Enable Loyalty = Yes.Program Status = active.Program Visibility = public.Program Terms CMS PageeStore Terms CMS Pageindicam páginas CMS corretas.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,Contentdefinidas comoYes.
Adicione uma regra de pontos por compra e teste todo o fluxo: enrollment, encomenda, atribuição de pontos, utilização de pontos no carrinho.
2. Programa com ativação diferida de pontos
Objetivo: os pontos só ficam disponíveis após o período de devolução.
Definições:
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.
Esta variante reduz o risco de o cliente gastar pontos antes do fim do período de devolução.
3. Programa B2B calculado sobre o valor líquido
Objetivo: atribuir pontos sobre o valor líquido dos produtos, sem envio e sem imposto.
Definições:
Default Earning Amount Basis = Net After Discounts.Default Rounding Mode = floor.- Defina
Minimum Order Amountde acordo com o valor mínimo de encomenda B2B, por exemplo500. - Defina
Maximum Order Percent Paid With Pointsde forma conservadora, por exemplo10ou20.
Esta variante faz sentido quando a fidelização deve ser calculada mais próxima da margem e do valor líquido faturado.
4. Programa VIP com níveis de clientes
Objetivo: os melhores clientes ganham pontos adicionais.
Definições:
- Ative as feature flags básicas do programa, pontos, regras e checkout.
- Configure níveis, por exemplo Silver, Gold, VIP.
- Defina
Bonus Multiplier:1.25,1.5,2.0. - Ajuste os limiares de
Minimum Completed Purchase Amountaos dados de vendas.
O bónus de nível é registado como uma transação separada no ledger. Com isto, os relatórios podem separar os pontos base dos pontos de bónus.
5. Campanha com ranking
Objetivo: apresentar um ranking público de clientes numa campanha.
Definições:
Leaderboard feature flag = Yes.Enable Leaderboard = Yes.Default Metric = points,challenge_progress,referralsoureviews.Default Widget Limit = 10ou outro valor razoável.Allow Public Leaderboard Widgets = Yesapenas após a aceitação das regras de privacidade.
Antes da publicação, verifique o conteúdo do regulamento, a política de privacidade e a forma de apresentação dos aliases dos clientes.
6. Promoção Spin the Wheel sem lotaria
Objetivo: ação promocional controlada com recompensas sem mecanismo aleatório.
Definições:
Gamification feature flag = Yes.Enable Gamification Mechanics = Yes.- Não ative
Lotteryse a promoção não for legalmente uma lotaria. - Use uma mecânica determinística ou uma sequência predefinida de recompensas.
- Defina limites de participação por cliente, e-mail, orçamento de pontos e número de prémios na configuração da mecânica.
Esta variante é adequada para ações de marketing que devem parecer apelativas, mas precisam de se manter controladas em termos de orçamento e auditáveis.
7. Lotaria ou jogo de azar
Objetivo: lançar uma campanha com um elemento aleatório real.
Definições:
Lottery feature flag = Yes.Enable Lottery Module = Yes.Allow Public Lottery Widgets = Yesapenas após a preparação da campanha.- A campanha deve ter estado ativo, website e country scope adequados e
legal_approval_status = approved. - Adicione um regulamento CMS separado e uma landing page da campanha.
Não use esta variante sem verificação legal para o país em que a loja opera.
Checklist antes da produção
- Programa ativado apenas para os website corretos.
- Estado do programa definido como ativo.
- Termos do programa e termos da loja atribuídos a páginas CMS.
- Newsletter descrita claramente como condição para direitos completos no programa.
- Regras de pontos testadas em staging.
- Limites de utilização de pontos calculados em relação à margem.
- Devoluções e credit memo testados manualmente.
- Cron Magento funciona e processa pontos pendentes, expiração e rankings.
- Rankings públicos e lotarias aprovados legalmente.
- REST API e GraphQL verificados quanto ao acesso apenas aos dados do cliente correto.
- Importação de correções de pontos testada quanto à idempotência.
Locais úteis no painel
Stores > Configuration > Kowal > Loyalty & Rewards- configuração principal do programa.Customers > Loyalty & Rewardsou o menu administrativoKowal Loyalty- participantes, ledger, correções manuais e relatórios, consoante os módulos ativados.- CMS Pages - termos do programa, termos da loja e landing pages.
- Cart Price Rules - regras de desconto utilizadas por recompensas com cupão.
Notas operacionais
O ledger de pontos é a fonte da verdade. A tabela de saldos é uma projeção para leituras rápidas no frontend, checkout e painel administrativo. Os saldos não devem ser editados manualmente sem uma transação no ledger.
As regras de pontos são cumulativas. Se várias regras ativas corresponderem ao evento, o cliente pode receber várias transações de pontos separadas. A prioridade da regra controla a ordem e a clareza da auditoria, não a paragem de regras seguintes.
Os pontos utilizados no carrinho são guardados na quote, transferidos para a order e reconciliados após a colocação da encomenda. Devoluções e credit memo devem ser testados para devoluções totais e parciais, especialmente quando a loja utiliza pontos como desconto.