WP WordPress WordPress & WooCommerce Intermedio

Predictive LTV & Churn — Documentazione completa

Guida di installazione, configurazione e utilizzo del plugin di valutazione LTV predittiva e segmentazione RFM automatica per WooCommerce.

Aggiornato Versione del modulo 1.0.0

Guida completa al plugin Predictive LTV & Churn per WooCommerce: installazione, configurazione degli Email Service Provider, utilizzo del cruscotto, comprensione del modello predittivo e della segmentazione RFM automatica.

Panoramica

Predictive LTV & Churn è un plugin WooCommerce che valuta ogni cliente del tuo negozio su due dimensioni: il suo lifetime value previsto e la sua probabilità di abbandono (churn). Su questa base, classifica automaticamente ogni cliente in uno dei 9 segmenti business azionabili, quindi sincronizza queste informazioni verso Brevo, Mailchimp o Klaviyo per permetterti di guidare con precisione le tue campagne di email marketing.

Il motore si ispira al modello BG/NBD utilizzato dai data scientist, ma funziona senza configurazione preliminare: apprende continuamente la baseline reale del tuo negozio (tasso di riacquisto, valore medio del carrello, intervallo tra ordini) per fornire previsioni ragionevoli fin dal primo ordine.

Caso d’uso tipico. Un cliente effettua il suo primo ordine. Il plugin lo rileva, calcola immediatamente il suo LTV previsto (con confidenza bassa ma valore utile), lo assegna al segmento «Nuovo cliente» e lo invia a Brevo con gli attributi DFPLC_PREDICTED_LTV e DFPLC_SEGMENT. La tua automazione Brevo può quindi attivare una sequenza di benvenuto personalizzata.

Installazione

Requisiti

  • WordPress 6.2 o superiore
  • WooCommerce 7.0 o superiore (testato fino a 9.4)
  • PHP 7.4 o superiore (8.x consigliato)
  • Una chiave API per almeno un ESP tra Brevo, Mailchimp o Klaviyo

Passaggi di installazione

  1. Scarica il file ZIP dfpredictivectvchurn.zip dal tuo account DataFirefly.
  2. Nell’admin WordPress, vai in Plugin > Aggiungi nuovo > Carica plugin.
  3. Seleziona il ZIP e fai clic su Installa ora.
  4. Fai clic su Attiva plugin.
  5. All’attivazione, il plugin crea automaticamente 3 tabelle dedicate nel tuo database: wp_dfplc_customer_scores, wp_dfplc_export_queue, wp_dfplc_baseline.
Il plugin dichiara formalmente la sua compatibilità con l’High Performance Order Storage (HPOS) di WooCommerce tramite FeaturesUtil. Nessun accesso diretto alle tabelle wp_postmeta, tutto passa da wc_get_orders().

Primo avvio e valutazione iniziale

Subito dopo l’attivazione, il tuo cruscotto è vuoto: nessun cliente è ancora stato valutato. Hai due opzioni.

Opzione 1: valutazione incrementale automatica

Non fare nulla. Il plugin valuterà i clienti man mano che arrivano nuovi ordini. È la via più delicata per basi grandi.

Opzione 2: valutazione retroattiva della cronologia completa

Vai su Predictive LTV > Cruscotto e fai clic sul pulsante Ricalcola tutti i clienti. Il plugin scorrerà la tua cronologia di ordini a lotti di 50 clienti, calcolerà ogni punteggio, aggiornerà la baseline del negozio e poi rinfrescherà i quintili RFM. In base alla dimensione della tua base, conta:

  • Meno di 500 clienti: pochi secondi
  • Da 500 a 5.000 clienti: da 30 secondi a 3 minuti
  • Oltre 5.000 clienti: da 5 a 15 minuti (l’elaborazione continua in background)
Su un negozio con più di 20.000 clienti, si consiglia di disattivare temporaneamente l’opzione «ricalcolo in tempo reale» durante la valutazione iniziale per evitare il doppio carico.

Configurazione degli Email Service Provider

Il plugin supporta tre ESP simultaneamente. Puoi attivarne uno, due o tutti e tre. Ogni configurazione si fa in Predictive LTV > Impostazioni.

Brevo (ex Sendinblue)

  1. Accedi al tuo account Brevo, vai in SMTP & API > API Keys.
  2. Crea una chiave v3 con almeno i permessi Contacts.
  3. Crea una lista dedicata (ad esempio «DataFirefly LTV»), annota il suo ID numerico.
  4. Nel plugin, incolla la chiave API in Chiave API Brevo e l’ID lista in ID lista Brevo.
  5. Fai clic su Verifica la connessione per validare le credenziali.

