# AI Competitor: monitoring cen konkurencji
> Wprowadzenie AI Competitor monitoruje ceny konkurencji bezpośrednio z panelu PrestaShop. Definiujesz konkurenta raz, wraz z nazwą i selektorami; moduł może następnie pobrać pełną listę jego produktów z jego sitemapy, dopasować…
- Strona:
- Język: pl
- Zaktualizowano: 2026-09-10
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfaicompetitor/index.md), [en](https://www.datafirefly.com/en/documentation/dfaicompetitor/index.md), [es](https://www.datafirefly.com/es/documentation/dfaicompetitor/index.md), [de](https://www.datafirefly.com/de/documentation/dfaicompetitor/index.md), [it](https://www.datafirefly.com/it/documentation/dfaicompetitor/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaicompetitor/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaicompetitor/index.md)
- Indeks:
## Wprowadzenie
AI Competitor monitoruje ceny konkurencji bezpośrednio z panelu PrestaShop. Definiujesz konkurenta raz, wraz z nazwą i selektorami; moduł może następnie pobrać pełną listę jego produktów z jego sitemapy, dopasować ją do Twojego katalogu, odczytywać ceny w regularnych odstępach, wykrywać istotne zmiany, powiadamiać Cię e-mailem i proponować cenę dostosowaną do Twojej strategii.
Zgodny z PrestaShop 8.0 do 9.x, PHP 7.4 do 8.3, natywny multisklep. Bez zależności Composera, bez zewnętrznej biblioteki JavaScript.
## Instalacja
1. W panelu otwórz **Moduły → Menedżer modułów → Wgraj moduł**.
2. Wgraj plik `dfaicompetitor.zip`.
3. Moduł tworzy swoje tabele oraz menu **Katalog → AI Competitor**, które obejmuje sześć stron: pulpit, konkurenci, monitorowane adresy URL, katalog konkurenta, raporty i analityka, import/eksport.
Po instalacji generowany jest unikalny token cron. Znajdziesz go na pulpicie modułu.
### Aktualizacja z wersji 1.0.x
Po prostu wgraj nowy ZIP na istniejącą instalację. Skrypt aktualizacji tworzy nowe tabele, dodaje brakujące kolumny, a przede wszystkim **generuje profil konkurenta dla każdej już używanej nazwy konkurenta** i przypisuje do niego odpowiednie adresy URL. Twoje dane zostają zachowane i nie trzeba niczego wprowadzać ponownie.
Ponowna instalacja paczki z tym samym numerem wersji co już zainstalowana nie uruchamia skryptu aktualizacji, a opcache PHP może nadal serwować stare pliki. Po każdym wgraniu sprawdzaj numer wersji wyświetlany na pulpicie.
## Konfiguracja początkowa
Otwórz **Katalog → AI Competitor**. Pulpit zbiera statystyki i pięć bloków konfiguracji.
### Dostawca AI
Awaryjna ekstrakcja AI jest opcjonalna, ale zalecana: przejmuje pracę, gdy witryna konkurenta nie udostępnia ani danych strukturalnych, ani użytecznego selektora. Obsługiwani są trzej dostawcy:
- **Mistral AI** (domyślnie), najtańszy, zalecany model: `mistral-small-latest`
- **Anthropic Claude**, najlepsza precyzja na złożonych stronach, zalecany model: `claude-haiku-4-5-20251001`
- **OpenAI**, dobry kompromis, zalecany model: `gpt-4o-mini`
Wpisz klucz API wybranego dostawcy. Jest wyświetlany zamaskowany; przy kolejnym zapisie zostaw pole puste, aby zachować zapisany klucz. Płacisz bezpośrednio dostawcy, bez narzutu DataFirefly.
### Alerty
- **E-mail powiadomień**: odbiorca zbiorczych alertów i raportu tygodniowego.
- **Próg zmiany** w procentach, domyślnie 3 %. Poniżej nie powstaje żaden alert.
- **Dzień raportu tygodniowego**, domyślnie poniedziałek.
### Scraping
- **Adresy URL na partię crona**: liczba adresów odczytywanych przy każdym przebiegu, domyślnie 20.
- **Domyślny interwał** w godzinach, stosowany do nowych adresów, domyślnie 24 h.
- **Limit czasu HTTP** i **User-Agent**. Dostarczony User-Agent identyfikuje robota z nazwy (`DataFireflyBot`); niektóre witryny dopuszczają nazwanego robota, którego inaczej by zablokowały.
- **Przechowywanie historii** w dniach, domyślnie 180.
### Indeksowanie katalogu
- **Stron na partię**: liczba kart konkurenta otwieranych w jednym przebiegu, domyślnie 15.
- **Sekund na partię**: budżet czasu każdego przebiegu, domyślnie 20. Utrzymuj go poniżej swojego `max_execution_time` w PHP.
- **Próg dopasowania**: minimalne podobieństwo tytułów do zaakceptowania automatycznego dopasowania, domyślnie 82.
- **Automatycznie monitoruj dopasowania**: tworzy monitorowany adres URL, gdy tylko zindeksowana strona zostanie dopasowana do jednego z Twoich produktów. Domyślnie wyłączone.
- **Kontynuuj indeksowanie z crona**: domyślnie włączone.
### Strategia korekty
Trzy strategie wyznaczają sugerowaną cenę, zawsze liczoną od najtańszego konkurenta:
- **Zrównanie**: ta sama cena co u najtańszego konkurenta.
- **Podcięcie o X %**: X % poniżej, domyślnie 1 %.
- **Premium o X %**: X % powyżej, dla świadomego pozycjonowania w wyższym segmencie.
## Zdefiniować konkurenta
Od wersji 1.1.0 konkurent jest osobnym wpisem, a nie etykietą wpisywaną ponownie przy każdym adresie. Otwórz **Katalog → AI Competitor → Konkurenci → Dodaj**. Formularz ma trzy zakładki.
### Tożsamość
Nazwa wyświetlana wszędzie, domena bez schematu (`przyklad.pl`), waluta, interwał odczytu, opcja wymuszonej ekstrakcji AI oraz pole na notatki. To domena pozwala modułowi automatycznie przypisać nowy adres URL do właściwego konkurenta.
### Selektory
Selektory CSS ceny, nazwy produktu, SKU, obrazu i dostępności. Zostaw je puste, jeśli witryna publikuje JSON-LD, co robi większość nowoczesnych sklepów. Obsługiwana składnia: znacznik, `.klasa`, `#identyfikator`, `[atrybut=wartość]`, potomek i bezpośrednie dziecko. Przykład: `div.product-price > span.amount`
To główna korzyść z wpisu konkurenta: gdy witryna przebuduje motyw i zepsuje selektor, poprawiasz go tutaj raz, a poprawka rozchodzi się na wszystkie adresy tego konkurenta, które nie mają własnego selektora.
### Indeksowanie katalogu
Adres sitemapy (zostaw pusty, aby odczytać dyrektywy `Sitemap:` z robots.txt domeny), adres startowej strony kategorii, selektor linków produktowych i selektor linku do następnej strony, wzorce adresów do zatrzymania lub odrzucenia, opóźnienie między dwoma żądaniami, limit produktów i poszanowanie robots.txt.
Wzorce przyjmują zwykły podciąg albo wyrażenie regularne ograniczone ukośnikami. W polskim sklepie `/produkt/` jako wzorzec do zatrzymania często wystarcza, aby wyodrębnić karty produktów z sitemapy zawierającej też bloga i strony CMS.
## Zindeksować katalog konkurenta
Otwórz **Katalog → AI Competitor → Katalog konkurenta**, wybierz konkurenta, źródło odkrywania i limit produktów, po czym uruchom indeksowanie.
Dostępne są dwa źródła:
- **Sitemapa**, zalecana. Moduł czyta skonfigurowaną sitemapę albo tę ogłoszoną przez robots.txt, podąża rekurencyjnie za indeksami sitemap i zatrzymuje adresy pasujące do Twoich wzorców.
- **Strony kategorii**, gdy żadna sitemapa nie nadaje się do użytku. Moduł startuje z adresu listingu, zbiera linki produktowe przez selektor konkurenta i podąża za linkiem do następnej strony.
Po odkrywaniu następuje faza wzbogacania, która otwiera każdą stronę, wyciąga tytuł, SKU, EAN, markę, cenę, dostępność i obraz, a następnie próbuje dopasowania do Twojego katalogu.
Indeksowanie postępuje partiami ograniczonymi czasowo, sterowanymi przez otwartą stronę z paskiem postępu, i wznawia się przy każdym przebiegu crona. Sitemapa z dziesiątkami tysięcy adresów jest przetwarzana bez osiągnięcia `max_execution_time` w PHP. Możesz zamknąć stronę: praca trwa dalej po stronie crona.
### Dopasowanie do Twojego katalogu
Moduł próbuje trzech dróg, w kolejności malejącej pewności:
1. **EAN13**, szukany w Twoich produktach i ich wariantach. Pewne dopasowanie, wynik 100.
2. **Referencja**, referencja dostawcy lub MPN. Wynik 95.
3. **Podobieństwo tytułu**, z wagą dającą większe znaczenie numerom modeli i markom niż słowom pospolitym, oraz karą, gdy oba tytuły znacznie różnią się długością. Wynik musi przekroczyć skonfigurowany próg, domyślnie 82.
Każdy wiersz katalogu pokazuje metodę i wynik dopasowania. Wątpliwe dopasowanie poprawia się ręcznie: pole dopasowania podpowiada z Twojego katalogu, po nazwie lub referencji. Przyciski **Dopasuj ponownie** uruchamiają operację na niedopasowanych wierszach albo na wszystkich, co przydaje się po poprawieniu referencji po Twojej stronie.
Dopasowany wiersz staje się monitorowanym adresem URL przyciskiem **Monitoruj** albo masowo, akcją grupową na zaznaczeniu. Utworzony adres dziedziczy nazwę, selektory, walutę i interwał konkurenta.
## Dodać adres URL ręcznie
Indeksowanie nie zastępuje pojedynczego wpisu. Otwórz **Katalog → AI Competitor → Monitorowane adresy URL → Dodaj**:
- **Konkurent**: wpis, po którym adres odziedziczy ustawienia. Zostaw puste, aby wpisać wszystko ręcznie.
- **Produkt**: wybrany z Twojego katalogu.
- **URL**: pełny adres karty produktu konkurenta.
- **Nazwa konkurenta, selektor CSS, waluta, interwał**: uzupełniane z konkurenta, gdy zostawisz je puste.
Jeśli nie wybierzesz konkurenta, moduł szuka tego, którego domena odpowiada wpisanemu adresowi, i przypisuje do niego adres. Przycisk **Scrape** przy każdym wierszu uruchamia natychmiastowy odczyt, przydatny do sprawdzenia adresu zaraz po utworzeniu.
### Jak działa ekstrakcja
Dla każdego adresu moduł próbuje czterech metod kaskadowo i zatrzymuje się na pierwszej skutecznej:
1. **JSON-LD**: dane strukturalne Product/Offer, obecne w zdecydowanej większości sklepów internetowych. Cena, waluta, dostępność, a przy indeksowaniu także tytuł, SKU, GTIN i marka, są odczytywane wprost bez konfiguracji.
2. **OpenGraph**: znaczniki meta product price amount.
3. **Selektor CSS**: ten z wpisu konkurenta albo własny adresu, jeśli go ma.
4. **AI**: oczyszczony fragment HTML trafia do Twojego dostawcy, który zwraca cenę, walutę i stan magazynowy. Obsługiwane są międzynarodowe formaty cen (1 299,90 tak samo jak 1.234,56 czy $49.99).
Zawsze zaczynaj bez selektora CSS: JSON-LD wystarcza w większości przypadków. Dodawaj selektor albo wymuszoną AI tylko wtedy, gdy kolumna Status pokazuje `no_price`.
## Import i eksport
Strona **Import / Eksport** służy do przeniesienia konfiguracji z jednego sklepu do drugiego.
### Konkurenci w JSON
Eksport tworzy plik z nazwami, domenami, selektorami i ustawieniami indeksowania. Zaznacz konkurentów do uwzględnienia albo nie zaznaczaj nikogo, aby wyeksportować wszystkich. Przy imporcie dopasowanie odbywa się najpierw po nazwie, potem po domenie; pole wyboru decyduje, czy istniejący konkurent zostanie zaktualizowany, czy pominięty, a tryb podglądu zapowiada wynik bez zapisu.
### Monitorowane adresy URL w CSV
Oczekiwane kolumny: `product_id`, `product_reference`, `competitor_name`, `competitor_domain`, `url`, `price_selector`, `currency_iso`, `use_ai_extraction`, `scrape_interval_hours`, `active`.
Obowiązkowe są tylko `competitor_name` i `url`, plus `product_id` lub `product_reference`, aby wiedzieć, do którego produktu należy adres. Nieznana nazwa konkurenta automatycznie tworzy jego wpis, dzięki czemu jeden plik wystarcza do uruchomienia całej instalacji. Separator jest wykrywany automatycznie, a import startuje w trybie podglądu, raportując wiersz po wierszu, co zostałoby utworzone, zaktualizowane lub pominięte.
### Katalog konkurenta w CSV
Eksport wszystkiego, co znalazło indeksowanie, wraz z dopasowanym produktem, metodą i wynikiem. Pole wyboru ogranicza eksport do samych dopasowanych wierszy. Przydatne do audytu offline lub do przekazania działowi zakupów.
## Skonfigurować cron
Praca cykliczna opiera się na punkcie końcowym zabezpieczonym tokenem, pokazanym na pulpicie. Zaplanuj jego wywołanie co 30 minut:
```
*/30 * * * * curl -s "https://twoj-sklep.pl/index.php?fc=module&module=dfaicompetitor&controller=cron&token=TWOJ_TOKEN" > /dev/null
```
Przy każdym przebiegu cron odczytuje partię adresów, których interwał upłynął, wysyła oczekujące e-maile alertów, wyprawia raport tygodniowy we właściwym dniu, posuwa o jedną partię trwające indeksowanie katalogu i czyści historię poza skonfigurowanym okresem przechowywania. Odpowiedzią jest podsumowanie w JSON.
Token można w każdej chwili wygenerować na nowo z pulpitu, wtedy istniejące zadania cron trzeba zaktualizować. Dostępne jest też ręczne uruchomienie przyciskiem **Run cron now**.
## Alerty
Generowanych jest pięć typów alertów, każdy z wagą:
- **price_drop / price_rise**: zmiana powyżej progu. Zmiana o 10 % lub więcej staje się critical.
- **undercut**: konkurent schodzi poniżej Twojej ceny sprzedaży brutto. Zawsze critical.
- **out_of_stock / back_in_stock**: zmiany dostępności wykryte przez dane strukturalne albo AI.
- **scrape_error**: dopiero po 3 kolejnych niepowodzeniach, aby wyeliminować szum przejściowych awarii.
Alerty są łączone w jedną wiadomość zbiorczą na każdy przebieg crona.
## Raporty i analityka
Ekran **Raporty i analityka** mieści się w czterech zakładkach, za stale widocznym paskiem wskaźników: porównywane produkty, udział produktów, w których jesteś najtańszy, średnia różnica wobec najniższej ceny rynkowej, otwarte alerty, kondycja scrapingu. Wybór okresu obejmuje 7, 30 lub 90 dni.
### Przegląd
Twoja pozycja rynkowa w formie paska (najtańszy, pośrodku, najdroższy), produkty, na których tracisz cenowo, uszeregowane według malejącej różnicy, te z zapasem na podwyżkę, tabela per konkurent pokazująca, kto podcina Cię najczęściej, oraz streszczenie napisane przez AI. Okazje eksportują się do CSV.
### Alerty
Lista filtrowana według typu, wagi, stanu i tekstu, z wykresem dziennego wolumenu według wagi. Każdy wiersz potwierdza się lub otwiera ponownie bez przeładowania strony, a licznik otwartych alertów aktualizuje się na pasku.
### Analiza produktu
Wybierz monitorowany produkt: moduł rysuje Twoją cenę wobec ceny każdego konkurenta w danym okresie, pokazuje sugestię korekty z ceną obecną i proponowaną obok siebie oraz wymienia źródła z przyciskiem natychmiastowego odczytu przy każdym.
Od wersji 1.1.0 każdy odczyt zapisuje też Twoją własną cenę z danej chwili. To pozwala odtworzyć historię różnic. W sklepie zaktualizowanym z wersji 1.0.x krzywa Twojej ceny jest dokładna dopiero od odczytów po aktualizacji; wcześniej moduł używa Twojej bieżącej ceny jako wartości zastępczej.
### Kondycja
Adresy, które zawodzą, ze statusem, liczbą kolejnych niepowodzeń, ostatnim błędem i przyciskiem ponowienia, plus wskaźnik skuteczności per konkurent. To pierwsze miejsce do sprawdzenia, gdy jakaś liczba wygląda podejrzanie: konkurent, którego scraping padł, zniekształca średnie.
## Sugestia ceny
W zakładce analizy produktu moduł pokazuje Twoją obecną cenę, minimum, średnią i maksimum konkurentów, źródła oraz sugerowaną cenę zgodnie z Twoją strategią. Przycisk **Zastosuj** zapisuje cenę na produkcie PrestaShop.
Zastosowanie nigdy nie jest automatyczne. To świadomy wybór, aby uniknąć spirali obniżek między konkurentami wyposażonymi w to samo narzędzie. Przeliczenie z ceny brutto na netto odbywa się automatycznie według stawki podatku produktu.
## Rozwiązywanie problemów
### Indeksowanie nie znajduje żadnej strony
Sprawdź najpierw, czy domena konkurenta jest wpisana bez schematu i bez `www.`. Następnie otwórz `https://domena/robots.txt` w przeglądarce: jeśli nie zawiera żadnej dyrektywy `Sitemap:`, wpisz adres sitemapy ręcznie we wpisie konkurenta. Jeśli sitemapa istnieje, ale nic nie zostaje zatrzymane, Twój wzorzec filtrowania jest zapewne zbyt wąski: opróżnij go, aby zobaczyć, co wraca, a potem zawęź.
### Indeksowanie znajduje strony, które nie są produktami
Wpisz jako wzorzec do zatrzymania segment wspólny dla kart produktów witryny, na przykład `/produkt/` lub `/p/`, a jako wzorzec do odrzucenia to, co zaśmieca wynik, na przykład `/blog/`. Następnie wyczyść katalog konkurenta i uruchom ponownie.
### Wiele stron pozostaje niedopasowanych
Sprawdź najpierw, czy karty konkurenta udostępniają SKU lub EAN: bez wspólnego identyfikatora zadziała tylko podobieństwo tytułu. Wpisz selektor SKU we wpisie konkurenta, uruchom indeksowanie ponownie, a potem użyj **Dopasuj ponownie**. Jeśli Twoje tytuły bardzo różnią się od tytułów konkurenta, obniż próg dopasowania do 75 i sprawdź uzyskane dopasowania, zanim tak to zostawisz.
### Status „no_price”
Żadna z metod nie znalazła ceny. Sprawdź adres w przeglądarce, dodaj selektor CSS ceny we wpisie konkurenta albo włącz wymuszoną ekstrakcję AI.
### Status „error” lub „blocked”
`error` oznacza, że strona nie odpowiedziała (HTTP 400 i wyżej albo przekroczenie limitu czasu). `blocked` oznacza, że robots.txt witryny zabrania tego adresu naszemu robotowi. W pierwszym przypadku dostosuj User-Agent, zwiększ limit czasu albo rozszerz interwał. W drugim jest to decyzja odwiedzanej witryny, którą sam musisz ocenić.
### Ekstrakcja AI nie działa
Sprawdź, czy klucz API jest ważny i czy model istnieje u Twojego dostawcy. Błędy wywołań AI są zapisywane w **Parametry zaawansowane → Logi** z prefiksem `[dfaicompetitor]`.
### E-maile nie docierają
Przetestuj konfigurację e-mail PrestaShop w **Parametry zaawansowane → E-mail**. Moduł korzysta z natywnego systemu poczty z własnymi szablonami FR i EN.
## Dobre praktyki i zgodność
- Zostaw włączone poszanowanie robots.txt. Obowiązuje przy odkrywaniu i przy czytaniu kart, honoruje opublikowany `Crawl-delay` i stosuje regułę pierwszeństwa standardu: gdy pasują zarówno `Allow`, jak i `Disallow`, wygrywa dłuższa reguła.
- Przy pierwszym indeksowaniu nieznanej witryny zachowaj opóźnienie między żądaniami co najmniej sekundy i rozsądny limit produktów.
- Rozszerz interwały odczytu: 6 do 24 h na adres w zupełności wystarcza do monitoringu cen.
- Zachowaj rozpoznawalny User-Agent. To uczciwa praktyka oczekiwana w obserwacji konkurencji, a niektóre witryny tolerują nazwanego robota, którego inaczej by zablokowały.
- Odczyt publicznych cen jest w Europie zasadniczo dozwolony, ale pozostajesz odpowiedzialny za wykorzystanie zebranych danych i za ocenę regulaminów odwiedzanych witryn.