# Predictive SEO: kompletna dokumentacja
> Przegląd DataFirefly Predictive SEO łączy Twój PrestaShop z Google Search Console, stosuje wbudowany silnik predykcji ML na historii wyszukiwań i automatycznie identyfikuje nadchodzące szczyty sezonowe. Dla każdej wykrytej szansy możesz…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfpredictiveseo/index.md), [en](https://www.datafirefly.com/en/documentation/dfpredictiveseo/index.md), [es](https://www.datafirefly.com/es/documentation/dfpredictiveseo/index.md), [de](https://www.datafirefly.com/de/documentation/dfpredictiveseo/index.md), [it](https://www.datafirefly.com/it/documentation/dfpredictiveseo/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfpredictiveseo/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfpredictiveseo/index.md)
- Indeks:
## Przegląd
DataFirefly Predictive SEO łączy Twój PrestaShop z Google Search Console, stosuje wbudowany silnik predykcji ML na historii wyszukiwań i automatycznie identyfikuje nadchodzące szczyty sezonowe. Dla każdej wykrytej szansy możesz jednym kliknięciem wygenerować ustrukturyzowany brief treści przez Mistrala, OpenAI lub Claude.
**Do zapamiętania:** Predictive SEO nie mierzy tego, co się wydarzyło, tylko projektuje to, co się wydarzy. Moduł działa czysto wyprzedzająco: publikujesz treść dwa tygodnie przed szczytem wyszukiwań i zajmujesz pozycję przed falą.
### Wymagania
- PrestaShop 8.0+ albo PrestaShop 9.x
- PHP minimum 8.1
- MySQL 5.7+ albo MariaDB 10.3+
- Konto Google z dostępem do usługi Search Console sklepu
- Klucz API dostawcy AI (Mistral, OpenAI albo Anthropic; domyślnie Mistral, około 0,002 euro za brief)
- Co najmniej 60 do 90 dni historii GSC dla wiarygodnych predykcji
## Instalacja
### Instalacja z pliku ZIP
1. Pobierz plik `dfpredictiveseo.zip` ze swojego konta klienta DataFirefly.
2. W zapleczu PrestaShop przejdź do **Moduły > Menedżer modułów**.
3. Kliknij **Wgraj moduł** i wskaż plik ZIP.
4. Moduł instaluje się automatycznie, tworzy 7 tabel `dfpseo_*`, rejestruje 6 zakładek pod IMPROVE i generuje unikalny token crona.
5. Po instalacji znajdziesz moduł w menu **Ulepszenia > Predictive SEO**.
**Aktualizacja:** Przy przyszłej aktualizacji wgranie nowego pliku ZIP nadpisuje pliki i automatycznie uruchamia skrypty `upgrade-X.Y.Z.php`. Dane i konfiguracja są zachowywane.
### Schemat bazy danych
Instalacja tworzy 7 tabel z prefiksem `dfpseo_`:
- `dfpseo_keyword`: słowa kluczowe śledzone z GSC
- `dfpseo_history`: historia dzienna (wyświetlenia, kliknięcia, CTR, pozycja)
- `dfpseo_forecast`: predykcje dzienne z przedziałami ufności
- `dfpseo_opportunity`: wykryte szanse sezonowe
- `dfpseo_recommendation`: briefy treści wygenerowane przez AI
- `dfpseo_seasonality`: indeksy sezonowe (dzień tygodnia × miesiąc) per słowo kluczowe
- `dfpseo_sync_log`: dziennik synchronizacji GSC
## Konfiguracja Google Search Console
Moduł korzysta ze standardowego protokołu OAuth2. Tworzysz OAuth Client w Google Cloud, wklejasz dane logowania w ustawieniach i uruchamiasz flow autoryzacji przyciskiem Połącz.
### Krok 1: utwórz projekt Google Cloud
1. Wejdź na [console.cloud.google.com](https://console.cloud.google.com/) i zaloguj się kontem Google, które ma dostęp do Twojej usługi Search Console.
2. Kliknij selektor projektu w lewym górnym rogu, a następnie **Nowy projekt**.
3. Nazwij go na przykład _DataFirefly Predictive SEO_ i utwórz.
### Krok 2: włącz API Search Console
1. W menu po lewej przejdź do **APIs & Services > Biblioteka**.
2. Wyszukaj _Search Console API_ i kliknij **Włącz**.
### Krok 3: skonfiguruj ekran zgody OAuth
1. Przejdź do **APIs & Services > Ekran zgody OAuth**.
2. Typ użytkownika: **Zewnętrzny**.
3. Uzupełnij nazwę aplikacji, e-mail wsparcia i autoryzowaną domenę (Twój sklep).
4. W sekcji **Zakresy** dodaj `https://www.googleapis.com/auth/webmasters.readonly` (Search Console tylko do odczytu).
5. W trybie testowym dodaj swój e-mail w **Użytkownicy testowi**. Możesz później przejść do produkcji bez zmian w module.
### Krok 4: utwórz Client OAuth
1. Przejdź do **APIs & Services > Dane logowania**.
2. Kliknij **Utwórz dane logowania > Identyfikator klienta OAuth**.
3. Typ aplikacji: **Aplikacja internetowa**.
4. Nazwa: dowolna (na przykład _Predictive SEO Production_).
5. Autoryzowany URI przekierowania: skopiuj adres wyświetlony w ustawieniach modułu (**Improve > Predictive SEO > Ustawienia > Google Search Console > URI przekierowania**). Format: `https://twoj-sklep.pl/module/dfpredictiveseo/settings/oauth_callback`.
6. Kliknij **Utwórz**. Google wyświetli `client_id` i `client_secret`.
### Krok 5: połącz moduł
1. W ustawieniach Predictive SEO wklej `client_id` i `client_secret`.
2. Zapisz.
3. Kliknij **Połącz z Google Search Console**.
4. Zostaniesz przekierowany na stronę zgody Google. Zezwól na dostęp tylko do odczytu.
5. Po powrocie do zaplecza moduł ma zapisany zaszyfrowany `refresh_token` i jest gotowy do synchronizacji.
6. Następnie wybierz w rozwijanej liście **usługę Search Console** do śledzenia (moduł wykrywa ją automatycznie po połączeniu).
**Uwaga:** URI przekierowania musi być **identyczny co do znaku** po stronie Google Cloud i modułu. Różnica w protokole (http lub https), końcowym ukośniku albo subdomenie powoduje błąd `redirect_uri_mismatch`.
## Konfiguracja dostawcy AI
Moduł obsługuje 3 dostawców AI do generowania briefów treści. Potrzebujesz tylko jednego i podajesz własny klucz API wybranego dostawcy. DataFirefly nie pobiera żadnej prowizji od użycia.
### Mistral (domyślny, zalecany)
- Model: `mistral-small-latest`
- Koszt orientacyjny: około 0,002 euro za wygenerowany brief
- Utworzenie klucza: [console.mistral.ai](https://console.mistral.ai/) > API Keys
- Wklej klucz w **Ustawienia > Dostawca AI > Klucz API Mistral**
### OpenAI
- Model: `gpt-4o-mini`
- Koszt orientacyjny: około 0,005 euro za brief
- Utworzenie klucza: [platform.openai.com](https://platform.openai.com/api-keys) > API keys
- Wklej klucz w **Ustawienia > Dostawca AI > Klucz API OpenAI**
### Anthropic (Claude)
- Model: `claude-3-5-haiku-latest`
- Koszt orientacyjny: około 0,004 euro za brief
- Utworzenie klucza: [console.anthropic.com](https://console.anthropic.com/) > API Keys
- Wklej klucz w **Ustawienia > Dostawca AI > Klucz API Anthropic**
Następnie wybierz aktywnego dostawcę w rozwijanej liście **Aktywny dostawca AI**. Po zmianie dostawcy wcześniej wygenerowane briefy nie są regenerowane automatycznie.
## Synchronizacja danych
### Pierwsza synchronizacja
Po nawiązaniu połączenia z GSC uruchom pierwszą ręczną synchronizację: **Ustawienia > Uruchom synchronizację**. Moduł pobiera historię z ostatnich 90 dni dla wybranej usługi, do 250 000 wierszy na synchronizację, z wymiarami _data × zapytanie × strona_. Pierwsza synchronizacja może zająć od 30 sekund do 2 minut, zależnie od wolumenu.
### Codzienny cron
Do automatycznych synchronizacji skonfiguruj codzienny cron (zalecana pora: wcześnie rano, między 4 a 6) wywołujący zabezpieczony endpoint modułu.
Dokładny adres i token są wyświetlane w **Ustawienia > Cron**. Format ogólny:
```
https://twoj-sklep.pl/module/dfpredictiveseo/cron/sync?token=TWOJ_WYGENEROWANY_TOKEN
```
Przykładowa linia crontab (cron uniksowy):
```
0 5 * * * curl -s "https://twoj-sklep.pl/module/dfpredictiveseo/cron/sync?token=TWOJ_TOKEN" > /dev/null 2>&1
```
**Wskazówka:** Token jest generowany losowo przy instalacji i zapisywany w tabeli konfiguracji PrestaShop (`DFPSEO_CRON_TOKEN`). Jeśli zostanie ujawniony, możesz go wygenerować ponownie w **Ustawienia > Wygeneruj ponownie token crona**.
### Przebieg synchronizacji
Każda synchronizacja wykonuje po kolei:
1. Pobranie z GSC danych z ostatnich 90 dni w oknie kroczącym (wymiary data, zapytanie, strona)
2. Wstawienie lub aktualizację w `dfpseo_keyword` i `dfpseo_history`
3. Przeliczenie indeksów sezonowych (dla słów kluczowych z wystarczającą historią)
4. Wygenerowanie prognoz na skonfigurowanym horyzoncie
5. Wykrycie szans w oknie przyszłym
6. Zapis do `dfpseo_sync_log`
## Pulpit
Pulpit (**Improve > Predictive SEO > Tablica**) zbiera kluczowe wskaźniki:
- **4 karty KPI**: śledzone słowa kluczowe, nadchodzące szanse, przewidywane kliknięcia w 14 dni, ostatnia synchronizacja GSC
- **Wykres główny**: zagregowana krzywa historyczna (90 dni) plus prognoza (skonfigurowany horyzont, domyślnie 30 dni), z pasmem ufności 95 %
- **Najlepsze szanse**: 10 najbliższych szczytów sezonowych posortowanych według score
- **Dziennik synchronizacji**: 5 ostatnich synchronizacji wraz ze statusem
### Status połączenia
Dwie plakietki u góry pulpitu pokazują stan integracji: **GSC połączony** (zielona lub czerwona) i **Dostawca AI skonfigurowany** (zielona lub czerwona). Jeśli któraś jest czerwona, skorzystaj z bezpośredniego linku do odpowiednich ustawień.
## Słowa kluczowe i prognozy
### Lista słów kluczowych
Zakładka **Słowa kluczowe** wyświetla natywny grid PrestaShop ze wszystkimi zsynchronizowanymi zapytaniami. Kolumny: zapytanie, strona docelowa, wyświetlenia 30 dni, kliknięcia 30 dni, CTR, średnia pozycja, ostatnia aktualizacja. Możesz filtrować, sortować i eksportować.
### Widok szczegółowy słowa kluczowego
Kliknięcie w słowo kluczowe otwiera jego kartę:
- Indywidualna krzywa historyczna plus własna prognoza
- Przedział ufności 95 % wokół predykcji
- Heatmapa sezonowa 12 × 7 (miesiąc × dzień tygodnia)
- Wyliczone indeksy sezonowe
- Lista szans powiązanych z tym słowem kluczowym
### Heatmapa sezonowości
Heatmapa wizualizuje multiplikatywne indeksy sezonowe. Odczyt:
- Komórka 1,00: średni ruch dla tej kombinacji miesiąc × dzień
- Komórka 1,50: ruch 50 % powyżej średniej (szczyt sezonowy)
- Komórka 0,60: ruch 40 % poniżej średniej (dołek)
Komórki są kolorowane od jasnoniebieskiego (dołek) po głęboki niebieski i czerwono-pomarańczowy (szczyt). Jedno spojrzenie wystarczy, aby wyłapać tygodnie warte wykorzystania.
## Szanse sezonowe
### Automatyczne wykrywanie
Szansa jest wykrywana, gdy w przyszłym oknie 14 dni (konfigurowalnym przez `DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS`):
- Predykcja przekracza baseline słowa kluczowego × 1,25 (**próg szczytu**)
- ORAZ indeks sezonowy kombinacji miesiąc × dzień jest wyższy niż 1,10
Sąsiadujące szczyty (przerwa nie większa niż 2 dni) są łączone w jedną szansę obejmującą całe okno.
### Score szansy
Score łączy trzy czynniki:
```
score = oczekiwane_kliknięcia × lift × zaufanie
```
- `oczekiwane_kliknięcia`: suma przewidywanych kliknięć w oknie
- `lift`: stosunek szczytu do baseline
- `zaufanie`: szerokość przedziału predykcji (im węższy przedział, tym wyższy score)
Score powyżej 80 oznacza szansę o wysokim potencjale i silnym sygnale sezonowym. Score od 40 do 80 oznacza szansę umiarkowaną. Poniżej 40 sygnał jest zbyt słaby lub zbyt niepewny, aby uzasadnić działanie priorytetowe.
### Workflow szansy
Każda szansa ma status:
- **Nowa**: świeżo wykryta, czeka na decyzję
- **W toku**: brief został wygenerowany, trwa praca redakcyjna
- **Obsłużona**: treść opublikowana, szansa wykorzystana
- **Zignorowana**: decyzja o nieobsługiwaniu (fałszywy pozytyw, poza strategią)
## Rekomendacje AI
### Generowanie briefu
Z poziomu dowolnej szansy kliknij **Wygeneruj brief**. Moduł wysyła żądanie do aktywnego dostawcy AI wraz z kontekstem słowa kluczowego (wolumen, sezonowość, aktualna pozycja, powiązana strona) i otrzymuje ustrukturyzowany brief JSON zawierający:
- **summary**: strategiczne streszczenie briefu
- **meta_description**: meta description SEO gotowa do wklejenia (150 do 160 znaków)
- **search_intent**: dominująca intencja wyszukiwania (informacyjna, transakcyjna, nawigacyjna, komercyjna)
- **outline**: szczegółowy plan h1/h2/h3 artykułu albo strony
- **keywords_to_include**: słowa kluczowe semantyczne do uwzględnienia
- **internal_links**: sugestie linkowania wewnętrznego do innych stron serwisu
- **rationale**: strategiczne uzasadnienie rekomendacji
Generowanie zajmuje od 1 do 3 sekund, zależnie od dostawcy.
### Workflow zatwierdzania
Każdy brief przechodzi przez statusy:
1. **Pending**: wygenerowany, czeka na przegląd
2. **Approved**: zatwierdzony do redakcji
3. **Published**: treść opublikowana (oznaczane ręcznie)
4. **Rejected**: odrzucony (brief słabej jakości albo nie na temat)
5. **Draft**: w trakcie modyfikacji
Workflow pozwala zachować czytelny ślad tego, co zostało obsłużone.
## Architektura techniczna
### Stack
- Architektura PSR-4, przestrzeń nazw `DfPredictiveSeo` odwzorowana na `src/`
- Kontrolery Symfony rozszerzające `FrameworkBundleAdminController`
- Repozytoria Doctrine DBAL (bez ObjectModel)
- GSC odpytywane bezpośrednio przez REST z cURL i OAuth2 (bez `google/apiclient`, dla lekkości)
- Żadnej obowiązkowej zależności Composera przy instalacji (wbudowany autoloader PSR-4)
### Pipeline ML
1. **Multiplikatywna dekompozycja sezonowa**: indeksy dnia tygodnia i miesiąca wyliczane wyśrodkowaną średnią kroczącą 28 dni i średnią przyciętą o 10 %
2. **Regresja OLS** na `log(wyświetlenia+1)` dla modelowania trendu log-liniowego
3. **Prognoza**: `exp(predykcja_log) × indeks_sezonowy_dnia × indeks_sezonowy_miesiąca`
4. **Przedziały 95 %**: aproksymacja Studenta na błędzie resztowym regresji, stopniowo poszerzana wraz z horyzontem
### Endpoint crona
Endpoint jest publiczny, ale zabezpieczony tokenem. Przykład w PHP do wywołania programowego:
```
$token = 'twoj_token_crona';
$url = 'https://twoj-sklep.pl/module/dfpredictiveseo/cron/sync?token=' . $token;
$response = file_get_contents($url);
$data = json_decode($response, true);
// $data['status'] = 'ok' | 'error'
// $data['keywords_synced'] = liczba zaktualizowanych słów kluczowych
// $data['opportunities_detected'] = liczba nowo wykrytych szans
```
### Zmienne konfiguracyjne
Moduł zapisuje 18 kluczy konfiguracji w tabeli `ps_configuration`:
- `DFPSEO_GSC_CLIENT_ID`, `DFPSEO_GSC_CLIENT_SECRET`, `DFPSEO_GSC_REFRESH_TOKEN` (zaszyfrowany), `DFPSEO_GSC_PROPERTY`
- `DFPSEO_AI_PROVIDER`, `DFPSEO_AI_MISTRAL_KEY`, `DFPSEO_AI_OPENAI_KEY`, `DFPSEO_AI_ANTHROPIC_KEY`
- `DFPSEO_FORECAST_HORIZON_DAYS` (domyślnie 30)
- `DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS` (domyślnie 14)
- `DFPSEO_PEAK_THRESHOLD` (domyślnie 1.25)
- `DFPSEO_SEASONAL_THRESHOLD` (domyślnie 1.10)
- `DFPSEO_CRON_TOKEN` (generowany przy instalacji)
- `DFPSEO_LAST_SYNC`, `DFPSEO_LAST_FORECAST`
## Rozwiązywanie problemów
### Błąd `redirect_uri_mismatch` przy łączeniu z GSC
URI przekierowania skonfigurowany w Google Cloud nie odpowiada dokładnie temu, którego oczekuje moduł. Sprawdź:
- Protokół: `https://`, nie `http://`
- Brak ukośnika na końcu: `...oauth_callback`, nie `...oauth_callback/`
- Subdomena: `www.` albo jej brak, zależnie od sklepu, musi się zgadzać
### Synchronizacja GSC nie zwraca żadnego słowa kluczowego
- Sprawdź, czy usługa wybrana w ustawieniach jest tą, która faktycznie odbiera ruch SEO (a nie pustą usługą domenową)
- Sprawdź, czy połączone konto Google jest _właścicielem_ albo _autoryzowanym użytkownikiem_ tej usługi
- Usługa musi mieć przynajmniej kilka dni zindeksowanej historii (Google Search Console publikuje dane z 2 do 3 dni opóźnienia)
### Predykcje wydają się mało wiarygodne
- Sprawdź, czy masz co najmniej 60 do 90 dni historii. Poniżej tego progu indeksy sezonowe nie mogą być poprawnie oszacowane
- Dla słów kluczowych nieregularnych (mało sygnału, dużo szumu) przedział 95 % jest celowo szerszy: moduł wyraźnie sygnalizuje niskie zaufanie
- Dla dokładniejszych predykcji na długich horyzontach (60 do 90 dni) poczekaj na zgromadzenie 6 do 12 miesięcy historii. Silnik poprawia się z czasem
### Endpoint crona zwraca błąd 403
Token przekazany w query stringu nie odpowiada `DFPSEO_CRON_TOKEN`. Sprawdź dokładną wartość w **Ustawienia > Cron**. W razie wątpliwości wygeneruj token ponownie i zaktualizuj crontab.
### Brief AI nie jest generowany
- Sprawdź, czy wkleiłeś prawidłowy klucz API dla wybranego aktywnego dostawcy
- Sprawdź saldo w konsoli dostawcy (Mistral, OpenAI albo Anthropic)
- Jeśli dostawca zwraca błąd rate limitu, odczekaj kilka minut i spróbuj ponownie
- Wygenerowane briefy są zapisywane w `dfpseo_recommendation`; w razie błędu jest on również logowany w tej tabeli ze statusem `error`
## FAQ
### Czy moduł działa bez Google Search Console?
Nie, GSC jest podstawowym źródłem danych. Moduł potrzebuje minimum 60 do 90 dni historii, aby produkować wiarygodne predykcje i wyliczać sezonowość. Jeśli Twój sklep dopiero wystartował, poczekaj na co najmniej 2 miesiące zindeksowanych danych przed instalacją modułu.
### Ile kosztuje brief AI?
To zależy od wybranego dostawcy. Przy Mistralu (domyślnym) licz około 0,002 euro za brief. OpenAI GPT-4o-mini około 0,005 euro. Claude Haiku około 0,004 euro. Podajesz własny klucz API i płacisz bezpośrednio dostawcy. DataFirefly nie pobiera żadnej prowizji.
### Ile słów kluczowych może śledzić moduł?
Nie ma limitu zapisanego na sztywno w kodzie. Standardowa synchronizacja pobiera do 250 000 wierszy (data × zapytanie × strona) na wywołanie, co pokrywa niemal wszystkie sklepy. Powyżej tej skali zwiększ pamięć PHP przydzieloną workerowi crona.
### Czy moduł jest zgodny z innymi modułami SEO?
Tak, Predictive SEO nigdy nie zapisuje niczego na kartach produktów ani w metadanych: wyłącznie czyta GSC i produkuje rekomendacje. Jest w pełni zgodny ze wszystkimi istniejącymi modułami SEO (DataFirefly i zewnętrznymi).
### Czy moje dane z GSC są przechowywane u DataFirefly?
Nie. Wszystkie dane pozostają na Twoim serwerze, w Twojej bazie PrestaShop. Moduł wywołuje bezpośrednio API Google Twoimi danymi logowania OAuth i bezpośrednio dostawców AI Twoim kluczem API. Żadne dane nie przechodzą przez serwery DataFirefly.
### Który horyzont predykcji jest najbardziej wiarygodny?
Horyzont od 7 do 14 dni jest bardzo wiarygodny (wąski przedział 95 %). Horyzont od 30 do 60 dni ma charakter orientacyjny (przedział szerszy). Powyżej 90 dni predykcje stają się mało przydatne do decyzji operacyjnych: moduł je wylicza, ale sygnalizuje niskie zaufanie.