WP WordPress WordPress & WooCommerce Intermédio

Predictive LTV & Churn: documentação completa

Guia de instalação, configuração e utilização do plugin de pontuação de LTV preditiva e segmentação RFM automática para WooCommerce.

Atualizado Versão do módulo 1.0.0

Guia completo do plugin Predictive LTV & Churn para WooCommerce: instalação, configuração dos Email Service Providers, leitura do painel, compreensão do modelo preditivo e da segmentação RFM automática.

Visão de conjunto

O Predictive LTV & Churn é um plugin WooCommerce que pontua cada cliente da sua loja em duas dimensões: o seu valor de vida previsto (Lifetime Value) e a sua probabilidade de churn (perda). Com base nisso, classifica automaticamente cada cliente num de 9 segmentos de negócio acionáveis, e sincroniza depois estas informações com a Brevo, o Mailchimp ou o Klaviyo, para comandar as suas campanhas de e-mail com precisão.

O motor inspira-se no modelo BG/NBD usado pelos cientistas de dados, mas funciona sem configuração prévia: aprende em contínuo a linha de base real da sua loja (taxa de recompra, valor médio do carrinho, intervalo entre encomendas) para dar previsões razoáveis logo na primeira encomenda.

Caso de uso típico. Um cliente faz uma primeira encomenda. O plugin deteta-a, calcula de imediato a sua LTV prevista (com confiança baixa mas com valor útil), atribui-o ao segmento «Cliente novo» e envia-o à Brevo com os atributos DFPLC_PREDICTED_LTV e DFPLC_SEGMENT. A sua automação na Brevo pode então desencadear uma sequência de boas-vindas adaptada.

Instalação

Requisitos

  • WordPress 6.2 ou superior
  • WooCommerce 7.0 ou superior (testado até à 9.4)
  • PHP 7.4 ou superior (recomendado 8.x)
  • Uma chave de API de pelo menos um ESP entre Brevo, Mailchimp e Klaviyo

Etapas de instalação

  1. Descarregue o ficheiro ZIP dfpredictivectvchurn.zip a partir da sua conta DataFirefly.
  2. Na administração do WordPress, vá a Plugins > Adicionar plugin > Carregar plugin.
  3. Selecione o ZIP e clique em Instalar agora.
  4. Clique em Ativar plugin.
  5. Na ativação, o plugin cria automaticamente 3 tabelas dedicadas na sua base de dados: wp_dfplc_customer_scores, wp_dfplc_export_queue, wp_dfplc_baseline.
O plugin declara formalmente a sua compatibilidade com o High Performance Order Storage (HPOS) do WooCommerce através do FeaturesUtil. Sem acessos diretos às tabelas wp_postmeta: tudo passa pelo wc_get_orders().

Primeiro arranque e pontuação inicial

Depois da ativação, o seu painel está vazio: nenhum cliente foi ainda pontuado. Tem duas opções.

Opção 1: pontuação incremental automática

Não faça nada. O plugin vai pontuar os clientes à medida das novas encomendas. É a via mais suave para as bases grandes.

Opção 2: pontuação retroativa do histórico completo

Vá a Predictive LTV > Painel e clique no botão Recalcular todos os clientes. O plugin vai percorrer o seu histórico de encomendas em lotes de 50 clientes, calcular cada pontuação, atualizar a linha de base da loja e depois atualizar os quintis RFM. Consoante o tamanho da sua base, conte com:

  • Menos de 500 clientes: alguns segundos
  • 500 a 5000 clientes: 30 segundos a 3 minutos
  • Mais de 5000 clientes: 5 a 15 minutos (o processamento continua em segundo plano)
Numa loja com mais de 20 000 clientes, recomenda-se desativar temporariamente a opção «recálculo em tempo real» durante a pontuação inicial, para evitar a carga dupla.

Configuração dos Email Service Providers

O plugin suporta três ESP em simultâneo. Pode ativar um, dois ou os três. Cada configuração é feita em Predictive LTV > Definições.

Brevo (antiga Sendinblue)

  1. Inicie sessão na sua conta Brevo e vá a SMTP & API > API Keys.
  2. Crie uma chave v3 com, no mínimo, as permissões Contacts.
  3. Crie uma lista dedicada (por exemplo «DataFirefly LTV») e anote o seu ID numérico.
  4. No plugin, cole a chave de API em Chave de API Brevo e o ID da lista em ID de lista Brevo.
  5. Clique em Testar a ligação para validar as credenciais.

