# Dokumentacja Wyszukiwanie Bez Wyników: Strona Ratunkowa i Powiadomienia

> Kompletny przewodnik po module dfzerosearch: instalacja, konfiguracja, strona ratunkowa, korekta literówek, mapowanie utraconych zapytań, formularz „powiadom mnie" i rozwiązywanie problemów. PrestaShop 8 i 9.

- Strona: <https://www.datafirefly.com/pl/documentation/dfzerosearch/>
- Język: pl
- Zaktualizowano: 2026-10-08
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfzerosearch/index.md), [en](https://www.datafirefly.com/en/documentation/dfzerosearch/index.md), [es](https://www.datafirefly.com/es/documentation/dfzerosearch/index.md), [de](https://www.datafirefly.com/de/documentation/dfzerosearch/index.md), [it](https://www.datafirefly.com/it/documentation/dfzerosearch/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfzerosearch/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfzerosearch/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## Wprowadzenie

Moduł **Wyszukiwanie Bez Wyników** (`dfzerosearch`) przejmuje sytuację, gdy wyszukiwanie w sklepie niczego nie znajduje. Zamiast pustej strony odwiedzający widzi **stronę ratunkową**: cel wybrany przez Ciebie dla tego zapytania, produkty o referencji podobnej do wpisanej, poprawione wyszukiwanie, szersze wyszukiwanie, bestsellery odgadniętej kategorii oraz formularz „powiadom mnie”.

W panelu administracyjnym każde utracone wyszukiwanie jest liczone. Łączysz je z produktem, kategorią, innym wyszukiwaniem lub adresem URL, za pomocą reguły dokładnej, „zawiera” lub wieloznacznej. Moduł mierzy następnie, co przynoszą te ratunki: wskaźnik odzyskania, zamówienia i przychód netto.

**Nowość w 1.3.0:** blok **Similar references** (wyszukanie `M91650-0005` pokazuje `M91650-0001` i `M91650-0002`) oraz reguły **wieloznaczne** (`M91650*` obejmuje całą rodzinę referencji jedną regułą).

Interfejs modułu i e-maile są dostępne po angielsku, francusku, hiszpańsku, niemiecku i włosku. W sklepie po polsku moduł wyświetla wersję angielską, dlatego nazwy ustawień podajemy poniżej w tej wersji.

## Instalacja i aktualizacja

### Pierwsza instalacja

1. Otwórz **Moduły > Menedżer modułów** i kliknij **Załaduj moduł**.
2. Wybierz archiwum `dfzerosearch.zip`.
3. Moduł tworzy swoje tabele, menu administracyjne i domyślną konfigurację. Działa od razu.
4. Skopiuj adres URL zadania cron widoczny na stronie konfiguracji i uruchamiaj go co godzinę (patrz niżej).

### Aktualizacja z wcześniejszej wersji

Załaduj nowy plik ZIP na stary, bez odinstalowywania. PrestaShop uruchamia skrypty aktualizacji: nowe kolumny, nowe ustawienia z wartościami domyślnymi, wyczyszczenie pamięci podręcznej modułu. Utracone zapytania, reguły, subskrybenci i statystyki zostają zachowane.

Nie odinstalowuj modułu, aby go zaktualizować: odinstalowanie usuwa jego tabele, a więc całą historię.

## Konfiguracja

Strona **Konfiguruj** zaczyna się od skrótów do trzech ekranów modułu, po których następują trzy panele ustawień i panel zadania cron.

### Rescue page

- **Enable module**: włącza lub wstrzymuje wykrywanie i stronę ratunkową.
- **Typo correction ("Did you mean...")**: poprawia literówki słowo po słowie na podstawie indeksu wyszukiwania i pokazuje pasujące produkty.
- **Similar references**: dla referencji, której nie ma w katalogu, pokazuje produkty, których referencja zaczyna się tak samo. Myślniki, spacje i wielkość liter są ignorowane, uwzględniane są referencje kombinacji.
- **Partial match**: gdy długie zapytanie zawodzi przez jedno słowo („skórzane buty rozmiar 45”), pokazuje wyniki najbliższego krótszego zapytania.
- **Best sellers of the guessed category**: porównuje zapytanie z nazwami kategorii, łącznie z podkategoriami.
- **Global best sellers fallback**: wyświetlane tylko wtedy, gdy żaden inny blok niczego nie znalazł. Jeśli sklep nie ma jeszcze sprzedaży, używane są nowości.
- **"Notify me" form**: odwiedzający zostawia e-mail, aby dostać powiadomienie, gdy jego wyszukiwanie znajdzie produkt.
- **Use the theme product miniatures**: produkty wyglądają jak na stronach kategorii (dodaj do koszyka, szybki podgląd, etykiety). Po wyłączeniu moduł używa własnych kompaktowych kart.
- **In-stock products only**: ukrywa niedostępne produkty we wszystkich blokach.
- **Custom message** (dla każdego języka): tekst na górze strony ratunkowej, na przykład numer telefonu lub link do zamówień specjalnych. `%query%` jest zastępowane wyszukiwanymi słowami.
- **Popular searches**: klikalne etykiety z działającymi wyszukiwaniami. Wpisz własną listę dla każdego języka lub zostaw puste, aby używać częstych wyszukiwań z wynikami.
- **Products per block**: od 1 do 24 (domyślnie 8).

### Tracking and data

- **Minimum query length**: krótsze wyszukiwania nie są zapisywane ani ratowane (domyślnie 2).
- **Treat approximate-only results as lost**: natywne wyszukiwanie przybliżone PrestaShop często zwraca niezwiązane produkty dla nieznanego słowa. Gdy wyszukiwanie znajduje tylko takie wyniki, liczy się je jako utracone, a blok ratunkowy pojawia się nad nimi.
- **Ignore bots and crawlers**: wyszukiwania wyszukiwarek, narzędzi SEO i skryptów nie są zapisywane.
- **Attribution window (days)** (domyślnie 7): zamówienie złożone w tym czasie po ratunku jest przypisywane do zapytania i bloku, które przywróciły odwiedzającego (ostatni kontakt).
- **Cache rescue results**: przechowuje wynik pracy wyszukiwania przez 15 minut dla każdego zapytania. Ceny i stany magazynowe pozostają aktualne. Pamięć podręczna jest czyszczona przy każdej zmianie ustawienia lub reguły.
- **Retention (days)** (domyślnie 180): utracone zapytania niewidziane od tego czasu oraz subskrypcje już powiadomione są usuwane przez zadanie cron. 0 zachowuje wszystko. Przycisk pozwala usunąć dane od razu.

### Automation

- **Automatic notify-me emails**: subskrybenci dostają e-mail, gdy tylko ich zapytanie otrzyma aktywną regułę lub wyszukiwanie znów znajdzie produkty.
- **Weekly digest**: co 7 dni utracone wyszukiwania, wskaźnik odzyskania i najczęstsze utracone zapytania wysyłane e-mailem.
- **Digest recipient**: puste pole oznacza adres e-mail sklepu.

## Zadanie cron

Panel **Scheduled task (cron)** pokazuje adres URL chroniony tokenem. Wywołuj go co godzinę z cPanel, Plesk lub dowolnej usługi cron, na przykład:

```
0 * * * * curl -s "https://www.twoj-sklep.pl/module/dfzerosearch/cron?token=..." > /dev/null
```

Zadanie wysyła automatyczne powiadomienia, stosuje okres przechowywania i wysyła raport tygodniowy. Panel pokazuje datę ostatniego uruchomienia, przycisk **Run now** uruchamia zadanie ręcznie, a **Generate a new token** zastępuje adres URL, jeśli wyciekł. W trybie multistore ustaw osobne zadanie dla każdego sklepu z adresem widocznym w kontekście danego sklepu.

Jeśli zadanie nie działało od 48 godzin, w panelu pojawia się ostrzeżenie: automatyczne e-maile i raport tygodniowy czekają, aż zadanie znów się uruchomi.

## Strona ratunkowa

Gdy siatka wyników jest pusta, skrypt ładuje stronę ratunkową przez AJAX. Wyszukiwania, które znajdują produkty, nie są spowalniane. Bloki pojawiają się w tej kolejności, bez powtarzania produktów między blokami:

1. **Twoja reguła**: jeśli aktywna reguła pasuje do zapytania, jej cel jest wyróżniony. W trybie przekierowania odwiedzający trafia bezpośrednio na cel. Synonim dodatkowo pokazuje swoje produkty.
2. **Podobne referencje**: produkty z tej samej rodziny referencji.
3. **„Czy chodziło o...”**: poprawione zapytanie i jego produkty, z linkiem do poprawionego wyszukiwania. Ten blok pojawia się tylko wtedy, gdy poprzednie bloki niczego nie pokazały.
4. **Częściowe dopasowanie**: wyniki skróconego zapytania, tylko jeśli nic jeszcze nie znaleziono.
5. **Bestsellery odgadniętej kategorii**.
6. **Bestsellery sklepu**: wyłącznie w ostateczności.

Własny komunikat pojawia się nad blokami, popularne wyszukiwania i formularz „powiadom mnie” pod nimi.

## Podobne referencje

Wielu klientów szuka produktu po dokładnej referencji. Gdy tej referencji nie ma w katalogu, moduł proponuje produkty z tej samej rodziny.

- Moduł wyszukuje w zapytaniu słowo wyglądające na referencję: co najmniej 5 znaków, w tym co najmniej 2 cyfry.
- Porównuje je z referencjami produktów i kombinacji, ignorując myślniki, spacje, kropki i wielkość liter. `M91650-0005`, `m91650 0005` i `M916500005` są traktowane tak samo.
- Zachowywane są tylko produkty o wystarczająco długim wspólnym początku referencji (co najmniej 5 znaków i 60% szukanej referencji). Najbliższe pojawiają się jako pierwsze.
- Przykład: wyszukanie `M91650-0005` pokazuje `M91650-0001` i `M91650-0002`, ale nie `M91651-0003`.

Korekta literówek nigdy nie zmienia słowa zawierającego co najmniej 2 cyfry: referencja nie jest „poprawiana” na inną.

## Reguły: mapowania i synonimy

Ekran **Mappings & synonyms** wyświetla Twoje reguły. Aby utworzyć regułę, kliknij **Add a mapping** albo użyj akcji **Map** przy utraconym zapytaniu, która wstępnie wypełnia formularz.

### Typy dopasowania

- **Dokładne** (exact): zapytanie musi być identyczne z regułą. Wielkość liter, akcenty i nadmiarowe spacje są ignorowane.
- **Zawiera** (contains): reguła musi występować w zapytaniu jako słowo lub ciąg słów. Myślniki, ukośniki, kropki i inne separatory liczą się jako spacje: reguła `m91651` dotyczy `M91651-0003`.
- **Wieloznaczne** (wildcard): `*` zastępuje dowolny ciąg znaków, a `?` jeden znak. `M91650*` obejmuje `M91650-0001`, `M91650-0007` lub `m916500009`, ale nie `M91659-0001`. Każda reguła zawierająca `*` lub `?` jest automatycznie zapisywana jako wieloznaczna.

Reguła wieloznaczna wymaga co najmniej 3 znaków poza symbolami wieloznacznymi, a `**` jest odrzucane. Pisz `M91650*` zamiast `M91650-*`, jeśli klienci wpisują referencję także bez myślnika.

### Priorytety

Gdy do zapytania pasuje kilka reguł, wygrywa najdokładniejsza: reguła dokładna ma pierwszeństwo przed wieloznaczną, a ta przed regułą „zawiera”. Przy tym samym typie reguła dla konkretnego języka ma pierwszeństwo przed regułą „wszystkie języki”, a następnie wygrywa dłuższa reguła.

### Cele i tryby

- **Product**: wyszukiwanie po nazwie, referencji lub ID w formularzu.
- **Category**.
- **Synonym (other search)**: inne słowa, które dają wyniki („bluza” zamiast „sweter”). Produkty z tego wyszukiwania są pokazywane na stronie ratunkowej.
- **Custom URL**: bezwzględny adres URL lub ścieżka zaczynająca się od ukośnika.

Każda reguła działa w trybie **Suggest** (cel wyróżniony na stronie ratunkowej) lub **Redirect** (odwiedzający trafia bezpośrednio na cel). Reguła może dotyczyć jednego języka lub wszystkich.

## Import i eksport CSV

Panel **Import / export (CSV)** na ekranie reguł importuje do 5000 wierszy i eksportuje wszystkie reguły. Separator `;` lub `,`, wiersz nagłówka opcjonalny. Kolumny:

```
query ; match ; language ; type ; target ; mode ; active
M91650* ; wildcard ; all ; category ; 12 ; redirect ; 1
sweter ; exact ; pl ; search ; bluza ; suggest ; 1
M91651 ; contains ; all ; product ; M91651-0003 ; suggest ; 1
```

- **match**: `exact`, `contains` lub `wildcard` (domyślnie exact; wildcard wykrywany automatycznie, gdy reguła zawiera `*` lub `?`).
- **language**: kod ISO albo puste pole, `*` lub `all` dla wszystkich języków.
- **type**: `product`, `category`, `search` lub `url`.
- **target**: ID lub referencja produktu, ID kategorii, słowa do wyszukania lub URL.
- **mode**: `suggest` lub `redirect` (domyślnie suggest). **active**: 1 lub 0 (domyślnie 1).

Istniejąca reguła z tym samym zapytaniem i językiem jest aktualizowana. Raport importu podaje wiersze utworzone, zaktualizowane i odrzucone wraz z ich numerami.

## Powiadomienia „powiadom mnie”

Formularz na stronie ratunkowej ma domyślnie niezaznaczone pole zgody i ukryte pole-pułapkę przeciw botom. Dla zalogowanego klienta e-mail jest wypełniony automatycznie. Zgłoszenia są widoczne na ekranie **Notify-me requests** wraz ze statusem.

Przy działającym zadaniu cron i opcji **Automatic notify-me emails** subskrybent otrzymuje e-mail `dfzerosearch_alert` w swoim języku, gdy tylko jego zapytanie dostanie aktywną regułę lub wyszukiwanie znów znajdzie produkty. Możesz też wysłać go ręcznie akcją **Notify** przy regule. Każdy e-mail zawiera link do wypisania się.

## Panel i odzyskany przychód

Ekran **Lost queries** pokazuje dane z ostatnich 30 dni: utracone wyszukiwania, wskaźnik odzyskania, zamówienia po ratunku, odzyskany przychód netto, nowe subskrypcje i oczekujące e-maile. Jeden wykres porównuje dzień po dniu wyszukiwania utracone i odzyskane, drugi pokazuje kliknięcia w poszczególne bloki ratunkowe (reguła, podobne referencje, korekta, częściowe dopasowanie, kategoria, bestsellery, popularne wyszukiwania).

Lista utraconych zapytań jest posortowana według liczby wystąpień. Każdy wiersz oferuje **Map**, **Ignore / restore** oraz, gdy znaleziono korektę, **Create a synonym from this correction**. Tabela **Latest orders after a rescue** pokazuje przypisane zapytanie i blok.

Atrybucja według ostatniego kontaktu: zamówienie jest przypisywane do ostatniego ratunku tego samego odwiedzającego w oknie atrybucji ustawionym w konfiguracji.

## Raport tygodniowy

Co 7 dni zadanie cron wysyła e-mail `dfzerosearch_digest`: utracone wyszukiwania, odzyskani odwiedzający, wskaźnik odzyskania, zamówienia i przychód netto po ratunku, nowe zgłoszenia „powiadom mnie” oraz najczęstsze utracone zapytania. Jeśli w tygodniu nic się nie wydarzyło, e-mail nie jest wysyłany.

## RODO

- **Wyraźna zgoda**: pole domyślnie niezaznaczone i jasny tekst zgody.
- **Oficjalny moduł RODO**: moduł jest zarejestrowany w `psgdpr`. Eksport i usunięcie danych klienta obejmują jego zgłoszenia „powiadom mnie”.
- **Wypisanie**: link w każdym e-mailu.
- **Przechowywanie**: automatyczne usuwanie starych zapytań i powiadomionych subskrypcji.
- **Hosting własny**: żadne dane nie trafiają do zewnętrznych usług.

## Kompatybilność i informacje techniczne

- PrestaShop od 8.0 do 9.x, multistore.
- Interfejs i e-maile po angielsku, francusku, hiszpańsku, niemiecku i włosku.
- Hooki: `actionSearch`, `actionFrontControllerSetMedia`, `actionValidateOrder`, `registerGDPRConsent`, `actionDeleteGDPRCustomer`, `actionExportGDPRData`.
- Tabele: `dfzerosearch_query`, `dfzerosearch_mapping`, `dfzerosearch_alert`, `dfzerosearch_stat`, `dfzerosearch_session`, `dfzerosearch_conversion`.
- Menu `AdminDfZeroSearch` w sekcji Moduły, z trzema ekranami: utracone zapytania, mapowania i synonimy, zgłoszenia „powiadom mnie”.
- Kontrolery front: `rescue` (strona ratunkowa, JSON), `cron` (zadanie cron, token) i `unsubscribe`.
- Brak zależności: bez Composera, JavaScript bez jQuery, bez zewnętrznych usług.

## Rozwiązywanie problemów

- **Strona ratunkowa się nie pojawia**: sprawdź, czy moduł jest włączony i czy wyszukiwanie naprawdę zwraca zero wyników, a następnie wyczyść pamięć podręczną PrestaShop i przeglądarki. Przy mocno zmodyfikowanym motywie skontaktuj się z nami, podając nazwę motywu.
- **Wyszukiwanie pokazuje niezwiązane produkty i nie jest liczone jako utracone**: włącz **Treat approximate-only results as lost**.
- **Brak podobnych referencji**: szukane słowo musi mieć co najmniej 5 znaków, w tym 2 cyfry, a aktywne produkty widoczne w wyszukiwaniu muszą mieć ten sam początek referencji.
- **Reguła wieloznaczna nie działa**: sprawdź, czy jest aktywna, ustawiona na właściwy język i czy żadna reguła dokładna nie ma pierwszeństwa. Wypróbuj ją bez separatora (`M91650*`), jeśli klienci wpisują referencję na różne sposoby.
- **Brak proponowanej korekty**: korekta podpowiada tylko słowa obecne w indeksie; przebuduj indeks wyszukiwania PrestaShop, jeśli katalog bardzo się zmienił.
- **Automatyczne e-maile lub raport nie są wysyłane**: sprawdź datę ostatniego uruchomienia zadania cron i ustawienia e-mail PrestaShop. Przycisk Notify pokazuje jasny komunikat błędu, gdy wysyłka się nie powiedzie.
- **Panel pozostaje pusty**: sprawdź minimalną długość zapytania i testuj w zwykłej przeglądarce, ponieważ boty są ignorowane.