GSC Connect: dokumentacja

GSC Connect sprowadza całą moc Google Search Console bezpośrednio do back office PrestaShop: połączenie OAuth jednym kliknięciem, przesyłanie sitemap, masowa inspekcja adresów URL, raporty kliknięć i pozycji per produkt i kategoria, automatyczne alerty spadków i deindeksacji. Ten przewodnik obejmuje instalację, konfigurację OAuth Google, pierwszą synchronizację, planowanie crona, odczyt raportów, rozwiązywanie typowych błędów i architekturę wewnętrzną.

Instalacja

Moduł wdraża się jak każdy standardowy moduł PrestaShop: żadnych zależności Composera, żadnego trwałego workera, żadnej usługi zewnętrznej poza Google.

1. Pobierz dfgscconnect.zip ze swojego konta DataFirefly (link do pobrania otrzymany po zamówieniu).
2. Back office → Moduły → Menedżer modułów → Wgraj moduł.
3. Przeciągnij i upuść ZIP. PrestaShop automatycznie instaluje 8 tabel dfgsc_*, zakładki menu i powiązane hooki.
4. Kliknij Konfiguruj na karcie modułu.

Wymagania

• PrestaShop 8.0.0 do 9.99.99
• PHP 7.4, 8.0, 8.1, 8.2 lub 8.3
• MySQL 5.6+ lub MariaDB 10.3+
• Włączone rozszerzenie PHP curl (domyślnie u wszystkich hostingodawców)
• Konto Google, które ma już dostęp właściciela lub właściciela delegowanego do witryny Search Console Twojego sklepu

Konfiguracja OAuth Google

Moduł używa OAuth 2.0, aby korzystać z Search Console w imieniu właściciela sklepu. Ten krok wykonuje się raz i zajmuje około 5 minut. Konto usługi nie jest wymagane: uwierzytelnianie korzysta bezpośrednio z konta Google, które ma już dostęp do Twojej witryny Search Console.

Krok 1: utworzenie projektu Google Cloud

1. Wejdź na console.cloud.google.com kontem Google, które ma dostęp do Search Console.
2. Kliknij selektor projektu u góry, a następnie Nowy projekt.
3. Nazwij go na przykład prestashop-gsc i utwórz.
4. Po utworzeniu wybierz ten nowy projekt.

Krok 2: włączenie API Search Console

1. Menu → API i usługi → Biblioteka.
2. Wyszukaj Google Search Console API.
3. Kliknij pozycję, a następnie Włącz.

Krok 3: konfiguracja ekranu zgody

1. Menu → API i usługi → OAuth consent screen.
2. Wybierz External, jeśli Twoje konto Google nie należy do organizacji Google Workspace, w przeciwnym razie Internal.
3. Podaj nazwę aplikacji (na przykład GSC Connect), adres wsparcia i domenę sklepu.
4. Na ekranie Scopes dodaj zakres https://www.googleapis.com/auth/webmasters (odczyt i zapis Search Console).
5. Na ekranie Test users dodaj swój adres Google. Dopóki ekran pozostaje w trybie testowym, to wystarczy do użytku prywatnego: nie trzeba zgłaszać aplikacji do weryfikacji przez Google.

Krok 4: utworzenie danych uwierzytelniających OAuth

1. Menu → API i usługi → Credentials.
2. Create Credentials → OAuth client ID.
3. Typ aplikacji: Web application.
4. Nazwa: GSC Connect (dowolna).
5. W Autoryzowanych źródłach JavaScript dodaj domenę swojego sklepu z protokołem HTTPS: https://twoj-sklep.pl.
6. W Autoryzowanym URI przekierowania wklej dokładny adres wyświetlony w konfiguracji modułu PrestaShop (ramka Adres przekierowania OAuth).
7. Kliknij Create. Google wyświetla Client ID i Client Secret.

Krok 5: wprowadzenie danych w PrestaShop

1. Back office → moduł → Konfiguruj.
2. Wklej Client ID i Client Secret.
3. Zapisz formularz. Pojawi się przycisk Połącz z Google.
4. Kliknij go. Zostaniesz przekierowany na stronę zgody Google.
5. Zatwierdź uprawnienia, wrócisz do BO PrestaShop.
6. Lista Twoich witryn Search Console jest pobierana automatycznie: moduł domyślnie wybiera tę, która odpowiada domenie sklepu.

Pierwsze uruchomienie

Po nawiązaniu połączenia OAuth uruchom pierwszą synchronizację, aby sprowadzić dane:

