Smart Loyalty Tiers: documentação completa

Introdução

O Smart Loyalty Tiers é um programa de fidelidade completo para WooCommerce. Ao contrário da maioria dos plugins de fidelidade, que se limitam a um simples contador de pontos nas compras, o Smart Loyalty Tiers propõe 5 fontes de ganho distintas, 4 níveis VIP progressivos com recompensas concretas (portes grátis vitalícios, acesso antecipado às novidades, apoio prioritário), um sistema de distintivos de gamificação, e a conversão dos pontos num cupão WooCommerce de utilização única.

Instalação e ativação

1. Descarregue o ficheiro ZIP smart-loyalty-tiers.zip a partir da sua área de cliente DataFirefly.
2. No WordPress, vá a Plugins → Adicionar plugin → Carregar plugin.
3. Selecione o ZIP e clique em Instalar agora.
4. Clique em Ativar.

Na ativação, o plugin cria automaticamente 9 tabelas na base de dados (prefixo wp_slt_), inicializa os 4 níveis Bronze / Silver / Gold / Platinum, insere 10 distintivos de conquista predefinidos, acrescenta o endpoint loyalty a A minha conta do WooCommerce, e agenda 2 tarefas cron (expiração diária, recálculo horário dos níveis).

Configuração em 3 minutos

Depois da ativação, aparece um novo menu Loyalty na barra lateral da administração com 5 subpáginas: Dashboard, VIP Tiers, Membros, Distintivos, Definições.

Etapa 1: taxa de ganho (Loyalty → Definições)

Ajuste os valores predefinidos conforme a sua estratégia:

• Pontos por euro gasto: por predefinição 1 (ou seja, 1 pt por 1 €)
• Pontos por avaliação de produto: por predefinição 50
• Pontos por apadrinhamento: por predefinição 500
• Pontos por inscrição na newsletter: por predefinição 100
• Pontos por partilha social: por predefinição 25

Etapa 2: conversão em cupão

• Taxa de conversão: por predefinição 100 pontos = 1 € de desconto
• Limiar mínimo de conversão: por predefinição 500 pontos
• Limite do cupão: por predefinição 30% do subtotal do carrinho

Etapa 3: apresentação e gamificação

• Designação dos pontos: por predefinição «pontos» (por exemplo: «milhas», «estrelas», «fireflies»)
• Gamificação ativa: ativa a sobreposição de celebração na subida de nível
• Notificações por e-mail: ativa os e-mails de subida de nível e de distintivo conquistado

Os 4 níveis VIP

Cada cliente é colocado automaticamente num nível em função do seu total de pontos acumulados ao longo da vida (pontos lifetime, independentemente do que gastou em cupões). Os níveis criados na ativação:

• Bronze: 0 pontos, sem benefícios especiais, nível de entrada
• Silver: 500 pontos acumulados, multiplicador ×1,25 nos pontos de compra, acesso antecipado de 12h
• Gold: 2000 pontos acumulados, multiplicador ×1,5, portes grátis, apoio prioritário, acesso antecipado de 24h
• Platinum: 5000 pontos acumulados, multiplicador ×2, portes grátis vitalícios, acesso antecipado de 48h, produtos exclusivos, 500 pontos de bónus de aniversário

A partir de Loyalty → VIP Tiers, cada nível é editável em direto com um seletor de cor. Os benefícios configuráveis:

• Multiplicador de pontos (points_multiplier): aplicado automaticamente a todos os pontos ganhos nas compras
• Portes grátis (free_shipping): as rates do WooCommerce são colocadas a zero no cálculo do carrinho
• Acesso antecipado em horas (early_access_hours): define quantas horas antes da data de embargo de um produto este nível o pode ver e comprar
• Apoio prioritário (priority_support): acrescenta um distintivo laranja nas encomendas na administração e um cabeçalho X-Priority nos e-mails transacionais
• Bónus de aniversário (birthday_bonus): pontos creditados automaticamente no dia de aniversário do cliente (se estiver indicado no perfil)
• Produtos exclusivos (exclusive_products): ativa a lógica de filtragem por nível nos produtos marcados como exclusivos

As 5 fontes de pontos

1. Compras (PurchaseAction)

Os pontos são creditados quando a encomenda passa ao estado concluída (woocommerce_order_status_completed). O cálculo:

pontos = subtotal sem IVA × pontos_por_euro × multiplicador_do_nível

O sistema é idempotente: é impossível ganhar duas vezes na mesma encomenda, mesmo que o estado oscile. Num reembolso total ou parcial, os pontos são automaticamente revertidos proporcionalmente ao montante reembolsado.

2. Avaliações de produto (ReviewAction)

Os pontos são creditados na publicação de uma avaliação validada (comment_post ou transition_comment_status → approved). Uma opção «Verificar que o cliente é comprador» permite limitar os ganhos às avaliações de compradores reais (proteção anti-spam).

3. Apadrinhamento (ReferralAction)

