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ł 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.