# Predictive LTV & Churn: documentação completa

> 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…

- Página: <https://www.datafirefly.com/pt/documentation/dfpredictivectvchurn/>
- Idioma: pt
- Atualizado em: 2026-10-10
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfpredictivectvchurn/index.md), [en](https://www.datafirefly.com/en/documentation/dfpredictivectvchurn/index.md), [es](https://www.datafirefly.com/es/documentation/dfpredictivectvchurn/index.md), [de](https://www.datafirefly.com/de/documentation/dfpredictivectvchurn/index.md), [it](https://www.datafirefly.com/it/documentation/dfpredictivectvchurn/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfpredictivectvchurn/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfpredictivectvchurn/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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/`) 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

- Suporte técnico: [datafirefly.com/support](https://www.datafirefly.com/pt/centro-de-apoio/)
- Contacto comercial: [contact@datafirefly.com](mailto:contact@datafirefly.com)
- Changelog completo: ver a ficha de produto