1. Zakładka Pulpit. Domyślna witryna jest już wybrana.
2. Kliknij Synchronizuj teraz. Moduł pobiera ostatnie 28 dni danych (kliknięcia, wyświetlenia, CTR, pozycja) na poziomie strony i zapytania. Licz od 30 sekund do 2 minut w zależności od wielkości katalogu.
3. Zakładka Sitemapy. Kandydaci są wykrywani automatycznie (/sitemap.xml w katalogu głównym plus wzorzec *_sitemap.xml generowany przez moduł gsitemap PrestaShop). Kliknij Prześlij obok każdej istotnej sitemapy.
4. Zakładka Inspekcja. Kliknij Zakolejkuj wszystkie aktywne produkty. Kolejka wypełnia się natychmiast. Faktyczne przetwarzanie odbywa się przez cron z poszanowaniem limitu Google wynoszącego 2000 inspekcji dziennie.

Pulpit

Pulpit gromadzi 8 KPI z 28 dni:

• Kliknięcia: łączna liczba kliknięć organicznych w oknie
• Wyświetlenia: łączna liczba wyświetleń w SERP
• Średni CTR: procent kliknięć względem wyświetleń
• Średnia pozycja: średnia ważona pozycja na wszystkich zapytaniach
• Nieprzeczytane alerty: liczba otwartych alertów do obsłużenia
• Strony niezaindeksowane: liczba przeinspekowanych stron, których werdykt Google to FAIL lub NEUTRAL
• Limit dnia: wywołania API Inspekcji zużyte z dziennego limitu
• Ostatnia synchronizacja: data i godzina ostatniego przebiegu crona sync

Pod KPI wykres ewolucji z 28 dni pokazuje kliknięcia (linia ciągła) i wyświetlenia (linia przerywana na osi pomocniczej). Chart.js jest dołączony lokalnie, żadna zależność CDN nie jest ładowana.

Po prawej stronie Top 10 produktów i Top 10 kategorii porządkują strony po kliknięciach, ze średnią pozycją i CTR. Rozwiązywanie adresu URL na encję używa natywnego routingu PrestaShop: wzorzec id-slug dla produktów, link_rewrite dla kategorii, cms_lang dla stron CMS.

Raporty kliknięć i pozycji

Zakładka Raporty oferuje trzy szczegółowe widoki: Produkty, Kategorie, Zapytania. Każdy widok przyjmuje konfigurowalny lookback: 7 / 14 / 28 / 90 dni.

Dla każdego wiersza otrzymujesz kliknięcia, wyświetlenia, CTR i średnią pozycję. Kliknij dowolny nagłówek kolumny, aby posortować (sortowanie po stronie klienta, natychmiastowe). Eksport CSV tworzy plik UTF-8 z BOM i separatorem średnikowym (natywnie zgodny z Excelem), do 5000 wierszy na eksport.

Porównanie okien

Dla każdego wylistowanego produktu lub kategorii raport pokazuje też zmianę względem poprzedniego okna o tej samej długości. Istotny spadek pozycji wyświetla się na czerwono, poprawa na zielono.

Sitemapy

Zakładka Sitemapy automatycznie wykrywa kandydatów w Twoim sklepie:

• https://twoj-sklep.pl/sitemap.xml: sitemapa w katalogu głównym
• https://twoj-sklep.pl/sitemap_index.xml: indeks sitemap
• Wzorzec *_sitemap.xml w katalogu głównym: generowany przez moduł gsitemap PrestaShop, jeden plik na sklep i język

Przesyłasz jednym kliknięciem. Moduł śledzi następnie za Ciebie:

• Liczbę przesłanych adresów URL (zadeklarowaną przez sitemapę)
• Liczbę adresów faktycznie zaindeksowanych (raportowaną przez Google)
• Liczbę błędów wykrytych przez Google
• Datę ostatniego pobrania przez Googlebota

Jeśli Google wykryje błędy w sitemapie, podnoszony jest automatyczny alert: ważność HIGH przy co najmniej 10 błędach, w przeciwnym razie MEDIUM.

Masowa inspekcja adresów URL

API URL Inspection Google jest ograniczone do 2000 wywołań dziennie na witrynę. GSC Connect zarządza tym limitem przez kolejkę z automatycznym retry.

Dostępne akcje

• Zakolejkuj wszystkie aktywne produkty: dodaje wszystkie produkty z widocznością both, search lub catalog
• Zakolejkuj wszystkie kategorie: dodaje wszystkie aktywne kategorie (katalog główny jest wykluczony)
• Przeinspekuj zmodyfikowane strony: dodaje wyłącznie encje oznaczone jako przeterminowane przez hooki actionProductUpdate i actionCategoryUpdate
• Przetwórz kolejkę teraz: do testów, bez czekania na cron
• Zainspekuj pojedynczy adres URL: aby zweryfikować natychmiastową poprawkę na konkretnej stronie

Zapisywane dane

Dla każdego zainspekowanego adresu URL moduł zapisuje:

