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 jednym kliknięciem wygenerować ustrukturyzowany brief treści przez Mistrala, OpenAI lub Claude.

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.

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

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

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.