# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfgscconnect/index.md), [en](https://www.datafirefly.com/en/documentation/dfgscconnect/index.md), [es](https://www.datafirefly.com/es/documentation/dfgscconnect/index.md), [de](https://www.datafirefly.com/de/documentation/dfgscconnect/index.md), [it](https://www.datafirefly.com/it/documentation/dfgscconnect/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfgscconnect/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfgscconnect/index.md)
- Indeks:
**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.
**Natywny multistore.** Moduł jest wielosklepowy. Każdy sklep przechowuje własny token OAuth, własną witrynę Search Console i własną historię metryk. Możesz podłączyć jeden sklep bez dotykania pozostałych.
### 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](https://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**.
**Adres przekierowania musi być identyczny co do znaku.** Łącznie z protokołem (`https`), subdomeną (`www` lub bez) i brakiem końcowego ukośnika. Wystarczy jedna różnica i Google blokuje połączenie błędem `redirect_uri_mismatch`.
### 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.
**Opóźnienie Search Console.** Google udostępnia dane Search Analytics z około 48 h opóźnienia. Jeśli dopiero co się połączyłeś, część metryk z wczoraj lub przedwczoraj nie będzie jeszcze dostępna. To normalne. Moduł uwzględnia to automatycznie w obliczeniach spadków (okno kroczące z przesunięciem 2 dni).
## 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
**Wykryta deindeksacja podnosi automatyczny alert.** Jeśli werdykt to FAIL lub NEUTRAL, albo stan pokrycia to DEINDEXED lub INDEXING_NOT_ALLOWED, automatycznie podnoszony jest alert HIGH z powodem zwróconym przez Google.
## 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"
```
**Zgodny z hostingiem współdzielonym.** Żadnych zależności od Redisa, BullMQ, trwałego workera ani dedykowanego PHP-FPM. Endpoint cron to zwykły adres HTTPS chroniony tokenem. Działa natywnie na o2switch, współdzielonym OVH i każdym standardowym hostingu Linux.
## 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._