• Globalny werdykt Google: PASS, PARTIAL, FAIL lub NEUTRAL
• Stan pokrycia (Indexed, Discovered, Crawled but not indexed itd.)
• Status robots.txt i zadeklarowaną indeksowalność
• Wykryte wyniki rozszerzone (Product, Breadcrumb, Review itd.)
• Status AMP i zgodność mobile-friendly
• Sitemapę odsyłającą i adresy odsyłające
• Datę ostatniego crawlowania przez Googlebota

Alerty i spadki

Moduł obsługuje automatycznie trzy rodziny alertów:

Spadki pozycji

Wykrywa istotny spadek pozycji na stronie już dobrze sklasyfikowanej. Domyślnie: spadek o 5 miejsc lub więcej na stronie na pozycji nie gorszej niż 50. Próg regulowany w konfiguracji (DFGSC_DROP_POS).

Spadki kliknięć

Wykrywa istotny spadek liczby kliknięć na stronie, która generowała minimalny wolumen. Domyślnie: spadek o 30 % przy minimum 5 kliknięć w poprzednim oknie. Progi regulowane w konfiguracji (DFGSC_DROP_CLICKS, DFGSC_DROP_MIN_CLICKS).

Deindeksacje

Podnoszone automatycznie, gdy zainspekowany adres URL wraca z werdyktem FAIL lub NEUTRAL, albo ze stanem pokrycia DEINDEXED / INDEXING_NOT_ALLOWED.

Mechanika porównania

Porównanie spadków odbywa się w oknie kroczącym 7 dni względem 7 dni poprzednich, z przesunięciem 2 dni ze względu na opóźnienie Search Console. Moduł porównuje D-9..D-2 z D-16..D-9.

Deduplikacja 24h

Ten sam alert (ta sama strona, ten sam typ) uruchamia się tylko raz na 24h, aby uniknąć szumu, nawet jeśli cron działa co godzinę.

Powiadomienia e-mail

Alerty mogą być wysyłane e-mailem jako digest HTML pogrupowany po ważności, po francusku lub angielsku. Włącz je w konfiguracji i podaj adres odbiorcy.

Cron i planowanie

Wszystkie zadania w tle przechodzą przez jeden endpoint chroniony tokenem, widoczny na stronie konfiguracji:

https://twoj-sklep.pl/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXXXXXXXX

Zaplanuj go co 1 do 6 godzin z panelu cron swojego hostingu (cPanel, Plesk, o2switch, OVH). Przykład crontab:

0 */2 * * * curl -fsS "https://twoj-sklep.pl/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX" > /dev/null 2>&1

Wykonywane zadania

Domyślnie endpoint wykonuje wszystkie zadania. Część możesz odfiltrować parametrem &tasks=:

Zadanie	Akcja
sync	Pobranie nowych danych Search Analytics (konfigurowalny lookback)
inspect	Przetworzenie kolejki inspekcji adresów URL z poszanowaniem limitu
sitemaps	Odświeżenie statusu przesłanych sitemap
drops	Wykrycie spadków pozycji i kliknięć
notify	Wysyłka digestu alertów e-mailem
prune	Czyszczenie zakończonych wpisów kolejki i starych liczników limitu

Przykład, aby synchronizować tylko metryki bez dotykania inspekcji:

curl "https://twoj-sklep.pl/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX&tasks=sync,drops,notify"

Konfiguracja referencyjna

Wszystkie opcje znajdują się na stronie Konfiguruj modułu:

Opcja	Klucz	Domyślnie
Client ID Google	DFGSC_CLIENT_ID	(do uzupełnienia)
Client Secret Google	DFGSC_CLIENT_SECRET	(do uzupełnienia)
Lookback synchronizacji (dni)	DFGSC_LOOKBACK_DAYS	28
Dzienny limit inspekcji URL	DFGSC_DAILY_QUOTA	2000
Próg spadku pozycji	DFGSC_DROP_POS	5
Próg spadku kliknięć (%)	DFGSC_DROP_CLICKS	30
Minimum kliknięć do wykrycia spadku	DFGSC_DROP_MIN_CLICKS	5
Powiadomienia e-mail włączone	DFGSC_ALERT_ENABLED	tak
Adres odbiorcy alertów	DFGSC_ALERT_EMAIL	e-mail administratora
Token crona	DFGSC_CRON_TOKEN	generowany automatycznie

Limity i ograniczenia API Google

API Search Console jest bezpłatne, ale podlega limitom Google:

• URL Inspection: 2000 wywołań dziennie na witrynę, 600 na minutę (twardy limit Google, nienegocjowalny)
• Search Analytics: 25000 wierszy na wywołanie, około 1200 wywołań na minutę, 30000 dziennie (limit miękki)
• Sitemaps: 5000 wywołań dziennie