São criados automaticamente os seguintes atributos em cada contacto da Brevo: DFPLC_PREDICTED_LTV, DFPLC_LTV_CONF, DFPLC_CHURN_PROB, DFPLC_SEGMENT, DFPLC_TOTAL_ORDERS, DFPLC_TOTAL_SPENT, DFPLC_RFM_R, DFPLC_RFM_F, DFPLC_RFM_M, DFPLC_LAST_ORDER.

Mailchimp

  1. No Mailchimp, vá a Account > Extras > API keys e crie uma chave.
  2. Localize o List ID da sua audiência (em Audience > Settings > Audience name and defaults).
  3. No plugin, cole a chave e o ID da lista.
  4. Clique em Testar a ligação.
O Mailchimp limita os nomes dos merge fields a 10 carateres. O plugin usa por isso nomes abreviados: DFPLTV (LTV prevista), DFCONF (confiança), DFCHURN (churn), DFSEG (segmento), DFORDERS, DFSPENT, DFRFM (concatenação R+F+M em 3 dígitos).

Klaviyo

  1. No Klaviyo, vá a Account > Settings > API Keys e crie uma Private API Key com os scopes Profiles: Full Access e Lists: Full Access.
  2. Opcional: obtenha o ID da lista (visível no URL /list/<LIST_ID>) se quiser que o plugin subscreva os contactos.
  3. No plugin, cole a chave e, se for o caso, o ID da lista.
  4. Clique em Testar a ligação.

Compreender o modelo preditivo

A probabilidade de o cliente ainda estar ativo

O plugin calcula p_alive = exp(-days_since_last / expected_interval), em que expected_interval é o intervalo médio entre duas encomendas desse cliente (ou a linha de base da loja se ele tiver apenas uma encomenda). Esta fórmula decresce exponencialmente: quanto mais tempo passa desde a última encomenda, mais aumenta a probabilidade de ele estar «perdido». A probabilidade de churn é simplesmente (1 - p_alive) × 100.

A LTV prevista

A fórmula é: predicted_ltv = total_spent + p_alive × expected_future_orders × avg_aov_customer. Num cliente novo (uma única encomenda), o plugin usa a linha de base da loja para estimar as encomendas futuras. Num cliente com várias encomendas, extrapola o ritmo pessoal dele num horizonte de um ano.

A confiança

A pontuação de confiança combina duas componentes: a qualidade do histórico pessoal (quanto mais encomendas o cliente tiver, melhor) e a riqueza da linha de base da loja (quanto mais dados a loja tiver, melhor). A fórmula pondera 0,6 × history_score + 0,4 × baseline_score.

Num cliente novo cuja primeira encomenda tem menos de 30 dias, a probabilidade de churn é neutralizada em cerca de 50% para evitar falsos positivos. Ainda não há qualquer sinal fiável que permita dizer se vai voltar ou não.

Os 9 segmentos de negócio

O plugin classifica cada cliente em exatamente um segmento, segundo uma lógica de prioridade descendente. Os limiares usam os quintis RFM (percentis 20, 40, 60 e 80) calculados sobre a sua base real.

  • Champions: cliente com R ≥ 4, F ≥ 4 e M ≥ 4. Topo do RFM, a fidelizar.
  • High-value at risk: LTV prevista ≥ p80 mas R ≤ 3 e churn ≥ 40%. Sinal de alerta crítico.
  • Churn risk: churn ≥ 70% e M ≥ 3. Cliente com valor que se está a afastar.
  • New customer: 1 encomenda e menos de 30 dias de antiguidade.
  • Potential loyalist: 2 encomendas ou mais, R ≥ 4. Prestes a tornar-se leal.
  • Loyal: F ≥ 4 mas M ≤ 3. Regular, mas com carrinho pequeno.
  • Dormant: R ≤ 2 e F ≥ 2. Foi bom cliente, já não é.
  • Lost: R = 1 e churn ≥ 90%. Perdido, provavelmente em definitivo.
  • Low value: LTV prevista ≤ p25. Fraco potencial económico.
Se a sua loja tiver menos de 20 clientes pontuados, a segmentação passa ao modo «predefinido» e atribui simplesmente new_customer ou loyal conforme o número de encomendas. Os quintis só são estatisticamente significativos acima desse limiar.

Utilização do painel de administração

Painel

Vista sintética com quatro KPI: número total de clientes pontuados, LTV média prevista, taxa média de churn e tamanho da fila de exportação. Por baixo, a distribuição por segmento aparece em barras coloridas, com a legenda associada. A linha de base da loja fica visível em baixo: taxa de recompra, valor médio do carrinho e intervalo médio entre encomendas.

