# Predictive LTV i Churn: kompletna dokumentacja
> Kompletny przewodnik po wtyczce Predictive LTV i Churn dla WooCommerce: instalacja, konfiguracja dostawców e-mail marketingu, odczyt panelu, zrozumienie modelu predykcyjnego i automatycznej segmentacji RFM. Przegląd Predictive LTV i Churn to…
- Strona:
- Język: pl
- Zaktualizowano: 2026-10-10
- Inne języki: [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), [nl](https://www.datafirefly.com/nl/documentation/dfpredictivectvchurn/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfpredictivectvchurn/index.md)
- Indeks:
Kompletny przewodnik po wtyczce Predictive LTV i Churn dla WooCommerce: instalacja, konfiguracja dostawców e-mail marketingu, odczyt panelu, zrozumienie modelu predykcyjnego i automatycznej segmentacji RFM.
## Przegląd
**Predictive LTV i Churn** to wtyczka WooCommerce, która ocenia każdego klienta Twojego sklepu w dwóch wymiarach: przewidywanej wartości życiowej (Lifetime Value) i prawdopodobieństwa odejścia (churn). Na tej podstawie automatycznie przypisuje każdego klienta do jednego z 9 użytecznych biznesowo segmentów, a następnie synchronizuje te informacje do Brevo, Mailchimpa albo Klaviyo, aby precyzyjnie sterować kampaniami e-mailowymi.
Silnik inspirowany jest modelem BG/NBD używanym przez data scientistów, ale działa bez wstępnej konfiguracji: na bieżąco uczy się rzeczywistej bazy odniesienia Twojego sklepu (wskaźnik ponownych zakupów, średni koszyk, odstęp między zamówieniami), aby dawać rozsądne prognozy już od pierwszego zamówienia.
**Typowy przypadek użycia.** Klient składa pierwsze zamówienie. Wtyczka je wykrywa, natychmiast liczy przewidywaną LTV (z niską pewnością, ale użyteczną wartością), przypisuje go do segmentu „Nowy klient" i wysyła do Brevo z atrybutami DFPLC_PREDICTED_LTV i DFPLC_SEGMENT. Twoja automatyzacja w Brevo może wtedy uruchomić dopasowaną sekwencję powitalną.
## Instalacja
### Wymagania
- WordPress 6.2 lub nowszy
- WooCommerce 7.0 lub nowszy (testowane do 9.4)
- PHP 7.4 lub nowszy (zalecane 8.x)
- Klucz API do co najmniej jednego dostawcy spośród Brevo, Mailchimp albo Klaviyo
### Kroki instalacji
1. Pobierz plik ZIP `dfpredictivectvchurn.zip` ze swojego konta DataFirefly.
2. W administracji WordPressa przejdź do **Wtyczki > Dodaj nową wtyczkę > Wyślij wtyczkę na serwer**.
3. Wybierz ZIP i kliknij **Zainstaluj teraz**.
4. Kliknij **Włącz wtyczkę**.
5. Przy aktywacji wtyczka automatycznie tworzy w Twojej bazie 3 dedykowane tabele: `wp_dfplc_customer_scores`, `wp_dfplc_export_queue`, `wp_dfplc_baseline`.
Wtyczka formalnie deklaruje zgodność z High Performance Order Storage (HPOS) w WooCommerce przez `FeaturesUtil`. Bez bezpośredniego dostępu do tabel `wp_postmeta`, wszystko przechodzi przez `wc_get_orders()`.
## Pierwsze uruchomienie i wstępne scoringowanie
Po aktywacji Twój panel jest pusty: żaden klient nie został jeszcze oceniony. Masz dwie możliwości.
### Opcja 1: automatyczny scoring przyrostowy
Nie rób nic. Wtyczka będzie oceniać klientów stopniowo, wraz z kolejnymi zamówieniami. To najłagodniejsza droga przy dużych bazach.
### Opcja 2: wsteczny scoring całej historii
Przejdź do **Predictive LTV > Panel** i kliknij przycisk **Przelicz wszystkich klientów**. Wtyczka przejdzie przez historię zamówień partiami po 50 klientów, wyliczy każdy wynik, zaktualizuje bazę odniesienia sklepu i odświeży kwintyle RFM. Zależnie od wielkości bazy licz na:
- Poniżej 500 klientów: kilka sekund
- 500 do 5 000 klientów: od 30 sekund do 3 minut
- Powyżej 5 000 klientów: 5 do 15 minut (przetwarzanie trwa dalej w tle)
W sklepie z ponad 20 000 klientów zalecane jest tymczasowe wyłączenie opcji przeliczania w czasie rzeczywistym na czas wstępnego scoringu, aby uniknąć podwójnego obciążenia.
## Konfiguracja dostawców e-mail marketingu
Wtyczka obsługuje trzech dostawców jednocześnie. Możesz włączyć jednego, dwóch albo wszystkich trzech. Każdą konfigurację wykonasz w **Predictive LTV > Ustawienia**.
### Brevo (dawniej Sendinblue)
1. Zaloguj się na swoje konto Brevo i przejdź do **SMTP i API > API Keys**.
2. Utwórz klucz v3 z uprawnieniami co najmniej _Contacts_.
3. Utwórz dedykowaną listę (na przykład „DataFirefly LTV") i zanotuj jej numeryczny identyfikator.
4. We wtyczce wklej klucz API w **Klucz API Brevo**, a identyfikator listy w **Identyfikator listy Brevo**.
5. Kliknij **Testuj połączenie**, aby zweryfikować dane dostępowe.
Na każdym kontakcie Brevo tworzone będą automatycznie następujące atrybuty: `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. W Mailchimpie przejdź do **Account > Extras > API keys** i utwórz klucz.
2. Odszukaj **List ID** swojej listy odbiorców (w **Audience > Settings > Audience name and defaults**).
3. We wtyczce wklej klucz i identyfikator listy.
4. Kliknij **Testuj połączenie**.
Mailchimp ogranicza nazwy merge fields do 10 znaków. Wtyczka używa więc skróconych nazw: `DFPLTV` (przewidywana LTV), `DFCONF` (pewność), `DFCHURN` (churn), `DFSEG` (segment), `DFORDERS`, `DFSPENT`, `DFRFM` (złączenie R+F+M w trzy cyfry).
### Klaviyo
1. W Klaviyo przejdź do **Account > Settings > API Keys** i utwórz **Private API Key** z zakresami _Profiles: Full Access_ i _Lists: Full Access_.
2. Opcjonalnie: pobierz identyfikator listy (widoczny w adresie `/list/`), jeśli chcesz, aby wtyczka zapisywała kontakty do listy.
3. We wtyczce wklej klucz i ewentualnie identyfikator listy.
4. Kliknij **Testuj połączenie**.
## Zrozumieć model predykcyjny
### Prawdopodobieństwo, że klient jest wciąż aktywny
Wtyczka liczy `p_alive = exp(-days_since_last / expected_interval)`, gdzie `expected_interval` to średni odstęp między dwoma zamówieniami tego klienta (albo baza odniesienia sklepu, jeśli ma tylko jedno zamówienie). Ta formuła maleje wykładniczo: im więcej czasu minęło od ostatniego zamówienia, tym większe prawdopodobieństwo, że klient jest „stracony". Prawdopodobieństwo churnu to po prostu `(1 - p_alive) × 100`.
### Przewidywana LTV
Formuła brzmi: `predicted_ltv = total_spent + p_alive × expected_future_orders × avg_aov_customer`. Dla nowego klienta (tylko jedno zamówienie) wtyczka używa bazy odniesienia sklepu do oszacowania przyszłych zamówień. Dla klienta z wieloma zamówieniami ekstrapoluje jego osobiste tempo na horyzont roku.
### Pewność
Wskaźnik pewności łączy dwie składowe: jakość historii osobistej (im więcej zamówień, tym lepiej) i bogactwo bazy odniesienia sklepu (im więcej danych w sklepie, tym lepiej). Formuła waży `0,6 × history_score + 0,4 × baseline_score`.
Dla nowego klienta, którego pierwsze zamówienie ma mniej niż 30 dni, prawdopodobieństwo churnu jest neutralizowane w okolicach 50 %, aby uniknąć fałszywych alarmów. Żaden wiarygodny sygnał nie pozwala jeszcze stwierdzić, czy wróci.
## 9 segmentów biznesowych
Wtyczka przypisuje każdego klienta do dokładnie jednego segmentu, według logiki malejącego priorytetu. Progi korzystają z kwintyli RFM (percentyle 20, 40, 60, 80) liczonych na Twojej rzeczywistej bazie.
- **Champions**: klient z R ≥ 4, F ≥ 4 i M ≥ 4. Szczyt RFM, do utrzymania.
- **High-value at risk**: przewidywana LTV ≥ p80, ale R ≤ 3 i churn ≥ 40 %. Krytyczny sygnał alarmowy.
- **Churn risk**: churn ≥ 70 % i M ≥ 3. Wartościowy klient, który się oddala.
- **New customer**: 1 zamówienie i mniej niż 30 dni stażu.
- **Potential loyalist**: 2 zamówienia lub więcej, R ≥ 4. Blisko stania się lojalnym.
- **Loyal**: F ≥ 4, ale M ≤ 3. Regularny, ale z małym koszykiem.
- **Dormant**: R ≤ 2 i F ≥ 2. Kiedyś był dobry, już nie jest.
- **Lost**: R = 1 i churn ≥ 90 %. Stracony, prawdopodobnie na dobre.
- **Low value**: przewidywana LTV ≤ p25. Niski potencjał ekonomiczny.
Jeśli Twój sklep ma mniej niż 20 ocenionych klientów, segmentacja przechodzi w tryb „domyślny" i przypisuje po prostu _new_customer_ albo _loyal_ według liczby zamówień. Kwintyle są statystycznie istotne dopiero powyżej tego progu.
## Korzystanie z panelu administracyjnego
### Panel
Widok zbiorczy z czterema KPI: łączna liczba ocenionych klientów, średnia przewidywana LTV, średni wskaźnik churnu, rozmiar kolejki eksportu. Poniżej rozkład per segment wyświetlany jest kolorowymi słupkami wraz z legendą. Baza odniesienia sklepu widoczna jest na dole: wskaźnik ponownych zakupów, średni koszyk, średni odstęp między zamówieniami.
### Klienci
Stronicowana lista z filtrami per segment, sortowaniem po przewidywanej LTV, po churnie, po liczbie zamówień albo po dacie ostatniego zamówienia. Każdy wiersz pokazuje e-mail, segment (z kolorową plakietką), przewidywaną LTV, pewność, procent churnu, wynik RFM, liczbę zamówień, łączny obrót i datę ostatniego zamówienia.
### Eksporty
Panel dla każdego skonfigurowanego dostawcy, z dwoma akcjami: **Testuj połączenie**, aby zweryfikować dane dostępowe, oraz **Zsynchronizuj wszystkich klientów**, aby skolejkować całą bazę do danego dostawcy. Globalny przycisk **Przetwórz kolejkę** pozwala wymusić natychmiastowe przetworzenie (bez czekania na godzinny cron).
### Ustawienia
Konfiguracja ogólna (przeliczanie w czasie rzeczywistym, automatyczny eksport, segmenty do automatycznego eksportu, progi churnu i wysokiej wartości), a następnie panel dla każdego dostawcy z kluczem API i identyfikatorem listy.
## Zadania zaplanowane
Wtyczka planuje dwa zadania WP-Cron zaraz po aktywacji.
- `dfplc_daily_recalculation`: uruchamiane codziennie o 3:00. Przelicza bazę odniesienia sklepu, odświeża kwintyle RFM i ocenia ponownie do 500 klientów, których wynik jest starszy niż 24 godziny.
- `dfplc_hourly_export`: uruchamiane co godzinę. Zdejmuje 100 pozycji z kolejki eksportu i wypycha dane do skonfigurowanych dostawców. Pozycje zakończone błędem ponawiane są do 3 razy, zanim zostaną oznaczone jako ostatecznie nieudane.
Jeśli używasz crona systemowego (przez `wp-cron.php --disable_wp_cron`), upewnij się, że Twój harmonogram wywołuje WordPressa co najmniej raz na godzinę, w przeciwnym razie kolejka eksportu będzie się gromadzić.
## REST API
Wtyczka udostępnia kompletną przestrzeń nazw REST `dfplc/v1`, chronioną zdolnością `manage_woocommerce`. Nadaje się do zewnętrznych paneli, skryptów automatyzujących i dashboardów BI.
- `GET /wp-json/dfplc/v1/stats`: statystyki globalne (sumy, rozkład per segment, kolejka eksportu, baza odniesienia).
- `GET /wp-json/dfplc/v1/customers`: stronicowana lista ocenionych klientów z filtrami i sortowaniem.
- `POST /wp-json/dfplc/v1/recalculate`: uruchamia przeliczenie partiami.
- `POST /wp-json/dfplc/v1/exporter/{provider}/test`: testuje połączenie z dostawcą.
- `POST /wp-json/dfplc/v1/exporter/{provider}/sync-all`: kolejkuje całą bazę do dostawcy.
- `POST /wp-json/dfplc/v1/queue/process`: wymusza przetworzenie kolejki eksportu.
Uwierzytelnianie odbywa się przez nonce `wp_rest` przy wywołaniach z administracji WordPressa albo przez standardowe uwierzytelnianie REST WordPressa (Application Passwords, JWT i inne) przy wywołaniach zewnętrznych.
## Wielojęzyczność i tłumaczenia
Wtyczka dostarczana jest z pięcioma katalogami tłumaczeń: francuskim, angielskim, hiszpańskim, niemieckim i włoskim. Textdomain to `dfpredictivectvchurn`. Pliki `.po` znajdują się w katalogu `languages/`; możesz edytować je w Poedicie albo Loco Translate, aby dodać kolejne języki albo dostosować wybrane ciągi.
Loco Translate automatycznie generuje skompilowane pliki `.mo` przy każdym zapisie. To najprostsza metoda, jeśli nie czujesz się swobodnie w wierszu poleceń.
## Deinstalacja
Plik `uninstall.php` uruchamiany jest automatycznie przez WordPressa, gdy usuwasz wtyczkę z ekranu **Wtyczki**. Wykonuje następujące operacje:
- Usunięcie 3 własnych tabel (`dfplc_customer_scores`, `dfplc_export_queue`, `dfplc_baseline`)
- Usunięcie wszystkich opcji z przedrostkiem `dfplc_`
- Usunięcie transientu `dfplc_quintiles`
- Odplanowanie dwóch zadań WP-Cron
Po deinstalacji nie zostają żadne dane resztkowe.
## Rozwiązywanie problemów
### „Wyniki się nie aktualizują"
Sprawdź, czy WP-Cron jest aktywny (opcja `DISABLE_WP_CRON` niezdefiniowana w `wp-config.php`) albo czy cron systemowy regularnie wywołuje `wp-cron.php`. Możesz też wymusić ręczne przeliczenie z poziomu panelu.
### „Kolejka eksportu się gromadzi"
Przetestuj połączenie z każdym skonfigurowanym dostawcą. Jeśli klucz API wygasł albo został unieważniony, wywołania kończą się niepowodzeniem po cichu w cronie. Sprawdź kolumnę `last_error` w tabeli `wp_dfplc_export_queue`, aby ustalić dokładną przyczynę.
### „Moje liczby wyglądają niespójnie"
Upewnij się, że baza odniesienia została przeliczona po wstępnym scoringu. Jeśli zaimportowałeś dużą partię historycznych zamówień, wymuś pełne przeliczenie z panelu, aby odświeżyć wszystkie statystyki.
## Zasoby
- Wsparcie techniczne: [datafirefly.com/support](https://www.datafirefly.com/pl/wsparcie/)
- Kontakt handlowy: [contact@datafirefly.com](mailto:contact@datafirefly.com)
- Pełny changelog: zobacz kartę produktu