# Inteligentne Live Search — Kompletny przewodnik
> Prezentacja i wymagania DFLiveSearch zastępuje natywne wyszukiwanie PrestaShop silnikiem live w AJAX: panel wyników otwiera się od pierwszych znaków, ze zdjęciem, marką, nazwą, ceną i promocyjnymi plakietkami każdego produktu. Moduł…
- Strona:
- Język: pl
- Zaktualizowano: 2026-09-08
- Inne języki: [fr](https://www.datafirefly.com/documentation/dflivesearch/index.md), [en](https://www.datafirefly.com/en/documentation/dflivesearch/index.md), [es](https://www.datafirefly.com/es/documentation/dflivesearch/index.md), [de](https://www.datafirefly.com/de/documentation/dflivesearch/index.md), [it](https://www.datafirefly.com/it/documentation/dflivesearch/index.md), [pt](https://www.datafirefly.com/pt/documentation/dflivesearch/index.md), [nl](https://www.datafirefly.com/nl/documentation/dflivesearch/index.md)
- Indeks:
## Prezentacja i wymagania
DFLiveSearch zastępuje natywne wyszukiwanie PrestaShop silnikiem live w AJAX: panel wyników otwiera się od pierwszych znaków, ze zdjęciem, marką, nazwą, ceną i promocyjnymi plakietkami każdego produktu. Moduł dodaje też inteligentny silnik wyszukiwania (marka, synonimy, tolerancja literówek, ważona trafność), karuzele sugestii (popularne wyszukiwania i polecane produkty), pełny dashboard analityczny oraz alerty e-mail dla wyszukiwań bez wyników.
- Kompatybilny z PrestaShop 8.0 do 9.x, motywem Classic i pochodnymi, motywem Warehouse (iqit).
- PHP 8.1 i nowszy.
- Multistore i wielojęzyczność (FR/EN/ES/DE/IT/PT).
- Żadnych override'ów plików: wyłącznie natywne hooki.
Moduł opiera się na hookach `displayHeader`, `displayTop`, `displaySearch`, `displayBackOfficeHeader` i `actionOrderStatusPostUpdate`. Tworzy sześć tabel: `dflivesearch_stats`, `dflivesearch_log`, `dflivesearch_alerts`, `dflivesearch_popular`, `dflivesearch_synonyms` i `dflivesearch_lexicon`.
## Instalacja
Zainstaluj moduł jak każdy moduł PrestaShop:
1. Pobierz archiwum `dflivesearch.zip` ze swojego konta klienta.
2. W back-office przejdź do **Moduły > Menedżer modułów**.
3. Kliknij **Zainstaluj moduł** i upuść archiwum.
4. Po instalacji kliknij **Konfiguruj**.
Przy instalacji moduł rejestruje hooki, tworzy tabele i wstępnie wypełnia tekst zachęty (placeholder) przetłumaczony na sześć języków. Kilka popularnych grup synonimów jest też wstępnie wypełnionych, a słownik korekty literówek budowany jest z Twojego katalogu. Pole wyszukiwania live jest od razu aktywne w sklepie.
## Aktualizacja
Aktualizacja przebiega normalnie z Menedżera modułów. Wbudowany skrypt upgrade'u tworzy nowe tabele, stosuje wartości domyślne nowych opcji (synonimy, trafność, tolerancja literówek, wyszukiwanie w marce, wygląd paska) bez naruszania istniejącej konfiguracji, a następnie odbudowuje słownik korekty. Żadna ręczna akcja nie jest wymagana. Po aktualizacji wyczyść cache PrestaShop i przegeneruj assety, aby usunąć stary JavaScript.
Po dużym imporcie katalogu pamiętaj o odbudowaniu słownika korekty (patrz sekcja „Inteligentne wyszukiwanie”), aby korekta literówek odzwierciedlała aktualny katalog.
## Konfiguracja ogólna
Strona konfiguracji grupuje ustawienia zachowania wyszukiwania:
- **Aktywuj moduł**: włącza lub wyłącza pole wyszukiwania live w sklepie.
- **Tekst zachęty (placeholder)**: tekst wyświetlany w polu, tłumaczony per język.
- **Minimalna liczba znaków**: próg uruchomienia wyszukiwania (domyślnie 2).
- **Maksymalna liczba produktów**: limit wyników wyświetlanych w panelu.
- **Pokaż ceny** i **pokaż rabaty**: sterują obecnością ceny i plakietki promocji na kartach wyników. Reguły PrestaShop obowiązują zawsze dodatkowo do tych ustawień (patrz „Wyświetlanie cen” poniżej).
- **Popularne wyszukiwania** i **ostatnie wyszukiwania**: wyświetlanie karuzel sugestii przed rozpoczęciem pisania.
- **Autouzupełnianie**: sugestie terminów (produkty, kategorie, marki, popularne wyszukiwania) podczas pisania, z nawigacją klawiaturą (strzałki góra/dół, Enter, Escape) i podświetlaniem wpisanego terminu. Maksymalna liczba sugestii jest konfigurowalna.
- **Szybkie dodanie do koszyka** i **selektor ilości**: opcje pozwalające dodać produkt bezpośrednio z wyników.
- **Produkty spersonalizowane**: uwzględnia historię zalogowanego klienta w automatycznych rekomendacjach.
## Wygląd
Sekcja **Wygląd** pozwala dopasować wyszukiwanie do Twojej identyfikacji wizualnej:
- **Kolor główny**: kolor przycisków i akcentów (domyślnie `#2196F3`).
- **Kolor główny (hover)**: kolor przy najechaniu na przyciski (domyślnie `#1976D2`).
- **Maksymalna szerokość okna**: maksymalna szerokość panelu wyszukiwania. Akceptuje wartość CSS jak `900px`, `1200px` lub `100%`.
- **Rozmiar paska wyszukiwania** (od wersji 1.4.0): Small, Medium lub Large. Dostosowuje wysokość, rozmiar tekstu i ikony paska w nagłówku.
- **Szerokość paska wyszukiwania**: maksymalna szerokość samego paska (`400px`, `50%`, `30rem`…). Zostaw puste, aby zajmował całą szerokość kontenera motywu.
- **Zaokrąglenie rogów paska**: od `0` (kąty proste) do `50` px (kształt pigułki).
- **Skrót klawiaturowy**: otwiera wyszukiwanie skrótem `Ctrl+K` (`Cmd+K` na Macu) lub klawiszem `/` z dowolnego miejsca strony. Na desktopie w pasku pojawia się plakietka („Ctrl K” lub „⌘K”). Opcja jest wyłączalna.
Te wartości są wstrzykiwane jako CSS na froncie. Dla paska w stylu „pigułki” jak w Algolii wybierz zaokrąglenie 50 i rozmiar Large. Dla okna na całą szerokość na mobile i desktopie wpisz `100%` w szerokości okna.
Od wersji 1.4.0 okno wyszukiwania jest w pełni dostępne z klawiatury: pasek jest fokusowalny i otwiera się Enterem lub Spacją, fokus pozostaje w oknie podczas nawigacji Tab, Escape zamyka okno i fokus wraca na pasek. Przycisk czyszczenia pojawia się w polu, gdy tylko wpisany jest tekst, a animacje respektują preferencję systemową `prefers-reduced-motion`.
## Zgodność z motywami i własne przyciski otwierania
Od wersji 1.5.0 okno wyszukiwania jest odłączane od nagłówka przy ładowaniu strony: działa nawet wtedy, gdy motyw ukrywa jego kontener (nagłówek desktopowy ukryty na telefonie) lub czyni go sticky. Współistnieją trzy sposoby otwierania wyszukiwarki:
- Pasek wyszukiwania modułu, wstawiany przez hooki `displayTop` lub `displaySearch`.
- Dowolny element Twojego motywu z klasą `dflivesearch-trigger` albo atrybutem `data-dflivesearch-trigger`: moduł automatycznie podpina do niego otwieranie wyszukiwarki (klik i klawiatura, z atrybutami ARIA).
- Natywne przyciski wyszukiwania motywu Warehouse (iqit): lupka nagłówka mobilnego (`#mobile-btn-search`) i desktopowego (`#iqit-search-btn`) otwierają bezpośrednio moduł, zamiast listy rozwijanej iqitsearch. Żadna modyfikacja szablonów nie jest wymagana.
Aby zintegrować wyszukiwarkę z innym motywem bez wyświetlania paska modułu, dodaj po prostu `data-dflivesearch-trigger` do istniejącego przycisku lupki w nagłówku.
## Polecane produkty
Polecane produkty wyświetlają się w karuzeli od razu po otwarciu pola wyszukiwania. Dostępne są dwa tryby przez ustawienie **Źródło polecanych produktów**:
- **Automatyczny**: moduł wybiera bestsellery (i uwzględnia historię klienta, jeśli opcja „Produkty spersonalizowane” jest włączona).
- **Ręczny**: sam wybierasz eksponowane produkty.
W trybie ręcznym pojawia się dedykowany selektor: wyszukaj produkt po nazwie lub referencji, kliknij, aby dodać, potem przestaw miniatury metodą przeciągnij i upuść. Zdefiniowana kolejność jest respektowana przy wyświetlaniu w sklepie.
Selektor proponuje tylko produkty aktywne i widoczne. Kolejność miniatur wyznacza kolejność w karuzeli.
## Zachowanie wyszukiwania
### Wyszukiwanie po słowach
Wyszukiwanie działa po słowach: każde wpisane słowo musi zostać znalezione (w nazwie, marce, referencji, kodzie EAN lub opisie skróconym), w dowolnej kolejności. Zapytanie jak „stetoskop pojedyncza głowica” znajdzie więc produkt, nawet jeśli te słowa nie sąsiadują w nazwie. Od wersji 1.2.0 każde słowo jest też rozszerzane o synonimy, a wyszukiwanie obejmuje referencje wariantów (patrz sekcja „Inteligentne wyszukiwanie”).
### Produkty z wariantami
Dla produktu z wariantami przycisk dodania do koszyka jest zastępowany przyciskiem **„Zobacz opcje”**, który prowadzi do karty produktu, aby klient wybrał wariant przed dodaniem. Gdy klient wyszukał dokładną referencję wariantu, przycisk prowadzi bezpośrednio do danej wariacji.
### Dostępność i stan magazynowy
Produkty wyprzedane pozostają w wynikach z plakietką „Brak w magazynie”. Plakietka nie pojawia się dla produktów z dozwolonym zamawianiem mimo braku (ustawienie „Przyjmuj zamówienia” PrestaShop): te wciąż można dodać do koszyka.
Jeśli wpiszesz ilość większą niż dostępny stan produktu niezamawialnego bez pokrycia, moduł nie doda produktu i wyświetli komunikat z pozostałą ilością.
### Wyświetlanie cen
Od wersji 1.5.0 moduł stosuje reguły wyświetlania cen PrestaShop, dodatkowo do własnego ustawienia „Pokaż ceny”:
- **Tryb katalogu** (Preferencje > Produkty): w wynikach nie pojawia się żadna cena ani przycisk koszyka.
- **Grupy klientów**: jeśli grupa odwiedzającego ma wyłączoną opcję „Pokaż ceny” (częsty przypadek w B2B dla niezalogowanych), ceny są ukrywane.
- **Opcja produktu**: produkt z odznaczoną opcją „Pokaż cenę” na karcie nie pokazuje ani ceny, ani rabatu.
We wszystkich tych przypadkach przycisk dodania do koszyka jest również usuwany, a dodawanie jest odrzucane po stronie serwera: klient jest przekierowywany na kartę produktu. Ustawienie „Pokaż rabaty” ukrywa przekreśloną cenę i plakietkę rabatu, nie ruszając ceny bieżącej.
## Inteligentne wyszukiwanie: marka, synonimy, literówki i trafność
Od wersji 1.2.0 DFLiveSearch zawiera inteligentny silnik wyszukiwania. Wszystkie te ustawienia znajdują się w sekcji **Inteligentne wyszukiwanie** strony konfiguracji.
### Wyszukiwanie w marce
Od wersji 1.5.0 opcja **„Wyszukuj w nazwie marki”** (domyślnie włączona) odpytuje również producenta produktu. Zapytanie jak „Littmann stetoskop” znajduje właściwy produkt, nawet gdy marka nie jest częścią jego nazwy: każde słowo jest szukane w nazwie, opisie skróconym, kodach i marce. Marka jest wyświetlana na kartach wyników, nad nazwą produktu, a nazwy marek są podpowiadane w autouzupełnianiu. Dokładne dopasowanie marki jest oceniane wyżej niż częściowe dopasowanie nazwy.
Braną pod uwagę marką jest **producent** przypisany do produktu (Katalog > Marki i dostawcy). Wypełniaj to pole na kartach produktów, zamiast powtarzać markę w nazwie produktu.
### Synonimy
Słownik synonimów łączy równoważne terminy: klient szukający „tv” znajdzie też produkty nazwane „telewizja” lub „telewizor”. Edytor jest wielojęzyczny (zakładka na język). Wpisz **jedną grupę na linię**, terminy rozdzielone przecinkami:
```
tv, telewizja, telewizor
komputer, pc, laptop
sluchawki, headphones
```
Wszystkie terminy z tej samej linii są uznawane za równoważne: wyszukanie jednego z nich automatycznie rozszerza zapytanie na pozostałe. Włączaj lub wyłączaj funkcję opcją **Włącz synonimy**. Kilka popularnych grup jest wstępnie wypełnionych przy instalacji; dostosuj je do katalogu.
Synonimy są przechowywane per sklep i per język. Pamiętaj o wypełnieniu każdej zakładki językowej, aby objąć całą klientelę.
### Tolerancja literówek
Gdy wyszukiwanie nie zwraca wyników, moduł automatycznie próbuje skorygować błąd na podstawie słownika zbudowanego z Twojego katalogu (nazwy produktów, referencje, marki, kategorie). Jeśli korekta daje wyniki, są one wyświetlane od razu z adnotacją **„Wyniki dla…”** i linkiem powrotu do pierwotnej pisowni.
- **Tolerancja literówek**: włącza lub wyłącza automatyczną korektę.
- **Maksymalna odległość korekty**: maksymalna liczba różniących się znaków (1 do 3; zalecane 2). Wyższa wartość koryguje więcej błędów, ale zwiększa ryzyko fałszywych trafień.
- **Pokaż „Czy chodziło Ci o?”**: wyświetla baner korekty. Wyłączona, korekta działa po cichu.
Korekta opiera się na wstępnej selekcji fonetycznej (SOUNDEX), po której następuje obliczenie odległości Levenshteina: odnajduje np. „telewizor” z „telewisor”. Słowa krótsze niż trzy znaki nie są korygowane; krótkie równoważności (jak „tv”) należą do synonimów.
### Słownik korekty
Słownik korekty (tabela `dflivesearch_lexicon`) jest budowany przy instalacji, a potem może być odbudowany w każdej chwili przyciskiem **Odbuduj słownik** na stronie konfiguracji. Strefa informacyjna pokazuje liczbę zaindeksowanych słów i datę ostatniej odbudowy. Od wersji 1.5.0 indeksowane są także nazwy marek, obok nazw produktów, referencji i kategorii.
Odbuduj słownik po dużym imporcie katalogu lub masowej zmianie nazw produktów, aby korekta literówek odzwierciedlała aktualny katalog. Możesz też zautomatyzować odbudowę zadaniem planowanym.
### Trafność wyników
Wyniki są sortowane ważonym wskaźnikiem trafności: dokładne dopasowanie nazwy (najwyższy wynik), nazwa zaczynająca się od zapytania, dokładna marka, zapytanie zawarte w nazwie, częściowa marka, potem referencja i EAN. Dwa boosty uzupełniają ranking:
- **Boost produktów w magazynie**: przy porównywalnej trafności produkty dostępne wskakują na górę listy.
- **Boost bestsellerów**: faworyzuje najlepiej sprzedające się produkty na podstawie statystyk sprzedaży PrestaShop.
Obie opcje włącza się niezależnie w sekcji **Inteligentne wyszukiwanie**.
### Wyszukiwanie po referencji wariantu
Wyszukiwanie obejmuje identyfikatory właściwe wariantom: **referencję, EAN, UPC i referencję dostawcy** każdej wariacji. Wpisanie referencji lub kodu kreskowego wariantu wywołuje produkt nadrzędny. Gdy zapytanie przypomina kod, wynik wskazuje bezpośrednio właściwy wariant (link do dokładnej wariacji), a karta pokazuje referencję i cenę tej wariacji.
Referencje czysto literowe (bez cyfry) pozostają znajdowalne, ale otwierają kartę na wariancie domyślnym. Referencje zawierające cyfry (EAN, większość SKU) uruchamiają bezpośredni link do dokładnego wariantu.
## Dashboard i statystyki
Moduł rejestruje każde wyszukiwanie (wpisany termin, liczba wyników, ewentualny klik na produkt, konwersja w zamówienie). Dashboard back-office prezentuje:
- łączną liczbę wyszukiwań i liczbę wyszukiwań unikalnych;
- wskaźniki sukcesu, kliknięć i konwersji;
- wykres ewolucji wyszukiwań per dzień;
- top 20 wyszukiwań z klikami i konwersjami;
- top 20 wyszukiwań bez wyników;
- eksport CSV całości danych.
Śledzenie konwersji odbywa się przez hook `actionOrderStatusPostUpdate`: zamówienie złożone po kliku w wynikach wyszukiwania jest liczone jako skonwertowane. Od wersji 1.3.0 każde zamówienie jest liczone tylko raz, niezależnie od późniejszych zmian statusu.
## Alerty e-mail
System alertów monitoruje terminy, które nie zwracają żadnych wyników. Gdy termin przekroczy konfigurowalny próg (domyślnie 5), na wybrany adres wysyłany jest alert e-mail, a w nagłówku back-office pojawia się powiadomienie. Każdy alert można oznaczyć jako przeczytany lub usunąć. Szablony e-mail są dostarczane w sześciu językach (FR/EN/ES/DE/IT/PT), a temat wysyłany jest w domyślnym języku sklepu. Te wyszukiwania bez wyników są cennym źródłem do wykrywania luk katalogu, częstych literówek lub brakujących synonimów do dodania.
## Retencja danych
Logi wyszukiwania są przechowywane domyślnie 90 dni (czas konfigurowalny). W back-office dostępny jest przycisk ręcznego czyszczenia, a od wersji 1.3.0 automatyczne czyszczenie działa na bieżąco według skonfigurowanej retencji.
## FAQ i rozwiązywanie problemów
### Wyszukiwanie „marka + produkt” nic nie zwraca
Sprawdź, czy opcja „Wyszukuj w nazwie marki” (sekcja Inteligentne wyszukiwanie) jest włączona, dostępna od wersji 1.5.0, i czy producent jest przypisany na karcie produktu. Po aktualizacji wyczyść cache i przegeneruj assety.
### Ceny pojawiają się, choć powinny być ukryte
Respektowanie trybu katalogu, grup klientów bez cen i opcji produktu „Pokaż cenę” jest dostępne od wersji 1.5.0. Zaktualizuj moduł, wyczyść cache PrestaShop i przegeneruj assety. Sprawdź też, czy ustawienie modułu „Pokaż ceny” odpowiada temu, czego oczekujesz.
### Wyszukiwarka nie otwiera się na telefonie (motyw Warehouse)
Zaktualizuj do wersji 1.5.0: okno wyszukiwania jest teraz niezależne od nagłówka, a lupka nagłówka mobilnego Warehouse otwiera bezpośrednio moduł. Wyczyść cache PrestaShop, przegeneruj assety i wyczyść cache przeglądarki (konkatenacja CCC motywu może serwować stary JavaScript). Jeśli modyfikowałeś szablon motywu, aby umieścić przycisk otwierania, ta modyfikacja pozostaje kompatybilna.
### Jak skonfigurować synonimy?
W sekcji „Inteligentne wyszukiwanie” konfiguracji wpisz jedną grupę synonimów na linię (terminy rozdzielone przecinkami) w zakładce każdego języka, potem zapisz. Sprawdź, czy opcja „Włącz synonimy” jest aktywna.
### Jak zmienić rozmiar lub kształt paska wyszukiwania?
W sekcji „Wygląd” wybierz rozmiar (Small / Medium / Large), maksymalną szerokość i zaokrąglenie rogów paska. Zaokrąglenie 50 daje pasek w kształcie pigułki. Te ustawienia dotyczą tylko paska w nagłówku; okno wyników reguluje się przez „Maksymalną szerokość okna”.
### Jak wyłączyć skrót Ctrl+K?
W sekcji „Wygląd” ustaw opcję „Skrót klawiaturowy” na Nie. Plakietka znika z paska, a klawisze Ctrl+K, Cmd+K i / nie otwierają już wyszukiwania.
### Wyszukiwanie z literówką zwraca pustą stronę
Sprawdź, czy opcja „Tolerancja literówek” jest włączona i czy słownik korekty zawiera słowa (strefa informacyjna konfiguracji). Po dużym imporcie kliknij „Odbuduj słownik”. Możesz też zwiększyć „Maksymalną odległość korekty”.
### Wyszukiwanie nie znajduje referencji wariantu
Wyszukiwanie po referencji wariacji (ref, EAN, UPC, ref dostawcy) jest dostępne od wersji 1.2.0. Zaktualizuj, wyczyść cache i przegeneruj assety. Aby uzyskać bezpośredni link do dokładnej wariacji, zapytanie musi przypominać kod (zawierać co najmniej jedną cyfrę).
### Wyszukiwanie nic nie zwraca dla kilku słów
Wyszukiwanie działa po słowach niezależnie od kolejności. Jeśli właśnie zaktualizowałeś, wyczyść cache PrestaShop i przegeneruj assety, aby załadować nowy JavaScript.
### Panel autouzupełniania zasłania wyniki
Autouzupełnianie zamyka się automatycznie, gdy pole traci fokus, lub klawiszem Escape. Upewnij się, że używasz najnowszej wersji, i wyczyść cache, jeśli stare zachowanie się utrzymuje.
### Plakietka „brak w magazynie” pojawia się na zamawialnym produkcie
Moduł odczytuje ustawienie „Przyjmuj zamówienia” w **Ilościach** karty produktu (przechowywane po stronie `StockAvailable` na PrestaShop 8). Sprawdź to ustawienie: jeśli zezwala na zamawianie, plakietka nie będzie wyświetlana.
### Co dzieje się przy odinstalowaniu?
Odinstalowanie czysto usuwa hooki, zmienne konfiguracji i sześć tabel modułu. W bazie nie zostają żadne dane resztkowe.