I seguenti attributi verranno creati automaticamente su ogni contatto 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. In Mailchimp, vai in Account > Extras > API keys, crea una chiave.
  2. Individua il List ID della tua audience (in Audience > Settings > Audience name and defaults).
  3. Nel plugin, incolla la chiave e l’ID lista.
  4. Fai clic su Verifica la connessione.
Mailchimp limita i nomi dei merge fields a 10 caratteri. Il plugin utilizza quindi nomi accorciati: DFPLTV (LTV previsto), DFCONF (confidenza), DFCHURN (churn), DFSEG (segmento), DFORDERS, DFSPENT, DFRFM (concatenazione di R+F+M in 3 cifre).

Klaviyo

  1. In Klaviyo, vai in Account > Settings > API Keys, crea una Private API Key con gli scope Profiles: Full Access e Lists: Full Access.
  2. Opzionale: recupera l’ID della lista (visibile nell’URL /list/<LIST_ID>) se vuoi che il plugin iscriva i contatti.
  3. Nel plugin, incolla la chiave e opzionalmente l’ID lista.
  4. Fai clic su Verifica la connessione.

Comprendere il modello predittivo

La probabilità che il cliente sia ancora attivo

Il plugin calcola p_alive = exp(-days_since_last / expected_interval), dove expected_interval è l’intervallo medio tra due ordini di questo cliente (o la baseline del negozio se ha un solo ordine). Questa formula decresce esponenzialmente: più tempo passa dall’ultimo ordine, maggiore è la probabilità che il cliente sia «perso». La probabilità di abbandono è semplicemente (1 - p_alive) × 100.

L’LTV previsto

La formula è: predicted_ltv = total_spent + p_alive × expected_future_orders × avg_aov_customer. Per un cliente nuovo (un solo ordine), il plugin utilizza la baseline del negozio per stimare gli ordini futuri. Per un cliente con più ordini, estrapola il suo ritmo personale su un orizzonte di un anno.

La confidenza

Il punteggio di confidenza combina due componenti: la qualità della cronologia personale (più ordini ha il cliente, meglio è) e la ricchezza della baseline del negozio (più dati ha il negozio, meglio è). La formula pondera 0,6 × history_score + 0,4 × baseline_score.

Per un cliente nuovo il cui primo ordine ha meno di 30 giorni, la probabilità di abbandono viene neutralizzata intorno al 50 % per evitare falsi positivi. Nessun segnale affidabile permette ancora di dire se tornerà o meno.

I 9 segmenti business

Il plugin colloca ogni cliente in esattamente un segmento seguendo una logica di priorità decrescente. Le soglie utilizzano i quintili RFM (percentili 20, 40, 60, 80) calcolati sulla tua base reale.

  • Campioni: cliente con R ≥ 4, F ≥ 4 e M ≥ 4. Top RFM da fidelizzare.
  • Alto valore a rischio: LTV previsto ≥ p80 ma R ≤ 3 e churn ≥ 40 %. Segnale di allerta critico.
  • Rischio di abbandono: churn ≥ 70 % e M ≥ 3. Cliente di valore che si allontana.
  • Nuovo cliente: 1 ordine e meno di 30 giorni di anzianità.
  • Potenziale fedele: 2 o più ordini, R ≥ 4. Sul punto di diventare fedele.
  • Fedele: F ≥ 4 ma M ≤ 3. Ricorrente ma con carrello piccolo.
  • Inattivo: R ≤ 2 e F ≥ 2. È stato buono, non lo è più.
  • Perso: R = 1 e churn ≥ 90 %. Perso, probabilmente in modo definitivo.
  • Basso valore: LTV previsto ≤ p25. Basso potenziale economico.
Se il tuo negozio ha meno di 20 clienti valutati, la segmentazione passa in modalità «predefinita» e assegna semplicemente new_customer o loyal in base al numero di ordini. I quintili sono statisticamente significativi solo oltre questa soglia.

Utilizzo del cruscotto amministratore

Cruscotto

Vista sintetica con quattro KPI: numero totale di clienti valutati, LTV media prevista, tasso medio di abbandono, dimensione della coda di esportazione. Sotto, la distribuzione per segmento è visualizzata come barre colorate, con la legenda associata. La baseline del negozio è visibile in basso: tasso di riacquisto, valore medio del carrello, intervallo medio tra ordini.

Clienti