Clientes

Lista paginada com filtros por segmento e ordenação por LTV prevista, por churn, por número de encomendas ou por data da última encomenda. Cada linha mostra o e-mail, o segmento (com pastilha colorida), a LTV prevista, a confiança, a percentagem de churn, a pontuação RFM, o número de encomendas, o volume de negócios total e a data da última encomenda.

Exportações

Um painel por ESP configurado, com duas ações: Testar a ligação para verificar as credenciais, e Sincronizar todos os clientes para colocar toda a base em fila para esse ESP. Um botão global Processar a fila de espera permite forçar o processamento imediato (sem esperar pelo cron horário).

Definições

Configuração geral (recálculo em tempo real, exportação automática, segmentos a exportar automaticamente, limiares de churn e de alto valor) e depois um painel por ESP, com chave de API e ID de lista.

Tarefas agendadas

O plugin agenda duas tarefas WP-Cron logo na ativação.

  • dfplc_daily_recalculation: corre todos os dias às 3h00. Recalcula a linha de base da loja, atualiza os quintis RFM e volta a pontuar até 500 clientes cuja pontuação tenha mais de 24 horas.
  • dfplc_hourly_export: corre de hora a hora. Retira 100 linhas da fila de exportação e envia os dados para os ESP configurados. As linhas que falham são repetidas até 3 vezes antes de serem marcadas como definitivamente falhadas.
Se usar um cron de sistema (com o WP-Cron desativado), certifique-se de que o seu agendamento chama mesmo o WordPress pelo menos uma vez por hora, caso contrário a fila de exportação acumula-se.

API REST

O plugin expõe um namespace REST completo dfplc/v1, protegido pela permissão manage_woocommerce. Utilizável em painéis externos, scripts de automação ou dashboards de BI.

  • GET /wp-json/dfplc/v1/stats: estatísticas globais (totais, distribuição por segmento, fila de exportação, linha de base).
  • GET /wp-json/dfplc/v1/customers: lista paginada dos clientes pontuados, com filtros e ordenação.
  • POST /wp-json/dfplc/v1/recalculate: desencadeia um recálculo por lote.
  • POST /wp-json/dfplc/v1/exporter/{provider}/test: testa a ligação de um ESP.
  • POST /wp-json/dfplc/v1/exporter/{provider}/sync-all: coloca toda a base em fila para um ESP.
  • POST /wp-json/dfplc/v1/queue/process: força o processamento da fila de exportação.

A autenticação é feita através de um nonce wp_rest nas chamadas a partir da administração do WordPress, ou através da autenticação REST padrão do WordPress (Application Passwords, JWT, etc.) nas chamadas externas.

Multilingue e tradução

O plugin é entregue com cinco catálogos de tradução: francês, inglês, espanhol, alemão e italiano. O textdomain é dfpredictivectvchurn. Os ficheiros .po estão em languages/; pode editá-los com o Poedit ou o Loco Translate para acrescentar outros idiomas ou personalizar algumas cadeias.

O Loco Translate gera automaticamente os ficheiros .mo compilados a cada gravação. É o método mais simples se não estiver à vontade com a linha de comandos.

Desinstalação

O ficheiro uninstall.php é acionado automaticamente pelo WordPress quando elimina o plugin a partir do ecrã de Plugins. Executa as seguintes operações:

  • Eliminação das 3 tabelas personalizadas (dfplc_customer_scores, dfplc_export_queue, dfplc_baseline)
  • Eliminação de todas as opções com prefixo dfplc_
  • Eliminação do transiente dfplc_quintiles
  • Desagendamento das duas tarefas WP-Cron

Não fica qualquer dado residual depois da desinstalação.

Resolução de problemas

«As pontuações não se atualizam»

Verifique que o WP-Cron está ativo (constante DISABLE_WP_CRON não definida no wp-config.php) ou que um cron de sistema chama mesmo o wp-cron.php com regularidade. Também pode forçar um recálculo manual a partir do painel.

«A fila de exportação acumula-se»

Teste a ligação de cada ESP configurado. Se a chave de API tiver expirado ou sido revogada, as chamadas falham silenciosamente no cron. Consulte a coluna last_error da tabela wp_dfplc_export_queue para identificar a causa exata.

«Os meus números parecem incoerentes»

Certifique-se de que a linha de base foi mesmo recalculada depois da pontuação inicial. Se tiver importado um grande lote de encomendas históricas, force um recálculo completo a partir do painel para atualizar todas as estatísticas.

Recursos

Esta página foi útil?

Ainda com dúvidas? Contacte o suporte