Cada utilizador recebe um código de apadrinhamento único e uma ligação de partilha. O seguimento faz-se por um cookie de 30 dias (duração configurável através de slt_referral_cookie_days). O padrinho ganha os pontos quando o afilhado conclui a primeira encomenda. É possível creditar ao afilhado um bónus de boas-vindas opcional.

4. Newsletter (NewsletterAction)

Dois modos de disparo:

• Caixa de seleção no checkout: tratada automaticamente se a caixa for assinalada
• Hook público: do_action('slt_newsletter_subscribed', $user_id, $email), que pode chamar a partir do Mailchimp, do Brevo, do MailPoet, do Klaviyo ou de qualquer outro sistema

Para um formulário nativo, use o shortcode [slt_newsletter_form].

5. Partilhas sociais (SocialShareAction)

7 plataformas suportadas através do shortcode [slt_share_buttons]: Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram e e-mail. Cada partilha é registada com um limite anti-abuso:

• Máximo de 5 partilhas por dia por utilizador (configurável)
• Uma mesma partilha (utilizador, plataforma, URL) só conta uma vez

As recompensas concretas

Portes grátis vitalícios

Nos níveis com free_shipping: true, todas as package rates do WooCommerce são colocadas a zero no cálculo do carrinho. Sem cupão para introduzir e sem manipulação. Aparece automaticamente um aviso verde no carrinho: «✨ Portes grátis, estatuto VIP».

Acesso antecipado às novidades

Em cada produto, uma metabox «Acesso antecipado Loyalty» permite definir uma data de embargo (_slt_embargo_until). Enquanto a data não for atingida, o produto fica:

• Não comprável para os níveis abaixo do limiar configurado (filtro woocommerce_is_purchasable)
• Invisível nas listagens (filtro woocommerce_product_query)

Os níveis com early_access_hours > 0 podem ver e comprar o produto na janela definida antes do levantamento público do embargo. Uma faixa âmbar na ficha de produto informa os clientes elegíveis.

Apoio prioritário

Nos níveis com priority_support: true, cada encomenda feita pelo cliente:

• Recebe um distintivo «Priority» laranja visível na lista de encomendas da administração (HPOS e legacy)
• Leva um cabeçalho X-Priority: high injetado nos e-mails transacionais, útil para filtrar no seu helpdesk (Zendesk, Freshdesk, Help Scout, etc.)

Sistema de distintivos (gamificação)

São criados 10 distintivos de conquista na ativação:

• First Purchase: primeira encomenda
• Regular Customer: 5 encomendas acumuladas
• Power Buyer: 10 encomendas acumuladas
• Reviewer: primeira avaliação publicada
• Critic: 10 avaliações publicadas
• Brand Ambassador: primeiro apadrinhamento bem-sucedido
• Influencer: 5 apadrinhamentos bem-sucedidos
• Social Butterfly: 10 partilhas sociais
• Insider: inscrição na newsletter
• Big Spender: 1000 € gastos ao longo da vida

A partir de Loyalty → Distintivos, edite os distintivos existentes ou crie novos. Cada distintivo tem um critério em JSON:

{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // para os triggers baseados em contagem
  "amount": 1000.00       // para lifetime_spend (montante na moeda)
}

Um distintivo pode também conceder um bónus de pontos no desbloqueio.

Conversão dos pontos em cupão

A partir de A minha conta → Loyalty, o cliente introduz o número de pontos a converter e clica em «Gerar cupão». O plugin:

1. Cria um objeto WC_Coupon único e de utilização única
2. Limita o cupão ao endereço de e-mail do cliente
3. Fixa uma expiração a 30 dias
4. Deduz os pontos do saldo e regista a transação

Um limite slt_max_redemption_percent (30% por predefinição) impede o cupão de ultrapassar uma percentagem do subtotal do carrinho, como proteção contra a diluição da margem.

Os 7 shortcodes do front-end

[slt_balance]

Apresenta o saldo de pontos do cliente com sessão iniciada. Atributo opcional: label="milhas".

[slt_balance label="fireflies"]

[slt_tier_badge]

Apresenta o nome do nível atual num distintivo colorido (cor do nível).

[slt_tier_badge]

[slt_progress_bar]

Barra de progresso animada para o nível seguinte, com o número de pontos em falta e um efeito shimmer.

[slt_progress_bar]

[slt_tiers_table]

Tabela comparativa de todos os níveis com os respetivos limiares e benefícios, ideal para uma página «Programa de fidelidade».

[slt_tiers_table]

[slt_referral_link]

Apresenta a ligação de apadrinhamento única do cliente, mais um botão de copiar e um contador de apadrinhamentos bem-sucedidos.

[slt_referral_link]

[slt_share_buttons]

Botões de partilha social. Atributos:

• url: URL a partilhar (por predefinição, o URL da página atual)
• title: título a partilhar (por predefinição, o título da página)
• platforms: lista separada por vírgulas (por predefinição, todas)

[slt_share_buttons platforms="facebook,twitter,whatsapp"]

[slt_newsletter_form]

Formulário de inscrição na newsletter com crédito automático dos pontos na subscrição.

