# Smart Bundle Engine: dokumentacja
> Prezentacja Smart Bundle Engine analizuje historię zamówień WooCommerce, aby wykryć produkty faktycznie kupowane razem, automatycznie generuje odpowiadające im zestawy i wyświetla je na karcie produktu, w koszyku i w e-mailu…
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfsmartbundle/index.md), [en](https://www.datafirefly.com/en/documentation/dfsmartbundle/index.md), [es](https://www.datafirefly.com/es/documentation/dfsmartbundle/index.md), [de](https://www.datafirefly.com/de/documentation/dfsmartbundle/index.md), [it](https://www.datafirefly.com/it/documentation/dfsmartbundle/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsmartbundle/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsmartbundle/index.md)
- Indeks:
## Prezentacja
Smart Bundle Engine analizuje historię zamówień WooCommerce, aby wykryć produkty faktycznie kupowane razem, automatycznie generuje odpowiadające im zestawy i wyświetla je na karcie produktu, w koszyku i w e-mailu po zakupie, z kontrolą marży, która w razie potrzeby automatycznie ogranicza rabat.
## Instalacja
1. Pobierz plik `df-smart-bundle.zip` ze swojego konta klienta DataFirefly.
2. W administracji WordPressa przejdź do **Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer**.
3. Wybierz ZIP, kliknij **Zainstaluj teraz** i włącz wtyczkę.
4. W pasku bocznym administracji pojawia się nowe menu **Smart Bundles**.
**Wymagania:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+. Zgodność z HPOS (High-Performance Order Storage) jest deklarowana natywnie.
Przy aktywacji wtyczka tworzy 4 dedykowane tabele (`df_sbe_cooccurrence`, `df_sbe_bundles`, `df_sbe_bundle_items`, `df_sbe_analysis_state`) i planuje crona analizy.
## Szybki start
1. Przejdź do **Smart Bundles → Analiza** i kliknij **Uruchom analizę teraz**.
2. Po zakończeniu analizy tabela **Najlepsze powinowactwa zakupowe** pokazuje wykryte pary wraz z metrykami (wystąpienia, ufność, lift).
3. Jeśli generowanie automatyczne jest włączone (domyślnie tak), zestawy tworzą się same: sprawdź je w **Smart Bundles → Zestawy**.
4. Odwiedź odpowiednią kartę produktu po stronie sklepu: blok „Często kupowane razem" pojawia się pod podsumowaniem produktu.
**Wskazówka:** analiza potrzebuje co najmniej kilkudziesięciu zamówień zawierających kilka produktów, aby dać użyteczne powinowactwa. Jeśli Twoja historia jest uboga, obniż tymczasowo próg minimalnych współwystąpień do 2 w ustawieniach.
## Analiza współwystąpień
Silnik przechodzi przez zamówienia **zrealizowane i w trakcie realizacji** w skonfigurowanym oknie analizy (domyślnie 180 dni), partiami po 200 zamówień. Dla każdego zamówienia zawierającego kilka produktów wyodrębniane i zliczane są wszystkie pary.
### Trzy metryki
- **Wystąpienia**: liczba zamówień zawierających parę A+B.
- **Ufność**: P(B|A) w procentach, czyli w jakim odsetku zamówień zawierających A występuje też B. Ufność 20 oznacza, że B pojawia się w 20 % zamówień zawierających A.
- **Lift**: stosunek zaobserwowanej częstości pary do częstości oczekiwanej, gdyby A i B były niezależne. Lift powyżej 1 wskazuje realne powinowactwo, powyżej 2 powinowactwo silne.
### Planowanie
Analiza działa automatycznie przez WP-Cron (hook `df_sbe_run_analysis`). Każde uruchomienie przetwarza do 25 partii po 200 zamówień, a następnie wznawia pracę przy kolejnym wyzwoleniu dzięki trwałemu kursorowi: żadne zamówienie nie jest przetwarzane dwa razy. Przycisk **Zresetuj stan** czyści tabele analizy i zaczyna od zera.
**Uwaga:** jeśli WP-Cron jest wyłączony na Twoim serwerze (`DISABLE_WP_CRON`), upewnij się, że cron systemowy regularnie wywołuje `wp-cron.php`, inaczej analiza uruchomi się wyłącznie ręcznie.
## Automatyczne generowanie zestawów
Po każdej pełnej analizie silnik wybiera pary przekraczające Twoje progi i tworzy odpowiadające im zestawy. Wyborem sterują trzy ustawienia:
- **Minimalne współwystąpienia** (domyślnie 3): minimalna liczba zamówień zawierających parę.
- **Minimalna ufność** (domyślnie 10 %): próg ufności, poniżej którego para jest pomijana.
- **Maksymalna liczba zestawów na produkt** (domyślnie 3): zapobiega przesyceniu jednego produktu.
Wybrane pary są sortowane według wyniku (lift × wystąpienia). Zestawy utworzone automatycznie otrzymują pochodzenie „Auto"; istniejące już zestawy z tymi samymi produktami nigdy nie są duplikowane. Zestawy ręczne są zawsze zachowywane przy ponownych analizach.
## Zarządzanie zestawami
Ekran **Smart Bundles → Zestawy** wymienia wszystkie zestawy z ich produktami, rabatem, minimalną marżą, kontekstami wyświetlania, wyświetleniami i konwersjami. Możesz filtrować po statusie, pochodzeniu (auto/ręczne) albo wyszukiwać swobodnie.
### Tworzenie albo edycja zestawu
1. Kliknij **Nowy zestaw** albo **Edytuj** przy istniejącym zestawie.
2. Wyszukaj i dodaj produkty (minimum 2): ilość każdej pozycji jest regulowana, a kolejność zmienia się przeciąganiem.
3. Ustaw rabat (procent albo kwota stała) i minimalną marżę.
4. Zaznacz pożądane konteksty wyświetlania: karta produktu, koszyk, e-mail.
5. **Priorytet** określa kolejność wyświetlania, gdy kwalifikuje się kilka zestawów (wyższy = pierwszy).
Przy istniejącym zestawie tabela **Podgląd wyceny** pokazuje na żywo sumę częściową, szacowany koszt, rabat żądany i zastosowany, cenę końcową oraz rzeczywistą marżę.
## Kontrola marży
Każdy zestaw ma próg **minimalnej marży** (w % ceny końcowej). Silnik wylicza odpowiadającą jej cenę minimalną:
```
cena_min_koncowa = koszt_calkowity / (1 − marza_min / 100)
```
Jeśli żądany rabat sprowadziłby cenę końcową poniżej tego progu, zostaje **automatycznie ograniczony** do maksymalnego zgodnego rabatu. Rabat pokazywany w sklepie jest więc zawsze bezpieczny.
### Źródło kosztu
Koszt każdego produktu ustalany jest w tej kolejności:
1. **Meta produktu**: domyślnie klucz `_df_cost_price`, konfigurowalny w ustawieniach (zgodny z Cost of Goods i innymi wtyczkami cen zakupu).
2. **Współczynnik zapasowy**: dla produktów bez wpisanego kosztu przyjmowany jest procent ceny sprzedaży (domyślnie 50 %).
**Wskazówka:** uzupełnij rzeczywiste koszty najpierw przy najlepiej sprzedających się produktach: ograniczanie marży będzie wtedy dokładne na zestawach, które liczą się najbardziej.
## Wyświetlanie w sklepie
### Karta produktu
Blok wstawia się na hooku `woocommerce_after_single_product_summary` z konfigurowalnym priorytetem (domyślnie 15, tuż przed produktami powiązanymi). Wyświetla miniatury produktów połączone znakami „+", przekreśloną sumę częściową, cenę zestawu i przycisk dodania jednym kliknięciem.
### Koszyk
Propozycje pojawiają się pod tabelą koszyka (`woocommerce_after_cart_table`). Zestawy, których wszystkie produkty są już w koszyku, są automatycznie ukrywane.
### E-mail po zakupie
Blok z propozycją wstawiany jest w e-maile **Zamówienie zrealizowane** i **Zamówienie w realizacji** (tylko do klientów), w wariantach HTML i tekstowym, z bezpośrednim linkiem powrotnym do sklepu.
Każdy kontekst można włączyć niezależnie, a jego tytuł jest konfigurowalny w ustawieniach.
## Stosowanie rabatu
Wtyczka nigdy nie zmienia cen produktów. Gdy zestaw zostanie dodany do koszyka, każda pozycja otrzymuje wewnętrzny znacznik; gdy tylko wszystkie pozycje zestawu są obecne, rabat stosowany jest jako **ujemna opłata** WooCommerce („Rabat zestawu"). Takie podejście:
- zachowuje ceny pozycji i raporty sprzedaży;
- pozostaje zgodne z podatkami, kosztami wysyłki i kodami rabatowymi;
- automatycznie usuwa rabat, jeśli pozycja zestawu zostanie usunięta z koszyka.
## Śledzenie wyników
Każde wyświetlenie zestawu zwiększa jego licznik **wyświetleń**; każde zamówienie zawierające kompletny zestaw zwiększa jego **konwersje** (przy przejściu w status „w realizacji" albo „zrealizowane", z zabezpieczeniem przed podwójnym liczeniem). Współczynnik konwersji per zestaw wyświetlany jest na liście zestawów, a ekran **Analiza** prezentuje statystyki globalne: przeanalizowane zamówienia, wykryte pary, aktywne zestawy oraz łączne wyświetlenia i konwersje.
## Przegląd ustawień
### Analiza współwystąpień
- **Okno analizy (dni)**: domyślnie 180. Zamówienia zrealizowane i w realizacji z tego okresu.
- **Minimalne współwystąpienia**: domyślnie 3.
- **Minimalna ufność (%)**: domyślnie 10.
- **Automatyczne generowanie zestawów**: domyślnie włączone.
- **Maksymalna liczba zestawów na produkt**: domyślnie 3.
### Wycena i marża
- **Rabat domyślny (%)**: 10, stosowany do zestawów generowanych automatycznie.
- **Domyślna marża minimalna (%)**: 20.
- **Klucz meta ceny zakupu**: `_df_cost_price`.
- **Zapasowy współczynnik kosztu (%)**: 50.
### Wyświetlanie
- **Konteksty**: karta produktu / koszyk / e-mail, włączane osobno.
- **Priorytet hooka karty produktu**: domyślnie 15.
- **Tytuły**: konfigurowalny tytuł dla każdego kontekstu.
## Wielojęzyczność
Wtyczka dostarczana jest z 5 językami (FR, EN, ES, DE, IT) w formacie `.po`/`.mo` plus plik `.pot` na własne tłumaczenia (textdomain `df-smart-bundle`). Zgodna z Polylangiem i WPML, wyświetlany język podąża za locale witryny albo użytkownika.
## Deinstalacja
Wyłączenie wtyczki po prostu usuwa zaplanowanego crona, a Twoje dane pozostają. **Usunięcie** wtyczki (przez Wtyczki → Usuń) uruchamia `uninstall.php`, który trwale kasuje 4 tabele, wszystkie opcje i metadane zamówień utworzone przez wtyczkę (zgodnie z HPOS).
## Rozwiązywanie problemów
### Nie generuje się żaden zestaw
- Sprawdź, czy analiza rzeczywiście zadziałała: **Smart Bundles → Analiza** powinna pokazywać liczbę przeanalizowanych zamówień większą od zera.
- Obniż progi (minimalne współwystąpienia, minimalna ufność), jeśli Twoja historia jest krótka.
- Sprawdź, czy automatyczne generowanie jest włączone w ustawieniach.
### Zestaw nie pojawia się w sklepie
- Zestaw musi być **aktywny**, a odpowiedni kontekst zaznaczony.
- Zestaw, którego wyliczony rabat wynosi zero (pełne ograniczenie marżą), jest ukrywany na karcie produktu.
- W koszyku zestaw już kompletny jest ukrywany celowo.
- Wyczyść cache stron, jeśli używasz wtyczki cache.
### Zastosowany rabat jest niższy niż skonfigurowany
To działanie ograniczenia marżą: całkowity koszt zestawu nie pozwala na żądany rabat bez zejścia poniżej minimalnej marży. Sprawdź koszty produktów albo skoryguj próg marży zestawu.
## FAQ
### Czy wtyczka działa z produktami wariantowymi?
Analiza i zestawy działają na poziomie produktu nadrzędnego. Warianty tego samego produktu liczone są razem.
### Czy mogę wykluczyć niektóre produkty z analizy?
Nie w wersji 1.0.0: po prostu usuń albo wyłącz niechciane zestawy; nie zostaną odtworzone, jeśli usuniesz je po wyłączeniu automatycznego generowania.
### Czy zestawy są zgodne z kodami rabatowymi?
Tak. Rabat zestawu to ujemna opłata niezależna od kuponów WooCommerce; oba się kumulują.
### Jaki jest wpływ na wydajność?
Analiza działa w tle partiami. Po stronie sklepu zapytania o zestawy są lekkie (indeksowane tabele), a zasoby ładowane wyłącznie na stronach produktów i koszyka.