Programa de fidelização Magento 2 - Kowal Loyalty & Rewards Suite

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. A instrução baseia-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.9 ou 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 submódulos encontram-se em packages/, mas a instalação padrão não requer a sua instalação separada.

Instalação

No projeto Magento, execute:

Receberá os dados de acesso ao repositório Composer, endereço de e-mail do cliente e token de licença, por e-mail após a compra. Também estão disponíveis no painel do cliente depois de iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do 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

Após a instalação, verifique se o cron Magento funciona 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.sh

O script verifica ficheiros JSON, PHP, PHTML, XML básicos, registos de módulos e esquemas GraphQL.

Local da configuração no painel Magento

A configuração principal encontra-se em:

Stores > Configuration > Kowal > Loyalty & Rewards

A configuração é, na maioria dos casos, definida por website. Isto significa que o programa pode ser ativado para um website e permanecer desativado para outro.

General

Recomendação: em produção, defina Enable Loyalty = Yes apenas para o website em que o programa deve estar ativo. Mantenha Debug Mode como No, a menos que esteja a diagnosticar um problema específico.

Program

Recomendação: antes de ativar publicamente o programa, crie páginas CMS com os termos do programa e os termos da loja e, em seguida, atribua-as na configuração.

Points Defaults

Opções de Default Earning Amount Basis:

Recomendação: para uma loja B2C típica, deixe Gross After Discounts, rounding_mode = floor, estados complete e validade dos pontos de 365 dias.

Point Redemption

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 elegível do carrinho.

Recomendação: para começar, defina um limite conservador, por exemplo 20-30%, para que o programa não absorva toda a margem da encomenda.

Feature Flags

As feature flags permitem lançar o pacote por etapas. Na primeira configuração, normalmente ative: Program, Rules, Points, Rewards, Checkout e Content.

Leaderboard

Recomendação: utilize rankings públicos apenas quando tiver uma política de privacidade aprovada e comunicação com o cliente. Por predefinição, o módulo utiliza pseudónimos em vez de dados pessoais.

Gamification

As mecânicas de gamificação não são uma verdadeira lotaria. A escolha das recompensas é determinística ou baseada numa sequência definida, o que facilita o controlo jurídico e orçamental.

Lotteries and Games of Chance

Recomendação: para promoções normais, utilize Gamification. Ative Lottery apenas para campanhas que tenham regulamento separado, aprovação jurídica 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:

Exemplo de uma 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 a atribuição de pontos segundo o valor do carrinho, de acordo com 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 final. A regra atribui um bónus único após a inscrição do cliente na newsletter, 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:

Níveis predefinidos instalados como modelos:

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 Page e Store Terms CMS Page apontam para 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, Content definidas como Yes.

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 ficam disponíveis apenas 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 = 14 ou 30.
• Default Points Expiration Days = 365.
• Expiration Notification Days = 30,7,1.

Esta variante limita 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 Amount de acordo com o valor mínimo de encomenda B2B, por exemplo 500.
• Defina Maximum Order Percent Paid With Points de forma conservadora, por exemplo 10 ou 20.

Esta variante faz sentido quando a fidelização deve ser contabilizada mais perto da margem e do valor líquido faturado.

4. Programa VIP com níveis de clientes

Objetivo: 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 Minimum Completed Purchase Amount aos dados de vendas.

O bónus de nível é guardado como uma transação separada no ledger. Isto permite que os relatórios separem os pontos base dos pontos de bónus.

5. Campanha com ranking

Objetivo: apresentar um ranking público de clientes na campanha.

Definições:

• Leaderboard feature flag = Yes.
• Enable Leaderboard = Yes.
• Default Metric = points, challenge_progress, referrals ou reviews.
• Default Widget Limit = 10 ou outro valor razoável.
• Allow Public Leaderboard Widgets = Yes apenas após a aprovaçã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 Lottery se a promoção não for juridicamente uma lotaria.
• Utilize 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 ganhos na configuração da mecânica.

Esta variante é adequada para ações de marketing que devem parecer apelativas, mas que precisam de permanecer 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 = Yes apenas após a preparação da campanha.
• A campanha deve ter estado ativo, website e country scope adequados, bem como legal_approval_status = approved.
• Adicione um regulamento CMS separado e uma landing page da campanha.

Não utilize esta variante sem verificação jurídica para o país em que a loja opera.

Checklist antes da produção

• Programa ativado apenas para os websites corretos.
• Estado do programa definido como ativo.
• Regulamento do programa e regulamento da loja atribuídos a páginas CMS.
• Newsletter descrita claramente como condição para direitos completos do programa.
• Regras de pontos verificadas em staging.
• Limites de utilização de pontos calculados em relação à margem.
• Devoluções e credit memo testados manualmente.
• Cron Magento em funcionamento e a processar pontos pendentes, expirações e rankings.
• Rankings públicos e lotarias aprovados juridicamente.
• 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 & Rewards ou menu administrativo Kowal Loyalty - participantes, ledger, correções manuais e relatórios, dependendo dos módulos ativados.
• CMS Pages - regulamentos do programa, regulamento da loja e landing pages.
• Cart Price Rules - regras de desconto utilizadas pelas recompensas por 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 legibilidade da auditoria, não a interrupção de regras seguintes.

Os pontos utilizados no carrinho são guardados na quote, transferidos para a order e liquidados após a submissã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.