[slt_newsletter_form title="Junte-se à nossa newsletter VIP"]

Área de cliente (A minha conta → Loyalty)

É acrescentado automaticamente um novo separador Loyalty a seguir ao painel de A minha conta do WooCommerce. O cliente encontra aí:

• Um bloco de destaque colorido com a cor do seu nível, o saldo e o estatuto
• A sua barra de progresso para o nível seguinte
• A lista dos benefícios atuais
• O formulário de conversão em cupão (se o saldo ultrapassar o limiar mínimo)
• A grelha de todos os distintivos (conquistados a cores, bloqueados a cinzento)
• O histórico completo de transações (as 25 últimas entradas por predefinição)

Painel de administração (Loyalty → Dashboard)

O painel de administração mostra estatísticas dos últimos 30 dias:

• Número total de membros e de membros ativos em 30 dias
• Pontos em circulação (soma dos saldos ativos)
• Pontos ganhos e trocados em 30 dias
• Apadrinhamentos concluídos em 30 dias
• Distribuição dos membros por nível (barras)
• Atividade recente (as 20 últimas transações de todos os membros)

A partir da página Membros, pode pesquisar um cliente, ver o seu saldo e o seu nível, e ajustar-lhe manualmente os pontos (atribuir ou deduzir) através de uma modal AJAX com justificação.

E-mails transacionais

São enviados automaticamente dois e-mails HTML responsivos:

Subida de nível

Enviado na passagem para um novo nível. Contém:

• Uma faixa com a cor do novo nível e um troféu
• A lista dos novos benefícios desbloqueados
• Um CTA para a área Loyalty

O template pode ser substituído copiando-o para o-seu-tema/smart-loyalty-tiers/emails/tier-upgrade.php.

Distintivo conquistado

Enviado no desbloqueio de um novo distintivo, com o nome, a descrição e o eventual bónus de pontos creditado.

Hooks para programadores

Cada ação do plugin dispara hooks que permitem estender sem tocar no código:

// Após o crédito de pontos
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// Após a dedução de pontos
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

// Mudança de nível
do_action('slt_tier_upgraded', $user_id, $new_tier, $old_tier);
do_action('slt_tier_downgraded', $user_id, $new_tier, $old_tier);

// Distintivo desbloqueado
do_action('slt_badge_awarded', $user_id, $badge);

// Apadrinhamento bem-sucedido
do_action('slt_referral_completed', $referrer_id, $referee_id, $order_id);

// Inscrição na newsletter (a disparar a partir da sua integração)
do_action('slt_newsletter_subscribed', $user_id, $email);

Compatibilidade com HPOS e com os blocos Cart / Checkout

O plugin declara automaticamente a compatibilidade HPOS através do FeaturesUtil::declare_compatibility(). Todas as leituras de encomenda passam pela API CRUD do WooCommerce (wc_get_order()), sem qualquer consulta direta a wp_posts.

A compatibilidade com os blocos Cart e Checkout também é declarada. Os portes grátis aplicam-se nos dois modos (clássico e blocos).

Multilingue (Polylang e WPML)

O plugin é totalmente traduzível através do load_plugin_textdomain com o textdomain smart-loyalty-tiers. O francês e o inglês são fornecidos, e está incluído um ficheiro POT completo para qualquer outro idioma.

Nos sites multilingues:

• Polylang Pro: os nomes dos níveis e dos distintivos podem ser traduzidos através da interface de String Translations do Polylang
• WPML: as mesmas cadeias são registadas com o WPML através do icl_register_string

FAQ e resolução de problemas

Um cliente não vê os pontos creditados depois de uma encomenda

Verifique que a encomenda está mesmo no estado concluída (o plugin não atribui pontos em «em processamento» ou «pendente»). Se o estado estiver correto, vá a Loyalty → Membros, procure o cliente e verifique o histórico.

Os portes não são oferecidos a um cliente Gold

Verifique em Loyalty → VIP Tiers que o benefício «Portes grátis» está mesmo assinalado no nível Gold. Limpe também as caches de sessão do WooCommerce (wc_clear_cart_cache()).

O endpoint A minha conta → Loyalty devolve um 404

Vá a Definições → Permalinks e clique em «Guardar alterações» para fazer flush às rewrite rules. É necessário apenas uma vez, depois da ativação.

O cron não dispara

Nos sites de baixo tráfego, o cron do WordPress pode ser irregular. Configure um verdadeiro cron de sistema para chamar o wp-cron.php a cada 5 a 15 minutos, e desative o pseudo-cron no wp-config.php:

define('DISABLE_WP_CRON', true);

Um cliente reclama pontos na sequência de um reembolso total

É o comportamento normal: num reembolso total ou parcial, os pontos correspondentes são deduzidos automaticamente. Se o cliente insistir, pode recreditar-lhe manualmente os pontos em Loyalty → Membros → Ajustar.

Como desativar a expiração dos pontos?

Em Loyalty → Definições, coloque a «Duração até à expiração» a 0 dias. Os pontos nunca serão eliminados.