Moduł zapisuje wszystkie wywołania per endpoint i per dzień w tabeli dfgsc_quota. Kolejka inspekcji zatrzymuje się czysto po osiągnięciu skonfigurowanego limitu, generując alert o ważności MEDIUM. Liczniki są automatycznie czyszczone po 30 dniach przez zadanie prune.

Architektura i dane

Moduł ma klasyczną architekturę PSR-4 pod namespace DataFireflyGscConnect, z własnym autoloaderem dostarczonym w vendor/autoload.php. Żadnych zależności Composera. Żadnych zależności zewnętrznych: wywołania Google API odbywają się w natywnym cURL z weryfikacją SSL.

Warstwy

• Api: klienci HTTP (GoogleOAuth, SearchConsoleClient)
• Model: repozytoria dostępu do bazy (Token, Site, Metric, Inspection, Sitemap, Alert, Queue, Quota)
• Services: orkiestracja (MetricsSync, Inspection, Sitemap, Alert)

Tworzone tabele

Tabela	Rola
dfgsc_token	Refresh token OAuth i wygaśnięcie per sklep
dfgsc_site	Znane witryny Search Console (per sklep, z witryną domyślną)
dfgsc_metric	Wiersze Search Analytics (per dzień, per strona, opcjonalnie per zapytanie)
dfgsc_inspection	Lokalny cache inspekcji adresów URL z pełnym werdyktem
dfgsc_sitemap	Stan przesłanych sitemap (adres, przesłane, zaindeksowane, błędy, ostatnie pobranie)
dfgsc_alert	Wygenerowane alerty (typ, ważność, strona, delta, status)
dfgsc_queue	Kolejka inspekcji ze statusami pending/processing/done/failed
dfgsc_quota	Liczniki wywołań API per endpoint i per dzień

Używane hooki

• actionAdminControllerSetMedia: ładowanie zasobów BO
• displayBackOfficeHeader: zarezerwowany na przyszłe powiadomienia
• actionProductUpdate / actionCategoryUpdate: unieważnienie cache inspekcji
• actionObjectProductDeleteAfter / actionObjectCategoryDeleteAfter: czyszczenie osieroconych inspekcji

Bezpieczeństwo

• CSRF state token oparty na cookie w przepływie OAuth
• Walidacja hash_equals na tokenie crona
• Refresh token przechowywany w bazie, nigdy nie logowany
• Access token nigdy nietrwały: regenerowany na żądanie z refresh tokena i trzymany w pamięci na czas żądania
• Pliki index.php anty-listing we wszystkich podkatalogach
• Systematyczne escapowanie przez Tools::safeOutput na wszystkich wyjściach szablonów

Rozwiązywanie problemów

Przycisk „Połącz z Google” nie pojawia się

Sprawdź, czy Client ID i Client Secret zostały zapisane. Zapisz formularz, a następnie przeładuj stronę konfiguracji.

Ekran Google pokazuje redirect_uri_mismatch

URI przekierowania w Google Cloud musi być identyczny co do znaku z tym wyświetlonym w konfiguracji modułu: ten sam protokół (https), ta sama subdomena (www lub bez), ta sama ścieżka, bez końcowego ukośnika. Kopiuj i wklej bez modyfikacji.

Synchronizacja nie sprowadza danych

Sprawdź trzy punkty: (1) wybrana witryna to faktycznie Twój sklep; (2) ma co najmniej 72 h historii w Search Console (Google udostępnia dane z około 48 h opóźnienia); (3) połączone konto Google ma dostęp właściciela lub właściciela delegowanego do tej witryny.

Inspekcje się nie wykonują

Sprawdź, czy cron jest zaplanowany i czy się wykonuje. Następnie sprawdź limit dnia: jeśli zużyłeś 2000 wywołań Google, kolejka jest wstrzymana do następnego dnia. Możesz wymusić ręcznie przyciskiem Przetwórz kolejkę teraz.

Alerty e-mail nie docierają

Sprawdź, czy podany adres jest poprawny, czy konfiguracja SMTP PrestaShop działa (przetestuj na przykład e-mailem powitalnym) i czy powiadomienia są włączone w konfiguracji modułu.

Błąd 401 lub 403 na wywołaniach Search Console

Refresh token został prawdopodobnie rewokowany po stronie Google (zmiana hasła, zabezpieczenia konta lub wygasła zgoda). Rozłącz i połącz sklep ponownie z poziomu konfiguracji.

Błąd Quota Exhausted (429)

Limit Google dla witryny został osiągnięty. Google ogranicza go do 2000 inspekcji dziennie, niezależnie od liczby modułów czy narzędzi odpytujących witrynę. Kolejka wznawia się automatycznie następnego dnia.

Changelog

Pełną listę zmian per wersja znajdziesz w pliku CHANGELOG.md dołączonym do ZIP modułu.

---

W przypadku pytań nieomówionych tutaj skontaktuj się ze wsparciem DataFirefly pod adresem support@datafirefly.com.