# DF Faceted SEO: wyszukiwanie fasetowe i SEO w PrestaShop
> DF Faceted SEO zamienia wyszukiwanie fasetowe PrestaShop w trwałą dźwignię SEO i przyspiesza strony kategorii 10 do 30 razy dzięki zdenormalizowanemu indeksowi. Ta dokumentacja obejmuje instalację, konfigurację reguł indeksowania, tworzenie…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/dffacetedseo/index.md), [en](https://www.datafirefly.com/en/documentation/dffacetedseo/index.md), [es](https://www.datafirefly.com/es/documentation/dffacetedseo/index.md), [de](https://www.datafirefly.com/de/documentation/dffacetedseo/index.md), [it](https://www.datafirefly.com/it/documentation/dffacetedseo/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffacetedseo/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffacetedseo/index.md)
- Indeks:
DF Faceted SEO zamienia wyszukiwanie fasetowe PrestaShop w trwałą dźwignię SEO i przyspiesza strony kategorii 10 do 30 razy dzięki zdenormalizowanemu indeksowi. Ta dokumentacja obejmuje instalację, konfigurację reguł indeksowania, tworzenie landing pages SEO i wykorzystanie statystyk popularnych kombinacji.
## Prezentacja
Natywny moduł `ps_facetedsearch` mechanicznie generuje adres URL dla każdej możliwej kombinacji filtrów. Na katalogu kilku tysięcy produktów z pięcioma fasetami daje to miliony adresów, które Google eksploruje, rozcieńczając budżet crawlowania i PageRank między niemal identycznymi stronami.
DF Faceted SEO rozwiązuje ten problem równolegle na dwa sposoby:
- **Inteligentne indeksowanie**: reguły biznesowe decydują, które kombinacje są indeksowalne, które otrzymują `noindex follow` i gdzie wskazuje canonical.
- **Dedykowane landing pages SEO**: dla kombinacji o wysokim potencjale komercyjnym (na przykład „czerwone buty rozmiar 42") twórz strony docelowe z czystym adresem, H1, meta i własnymi treściami per język.
Dodatkowo silnik wyszukiwania modułu zastępuje silnik natywny systemem znacznie szybszym, opartym na zdenormalizowanym indeksie i dwupoziomowym cache.
## Wymagania
- PrestaShop 8.0 do 9.x
- PHP 8.1 lub nowsze
- MySQL 5.7 lub MariaDB 10.3 minimum
- Włączone przyjazne adresy URL (_Preferencje / SEO i adresy URL_)
- Standardowe uprawnienia do tworzenia tabel MySQL
## Instalacja
1. Wgraj archiwum ZIP przez _Moduły / Menedżer modułów / Wgraj moduł_.
2. Kliknij **Zainstaluj**. Moduł automatycznie tworzy 10 tabel `ps_dffacetedseo_*` i 5 zakładek w menu _Ulepszenia_.
3. Przejdź do _Ulepszenia / DF Faceted SEO / Pulpit_.
4. Kliknij **Odbuduj indeks**. _Ten krok jest obowiązkowy za pierwszym razem_: bez indeksu silnik wyszukiwania modułu nie ma żadnych danych do wykorzystania.
5. Wyczyść cache PrestaShop: _Parametry zaawansowane / Wydajność / Wyczyść cache_.
Na katalogu 50 000 produktów odbudowa indeksu trwa typowo od 2 do 5 minut. Moduł wstawia wiersze partiami po 500.
## Pierwsze kroki: pulpit
Pulpit (_Ulepszenia / DF Faceted SEO_) wyświetla sześć kafelków statystycznych:
- **Aktywne reguły**: liczba włączonych reguł indeksowania
- **Landing pages**: liczba utworzonych stron docelowych SEO
- **Produkty w indeksie**: liczba zaindeksowanych produktów (powinna być zbliżona do sumy katalogu)
- **Wiersze w indeksie**: liczba par (produkt, wartość filtra), czyli tabela zdenormalizowana
- **Wpisy w cache**: liczba zapytań w pamięci podręcznej
- **Popularne kombinacje**: liczba zaobserwowanych kombinacji filtrów
Pod kafelkami znajdują się dwa bloki operacji:
- **Odbuduj indeks**: przydatne po dużej modyfikacji katalogu (import masowy, zmiana struktury atrybutów)
- **Wyczyść cache**: przydatne po modyfikacji reguł lub ustawień
## Reguły indeksowania
Reguły decydują, dla każdej odwiedzonej kombinacji filtrów, jaki znacznik `robots` i jaki `canonical` są wysyłane do przeglądarki i do Google. Reguła ma **zakres** (obszar zastosowania) i **politykę** (decyzję).
### Dostępne zakresy
- **Globalny**: obowiązuje na wszystkich stronach fasetowych katalogu
- **Konkretna kategoria**: obowiązuje wyłącznie na stronach danej kategorii
- **Grupa atrybutów**: obowiązuje na kombinacjach zawierających konkretną grupę (na przykład wszystkie strony, gdzie filtrowany jest Kolor)
- **Cecha**: analogicznie, dla cechy produktu
- **Marka**: analogicznie, dla marki (producenta)
- **Przedział cenowy**: obowiązuje na stronach filtrowanych po danym zakresie cen
### Dostępne polityki
- **Index, follow**: strona indeksowalna, canonical wskazujący na nią samą w postaci znormalizowanej
- **Noindex, follow**: strona nieindeksowana, ale linki są podążane (zalecane dla rzadkich kombinacji)
- **Canonical do rodzica**: strona dostępna, ale canonical wskazuje na kategorię nadrzędną (wartość SEO jest przenoszona)
- **Znormalizowany canonical self**: canonical na samą stronę z posortowanymi i pogrupowanymi filtrami (eliminuje duplikaty adresów dla tej samej kombinacji)
### Łańcuch priorytetów
Moduł ocenia reguły od **najbardziej szczegółowej do najbardziej ogólnej**. Konkretnie, dla strony kategorii Buty filtrowanej po kolorze:
1. Moduł szuka najpierw reguły o zakresie `category` dla Butów
2. Jeśli istnieje i pasuje, zostaje zastosowana
3. W przeciwnym razie szuka reguły o zakresie `attribute_group` dla Koloru
4. W przeciwnym razie wspina się do reguły globalnej
5. Jeśli żadna reguła nie pasuje, stosowana jest polityka domyślna z pulpitu
### Zaawansowane pola reguły
- **Maksimum indeksowalnych filtrów**: jeśli kombinacja zawiera więcej filtrów niż ten limit, polityka automatycznie przechodzi w `noindex follow`. Przykład: maksymalnie 2 filtry na butach (kolor i rozmiar indeksowane, ale nie kolor plus rozmiar plus materiał plus sezon).
- **Whitelista wartości**: ID dozwolonych wartości (oddzielone przecinkami). Kombinacja zawierająca wyłącznie wartości z whitelisty jest indeksowalna. Przykład: whitelista dla kolorów czerwonego, czarnego, białego i niebieskiego, przez co rzadkie kolory typu „zielone jabłko" nie będą indeksowane.
- **Blacklista wartości**: odwrotność. Każda kombinacja zawierająca wartość z blacklisty automatycznie trafia w `noindex`.
- **Minimum produktów**: jeśli kombinacja nie zwraca co najmniej tej liczby produktów, przechodzi w `noindex`. Zapobiega indeksowaniu niemal pustych stron.
- **Priorytet**: liczba całkowita. W razie konfliktu między dwiema regułami o tym samym zakresie wygrywa wyższy priorytet.
Zalecana strategia na start: utwórz regułę _globalną_ z polityką `canonical do rodzica` i maksymalnie 1 indeksowalnym filtrem, następnie stopniowo dodawaj bardziej szczegółowe reguły, aby otworzyć indeksowanie kombinacji o wysokim potencjale.
## Landing pages SEO
Landing pages to strony docelowe dedykowane strategicznym kombinacjom filtrów. Mają własny czysty adres, własny H1, własne meta i treść redakcyjną per język.
### Tworzenie landing page
1. Przejdź do _Ulepszenia / DF Faceted SEO / Landing pages_
2. Kliknij **Dodaj**
3. Sekcja **Celowanie**: wybierz kategorię i ewentualnie odpowiednią markę
4. Sekcja **Wyświetlanie**: sortowanie domyślne, kierunek, aktywacja, indeksowanie, priorytet
5. Sekcja **Kombinacja filtrów**: dodaj filtry składające się na kombinację (grupa atrybutów i wartości, cecha lub marka). Przykład: Kolor = Czerwony ORAZ Rozmiar = 42.
6. Zakładki wielojęzyczne: uzupełnij dla każdego języka nazwę wewnętrzną, slug adresu, H1, meta title, meta description, treść intro i treść outro.
7. Zapisz
### Struktura adresu URL
Adres landing page ma następujący wzorzec:
```
https://twoja-domena.pl/landing/twoj-slug
https://twoja-domena.pl/en/landing/twoj-slug
https://twoja-domena.pl/pl/landing/twoj-slug
```
Prefiks języka jest obsługiwany automatycznie przez router PrestaShop, gdy tylko włączone są przyjazne adresy URL, a w sklepie aktywnych jest kilka języków.
Jeśli otrzymujesz 404 na adresie landingu, sprawdź w tej kolejności: włączone przyjazne adresy URL, zregenerowany `.htaccess` (przycisk Zapisz na dole strony SEO i adresy URL), wyczyszczony cache, aktywny landing w formularzu, hook `moduleRoutes` poprawnie podpięty do modułu w _Moduły / Pozycje_.
### Treść redakcyjna
Dla każdego języka dostępne są dwa bogate bloki HTML:
- **Intro**: wyświetlany nad siatką produktów. Idealny na akapit wprowadzający SEO liczący 150 do 300 słów z Twoimi docelowymi słowami kluczowymi.
- **Outro**: wyświetlany pod siatką. Idealny na elementy budujące zaufanie, poradniki zakupowe i FAQ.
### Automatyczny JSON-LD
Każda landing page automatycznie wstrzykuje na stronę dwa bloki JSON-LD:
- **BreadcrumbList**: Strona główna, Kategoria, Landing
- **Product**: jeden blok Product na każdy wyświetlany produkt (nazwa, cena, zdjęcie, adres, dostępność)
Otrzymujesz automatycznie rich snippety Google bez dodatkowej konfiguracji.
## Statystyki popularnych kombinacji
Moduł automatycznie zapisuje w tabeli `ps_dffacetedseo_combination_log` każdą kombinację filtrów realnie odwiedzoną przez klientów: sygnaturę, liczbę trafień, ostatnie wyświetlenie.
### Wykorzystanie statystyk
1. Przejdź do _Ulepszenia / DF Faceted SEO / Statystyki_
2. Przefiltruj po kategorii, minimalnej liczbie trafień i limicie wyświetlania
3. Posortuj malejąco po trafieniach
4. Wychwyć kombinacje z ponad 50 trafieniami tygodniowo
5. Kliknij **Awansuj** w kolumnie akcji
6. Formularz landing page otwiera się **wstępnie wypełniony** kombinacją filtrów
7. Pozostaje tylko uzupełnić treść redakcyjną i zapisać
### Utrzymanie
Na dole strony Statystyki znajduje się przycisk _Wyczyść stare dane_ z polem „liczba dni do zachowania". Zalecane: czyszczenie co 90 dni, aby uniknąć nieograniczonego wzrostu tabeli.
## Ustawienia globalne
Pulpit udostępnia 11 ustawień globalnych pogrupowanych w 3 sekcje.
### Indeksowanie
- **Polityka domyślna**: polityka stosowana, gdy żadna reguła nie pasuje
- **Maksimum indeksowalnych filtrów**: wartość globalna (może być nadpisana przez regułę)
- **Minimum produktów na kombinację**: globalny próg uznania strony za indeksowalną
### Wydajność
- **TTL cache (sekundy)**: czas życia wpisu w cache. Domyślnie: 3600 (1 godzina). Zwiększ do 86400 (24 h) na stabilnej produkcji.
- **Ukryj puste filtry**: jeśli włączone, wartości z 0 wynikami są ukrywane w panelu filtrów
- **Limit wyników na stronę**: paginacja produktów
### Adresy URL
- **Prefiks adresów landingów**: domyślnie `landing`. Wzorzec trasy jest zdefiniowany na sztywno w hooku `moduleRoutes` modułu i używa tego prefiksu.
## Inteligentny canonical
Na każdej stronie fasetowej moduł wylicza optymalny canonical:
- Kombinacja pasująca do istniejącego landingu: canonical równy pretty URL landingu
- Kombinacja indeksowalna według reguł: canonical równy znormalizowanemu self (filtry posortowane i pogrupowane)
- Kombinacja nieindeksowalna według reguł: canonical równy kategorii nadrzędnej
- Strona kategorii bez filtra: canonical równy standardowemu self
Normalizacja grupuje wartości według grupy i sortuje grupy po ID. Dwa adresy wizualnie różne, ale semantycznie identyczne (na przykład inna kolejność parametrów GET) otrzymują ten sam canonical.
## Wysokowydajny silnik filtrów
Silnik opiera się na tabeli `ps_dffacetedseo_index`: jeden wiersz na parę (produkt, typ filtra, wartość). Wyszukiwanie zamienia się w przecięcie zbiorów identyfikatorów produktów.
### Cache dwupoziomowy
- **Poziom 1: pamięć (in-process)**. Unika dwukrotnego wykonania tego samego zapytania w obrębie jednej strony.
- **Poziom 2: baza danych (tabela ps_dffacetedseo_cache)**. Utrwala wyniki między żądaniami z TTL.
### Automatyczne unieważnianie
Moduł nasłuchuje hooków `actionProductSave`, `actionProductDelete` i `actionCategoryUpdate`. Za każdym razem, gdy produkt zostaje zapisany, jego wpis w indeksie jest regenerowany, a wszystkie wpisy cache powiązane z tym produktem są unieważniane.
### AJAX i UX
Frontowy panel filtrów jest w całości sterowany przez AJAX:
- Debounce 250 ms na zmianach filtrów
- `pushState` do aktualizacji adresu bez przeładowania strony
- Aktualizacja w czasie rzeczywistym znaczników `canonical` i `robots` w nagłówku dokumentu
- Płynne przewijanie do siatki produktów po aktualizacji
- Klikalne aktywne chipy pozwalające usunąć pojedynczy filtr
- Suwak cen z polami liczbowymi i przyciskiem Zastosuj
- Swatche kolorów widoczne na atrybutach typu Kolor
## Multisklep i wielojęzyczność
Moduł jest natywnie multisklepowy i wielojęzyczny:
- Każda landing page ma tłumaczenia per język (tabela `ps_dffacetedseo_landing_page_lang`)
- Każdy landing może być ograniczony do jednego lub kilku sklepów (tabela `ps_dffacetedseo_landing_page_shop`)
- Reguły indeksowania domyślnie obowiązują we wszystkich sklepach
- Indeks jest partycjonowany per sklep
- Tłumaczenia interfejsu są dostarczone po francusku i angielsku (XLIFF w katalogu `translations/`)
## Architektura techniczna
### Używane hooki
- `displayHeader`: dynamiczne canonical i meta robots
- `actionFrontControllerSetMedia`: CSS i JS frontendu
- `moduleRoutes`: czysta trasa dla landing pages
- `displayLeftColumn`: wstrzykiwanie panelu filtrów
- `displayBeforeBodyClosingTag`: JSON-LD na landingach
- `actionProductSearchProviderRunQuery`: integracja z silnikiem PS
- `actionProductSave` i `actionProductDelete`: przyrostowa reindeksacja
- `actionCategoryUpdate`: unieważnienie cache kategorii
- `displayBackOfficeHeader`: CSS i JS admina
### Tworzone tabele
| Tabela | Rola |
| --- | --- |
| `dffacetedseo_rule` | Reguły indeksowania per zakres |
| `dffacetedseo_landing_page` | Landingi (dane biznesowe) |
| `dffacetedseo_landing_page_lang` | Tłumaczenia landingów |
| `dffacetedseo_landing_page_shop` | Powiązania multisklepowe |
| `dffacetedseo_landing_filter` | Filtry powiązane z landingami |
| `dffacetedseo_combination_log` | Statystyki odwiedzin |
| `dffacetedseo_cache` | Cache wyników zapytań |
| `dffacetedseo_filter_template` | Szablony filtrów wielokrotnego użytku |
| `dffacetedseo_index` | Zdenormalizowany indeks (klucz wydajności) |
| `dffacetedseo_setting` | Ustawienia wewnętrzne |
### Konwencja adresów filtrów
```
?attribute_group__{id_group}=v1,v2&feature__{id_feature}=v3&manufacturer__0=5&price=10-50&s=needle
```
Stabilna sygnatura SHA-1 jest wyliczana do porównywania kombinacji (dopasowanie landingu, klucz cache, log).
## Oczekiwana wydajność
Pomiary wykonane na katalogu referencyjnym (50 000 produktów, 8 aktywnych faset):
| Silnik | Średni czas |
| --- | --- |
| Natywny `ps_facetedsearch` | 800 ms do 1,4 s na zapytanie |
| DF Faceted SEO bez cache | 50 do 120 ms |
| DF Faceted SEO z cache | poniżej 10 ms |
Typowy zysk: **x10 do x30**
## FAQ techniczne
### Czy trzeba odinstalować ps_facetedsearch
Nie, moduł integruje się przez oficjalne hooki. Możesz przetestować go równolegle. Po walidacji odinstaluj `ps_facetedsearch`, aby uniknąć zdublowania panelu filtrów.
### Czy moduł jest zgodny z HTTPS i absolutnymi adresami canonical
Tak. Moduł używa `Context::getContext()->link->getPageLink()` i `getModuleLink()`, które respektują konfigurację HTTPS PrestaShop.
### Jak dodać nowy język po stronie modułu
Skopiuj plik `translations/fr-FR.xlf` jako `translations/xx-XX.xlf` i przetłumacz elementy `trans-unit`. Żadna inna interwencja nie jest potrzebna.
### Czy moduł obsługuje atrybuty złożone (kombinacje atrybutów)
Tak. Zdenormalizowany indeks indeksuje warianty przez ich atrybuty. Silnik wyszukiwania filtruje produkty, których co najmniej jeden wariant odpowiada wszystkim aktywnym filtrom.
### Jak debugować regułę, która się nie stosuje
Włącz logi PrestaShop (_Parametry zaawansowane / Logi_) i sprawdź sekcję `dffacetedseo`. Każde rozstrzygnięcie dyrektywy zapisuje dopasowaną regułę i powód.
## Rozwiązywanie problemów
### Fatal error przy wywołaniu `getBySlug`
Objaw: `Call to a member function getBySlug() on false`. Przyczyna: dawny helper `get()`, który zwracał `false` zamiast obiektu usługi. Poprawione w v1.0.1. Zaktualizuj moduł.
### 404 na adresie landing page
Objaw: `https://twoja-strona/en/landing/twoj-slug` zwraca 404. Typowa przyczyna: hook `moduleRoutes` nie jest zarejestrowany albo cache tras PrestaShop jest nieaktualny.
1. Sprawdź, czy _Preferencje / SEO i adresy URL / Włącz przyjazne adresy URL_ jest ustawione na TAK
2. Zapisz tę stronę (regeneruje `.htaccess`)
3. Wyczyść cache PrestaShop dwukrotnie
4. Przejdź do _Moduły / Pozycje_ i sprawdź, czy `dffacetedseo` jest podpięty do `moduleRoutes`
5. Fallback testowy: `https://twoja-strona/index.php?fc=module&module=dffacetedseo&controller=landing&slug=twoj-slug`
### Silnik wyszukiwania nie zwraca żadnego produktu
Indeks jest prawdopodobnie pusty. Przejdź do pulpitu i kliknij **Odbuduj indeks**.
### Filtry nie wyświetlają się w kolumnie
Sprawdź w _Moduły / Pozycje_, czy `dffacetedseo` jest podpięty do hooka `displayLeftColumn`. W zależności od motywu możesz go też podpiąć do `displayRightColumn` lub `displayHome`.
### Spadek wydajności po masowym imporcie produktów
Przyrostowe unieważnianie sprawdza się przy modyfikacjach jednostkowych. Po imporcie masowym szybciej jest odbudować cały indeks z pulpitu i wyczyścić cache.
## Aktualizacje
Moduł stosuje wersjonowanie `GŁÓWNA.POBOCZNA.PATCH`. Krytyczne poprawki (bezpieczeństwo, fatal errors) są dostarczane jako patch; nowe funkcje wywołują podbicie wersji pobocznej. Każda aktualizacja główna zawiera skrypt `upgrade/upgrade-X.Y.Z.php`, który uruchamia się automatycznie przy instalacji nowej wersji.
## Wsparcie
W razie pytań lub zgłoszenia błędu skontaktuj się z [support@datafirefly.com](mailto:support@datafirefly.com), podając wersję PrestaShop, wersję PHP, wersję modułu oraz logi PHP i PrestaShop.