Lista paginata con filtri per segmento, ordinabile per LTV previsto, per churn, per numero di ordini o per data dell’ultimo ordine. Ogni riga mostra l’email, il segmento (con pillola colorata), l’LTV previsto, la confidenza, la percentuale di churn, il punteggio RFM, il numero di ordini, il totale speso e la data dell’ultimo ordine.

Esportazioni

Un pannello per ogni ESP configurato, con due azioni: Verifica la connessione per verificare le credenziali e Sincronizza tutti i clienti per mettere in coda l’intera base verso quell’ESP. Un pulsante globale Elabora la coda permette di forzare l’elaborazione immediata (senza aspettare il cron orario).

Impostazioni

Configurazione generale (ricalcolo in tempo reale, esportazione automatica, segmenti da auto-esportare, soglie di churn e di high-value) e poi un pannello per ESP con chiave API e ID lista.

Attività pianificate

Il plugin pianifica due attività WP-Cron fin dalla sua attivazione.

  • dfplc_daily_recalculation: gira ogni giorno alle 3:00 del mattino. Ricalcola la baseline del negozio, rinfresca i quintili RFM e ripunteggia fino a 500 clienti il cui punteggio ha più di 24 ore.
  • dfplc_hourly_export: gira ogni ora. Estrae 100 righe dalla coda di esportazione e invia i dati agli ESP configurati. Le righe fallite vengono ritentate fino a 3 volte prima di essere marcate come definitivamente fallite.
Se usi un cron di sistema (tramite wp-cron.php --disable_wp_cron), assicurati che la tua pianificazione chiami WordPress almeno una volta all’ora, altrimenti la coda di esportazione si accumulerà.

API REST

Il plugin espone un namespace REST completo dfplc/v1, protetto dalla capability manage_woocommerce. Utilizzabile per dashboard esterne, script di automazione o dashboard BI.

  • GET /wp-json/dfplc/v1/stats: statistiche globali (totali, distribuzione per segmento, coda di esportazione, baseline).
  • GET /wp-json/dfplc/v1/customers: lista paginata dei clienti valutati con filtri e ordinamento.
  • POST /wp-json/dfplc/v1/recalculate: avvia un ricalcolo a lotti.
  • POST /wp-json/dfplc/v1/exporter/{provider}/test: testa la connessione di un ESP.
  • POST /wp-json/dfplc/v1/exporter/{provider}/sync-all: mette in coda l’intera base verso un ESP.
  • POST /wp-json/dfplc/v1/queue/process: forza l’elaborazione della coda di esportazione.

L’autenticazione si fa tramite un nonce wp_rest per le chiamate dall’admin WordPress, o tramite autenticazione REST standard di WordPress (Application Passwords, JWT, ecc.) per le chiamate esterne.

Multilingua e traduzione

Il plugin è fornito con cinque cataloghi di traduzione: francese, inglese, spagnolo, tedesco e italiano. Il textdomain è dfpredictivectvchurn. I file .po si trovano in languages/; puoi modificarli con Poedit o Loco Translate per aggiungere altre lingue o personalizzare alcune stringhe.

Loco Translate genera automaticamente i file .mo compilati a ogni salvataggio. È il metodo più semplice se non sei a tuo agio con la riga di comando.

Disinstallazione

Il file uninstall.php viene attivato automaticamente da WordPress quando elimini il plugin dalla schermata Plugin. Esegue le seguenti operazioni:

  • Rimuove le 3 tabelle personalizzate (dfplc_customer_scores, dfplc_export_queue, dfplc_baseline)
  • Elimina tutte le opzioni con prefisso dfplc_
  • Elimina il transient dfplc_quintiles
  • Deprogramma le due attività WP-Cron

Nessun dato residuo rimane dopo la disinstallazione.

Risoluzione dei problemi

«I punteggi non si aggiornano»

Verifica che WP-Cron sia attivo (opzione DISABLE_WP_CRON non definita in wp-config.php) o che un cron di sistema chiami regolarmente wp-cron.php. Puoi anche forzare un ricalcolo manuale dal cruscotto.

«La coda di esportazione si accumula»

Testa la connessione di ogni ESP configurato. Se la chiave API è scaduta o revocata, le chiamate falliscono silenziosamente nel cron. Consulta la colonna last_error della tabella wp_dfplc_export_queue per identificare la causa esatta.

«I miei numeri sembrano incoerenti»

Assicurati che la baseline sia stata ricalcolata dopo la valutazione iniziale. Se hai importato un grosso lotto di ordini storici, forza un ricalcolo completo dal cruscotto per rinfrescare tutte le statistiche.

Risorse

Questa pagina ti è stata utile?

Ancora bloccato? Contatta l'assistenza