GSC Connect: volledige gids

GSC Connect brengt alle kracht van Google Search Console direct in de PrestaShop back-office: OAuth-verbinding in één klik, sitemaps indienen, URL-inspectie in bulk, klik- en positierapporten per product en categorie, automatische meldingen bij dalingen en de-indexering. Deze gids behandelt de installatie, de Google OAuth-configuratie, de eerste synchronisatie, de cronplanning, het lezen van de rapporten, het oplossen van veelvoorkomende fouten en de interne architectuur.

Installatie

De module wordt uitgerold zoals elke standaard PrestaShop-module: geen Composer-afhankelijkheid, geen persistente worker, geen externe dienst behalve Google.

1. Download dfgscconnect.zip vanuit uw DataFirefly-account (downloadlink ontvangen na bestelling).
2. Back-office → Modules → Modulebeheer → Een module uploaden.
3. Sleep de ZIP erin. PrestaShop installeert automatisch de 8 tabellen dfgsc_*, de menutabbladen en de bijbehorende hooks.
4. Klik op Configureren op de modulefiche.

Vereisten

• PrestaShop 8.0.0 tot 9.99.99
• PHP 7.4, 8.0, 8.1, 8.2 of 8.3
• MySQL 5.6+ of MariaDB 10.3+
• PHP-extensie curl ingeschakeld (standaard bij alle hosters)
• Een Google-account dat al eigenaars- of gedelegeerde eigenaarstoegang heeft tot de Search Console-property van uw winkel

Google OAuth-configuratie

De module gebruikt OAuth 2.0 om namens de winkeleigenaar toegang te krijgen tot Search Console. Deze stap gebeurt één keer en duurt ongeveer 5 minuten. Er is geen serviceaccount vereist: de authenticatie gebruikt direct het Google-account dat al toegang heeft tot uw Search Console-property.

Stap 1 — Een Google Cloud-project aanmaken

1. Ga naar console.cloud.google.com met het Google-account dat de Search Console-toegang bezit.
2. Klik bovenaan op de projectkiezer en dan op Nieuw project.
3. Noem het bijvoorbeeld prestashop-gsc en maak het aan.
4. Selecteer dit nieuwe project zodra het is aangemaakt.

Stap 2 — De Search Console API activeren

1. Menu → API’s & Services → Bibliotheek.
2. Zoek Google Search Console API.
3. Klik erop en dan op Activeren.

Stap 3 — Het toestemmingsscherm configureren

1. Menu → API’s & Services → OAuth consent screen.
2. Kies External als uw Google-account geen lid is van een Google Workspace-organisatie, anders Internal.
3. Vul de applicatienaam in (bijvoorbeeld GSC Connect), uw supportadres en uw winkeldomein.
4. Voeg op het scherm Scopes de scope https://www.googleapis.com/auth/webmasters toe (lezen/schrijven Search Console).
5. Voeg op het scherm Test users uw Google-adres toe. Zolang het scherm in testmodus blijft, volstaat dat voor privégebruik: het is niet nodig de applicatie ter verificatie aan Google voor te leggen.

Stap 4 — De OAuth-identificatiegegevens aanmaken

1. Menu → API’s & Services → Credentials.
2. Create Credentials → OAuth client ID.
3. Applicatietype: Web application.
4. Naam: GSC Connect (vrij te kiezen).
5. Voeg in Geautoriseerde JavaScript-origins het domein van uw winkel toe met het HTTPS-protocol: https://uw-winkel.nl.
6. Plak in Geautoriseerde redirect-URI de exacte URL die in de configuratie van de PrestaShop-module wordt getoond (kader OAuth-redirect-URL).
7. Klik op Create. Google toont een Client ID en een Client Secret.

Stap 5 — De identificatiegegevens invullen in PrestaShop

1. Back-office → module → Configureren.
2. Plak de Client ID en de Client Secret.
3. Sla het formulier op. Een knop Verbinden met Google verschijnt.
4. Klik erop. U wordt naar de Google-toestemmingspagina doorgestuurd.
5. Bevestig de permissies, u wordt teruggeleid naar de PrestaShop BO.
6. De lijst met uw Search Console-properties wordt automatisch opgehaald: de module selecteert standaard die welke overeenkomt met het domein van uw winkel.

Eerste start

Start zodra de OAuth-verbinding tot stand is gebracht de eerste synchronisatie om uw gegevens op te halen:

1. Tabblad Dashboard. De standaardproperty is al geselecteerd.
2. Klik op Nu synchroniseren. De module haalt de laatste 28 dagen aan gegevens op (klikken, vertoningen, CTR, positie) op pagina- en zoekopdrachtniveau. Reken op 30 seconden tot 2 minuten afhankelijk van de omvang van uw catalogus.
3. Tabblad Sitemaps. De kandidaten worden automatisch gedetecteerd (/sitemap.xml in de root + patroon *_sitemap.xml gegenereerd door de PrestaShop-module gsitemap). Klik op Indienen naast elke relevante sitemap.
4. Tabblad Inspectie. Klik op Alle actieve producten in de wachtrij zetten. De wachtrij vult zich onmiddellijk. De werkelijke verwerking gebeurt via de cron met inachtneming van het Google-quotum van 2000 inspecties per dag.

Dashboard

Het dashboard bundelt 8 KPI’s over 28 dagen:

• Klikken — totaal aantal organische klikken in het venster
• Vertoningen — totaal aantal weergaven in de SERP
• Gemiddelde CTR — percentage klikken ten opzichte van de vertoningen
• Gemiddelde positie — gewogen gemiddelde positie over alle zoekopdrachten
• Ongelezen meldingen — aantal openstaande te behandelen meldingen
• Niet-geïndexeerde pagina’s — aantal geïnspecteerde pagina’s waarvan het Google-verdict FAIL of NEUTRAL is
• Quotum van vandaag — verbruikte Inspection API-aanroepen van het dagquotum
• Laatste synchronisatie — datum en tijd van de laatste sync-cronrun

Onder de KPI’s toont een evolutiegrafiek over 28 dagen de klikken (volle lijn) en de vertoningen (stippellijn op secundaire as). Chart.js is lokaal gebundeld, er wordt geen enkele CDN-afhankelijkheid geladen.

Rechts rangschikken de Top 10 producten en de Top 10 categorieën uw pagina’s op klikken met hun gemiddelde positie en hun CTR. De resolutie URL → entiteit gebruikt de native PrestaShop-routing: patroon id-slug voor de producten, link_rewrite voor de categorieën, cms_lang voor de CMS-pagina’s.

Klik- en positierapporten

Het tabblad Rapporten biedt drie detailweergaven: Producten, Categorieën, Zoekopdrachten. Elke weergave accepteert een configureerbare lookback: 7 / 14 / 28 / 90 dagen.

Voor elke regel krijgt u de klikken, de vertoningen, de CTR en de gemiddelde positie. Klik op elke kolomkop om te sorteren (client-side sortering, direct). De CSV-export produceert een UTF-8-bestand met BOM en puntkomma als scheidingsteken (native Excel-compatibel), tot 5000 regels per export.

Venstervergelijking

Voor elk vermeld product of elke categorie toont het rapport ook de variatie ten opzichte van het vorige venster van dezelfde duur. Een significante positiedaling verschijnt in het rood, een verbetering in het groen.

Sitemaps

Het tabblad Sitemaps detecteert automatisch de kandidaten op uw winkel:

• https://uw-winkel.nl/sitemap.xml — rootsitemap
• https://uw-winkel.nl/sitemap_index.xml — sitemap-index
• Patroon *_sitemap.xml in de root — gegenereerd door de PrestaShop-module gsitemap, één bestand per winkel en per taal

Dien in met één klik. De module volgt daarna voor u:

• Het aantal ingediende URL’s (opgegeven door uw sitemap)
• Het aantal daadwerkelijk geïndexeerde URL’s (gerapporteerd door Google)
• Het aantal door Google gedetecteerde fouten
• De datum van de laatste download door Googlebot

Detecteert Google fouten op een sitemap, dan wordt automatisch een melding aangemaakt: ernst HIGH bij ≥ 10 fouten, anders MEDIUM.

URL-inspectie in bulk

De URL Inspection API van Google is beperkt tot 2000 aanroepen per dag per property. GSC Connect beheert deze limiet via een wachtrij met automatische retry.

Beschikbare acties

• Alle actieve producten in de wachtrij zetten — voegt alle producten toe met zichtbaarheid both, search of catalog
• Alle categorieën in de wachtrij zetten — voegt alle actieve categorieën toe (de root is uitgesloten)
• Gewijzigde pagina’s herinspecteren — voegt alleen de entiteiten toe die door de hooks actionProductUpdate en actionCategoryUpdate als verouderd zijn gemarkeerd
• De wachtrij nu verwerken — voor tests, zonder op de cron te wachten
• Een losse URL inspecteren — om een directe correctie op een specifieke pagina te valideren

Geregistreerde gegevens

Voor elke geïnspecteerde URL registreert de module:

• Het globale Google-verdict: PASS, PARTIAL, FAIL of NEUTRAL
• De dekkingsstatus (Indexed, Discovered, Crawled but not indexed, enzovoort)
• De robots.txt-status en de opgegeven indexeerbaarheid
• De gedetecteerde rich results (Product, Breadcrumb, Review, enzovoort)
• De AMP-status en de mobile-friendly conformiteit
• De verwijzende sitemap en de verwijzende URL’s
• De datum van de laatste crawl door Googlebot

Meldingen en dalingen

Drie families van meldingen worden automatisch door de module beheerd:

Positiedalingen

Detecteert een significante positiedaling op een al goed gerangschikte pagina. Standaard: daling van 5 plaatsen of meer op een pagina gepositioneerd op ≤ 50. Drempel aanpasbaar in de configuratie (DFGSC_DROP_POS).

Klikdalingen

Detecteert een significante daling van het aantal klikken op een pagina die een minimumvolume genereerde. Standaard: daling van 30% met een minimum van 5 klikken in het vorige venster. Drempels aanpasbaar in de configuratie (DFGSC_DROP_CLICKS, DFGSC_DROP_MIN_CLICKS).

De-indexeringen

Automatisch aangemaakt wanneer een geïnspecteerde URL terugkomt met een verdict FAIL of NEUTRAL, of een dekkingsstatus DEINDEXED / INDEXING_NOT_ALLOWED.

Vergelijkingsmechanisme

De dalingsvergelijking gebeurt op een glijdend venster van 7 dagen tegen de 7 voorgaande dagen, met een offset van 2 dagen om de Search Console-latentie te respecteren. De module vergelijkt D-9..D-2 met D-16..D-9.

24u-ontdubbeling

Eenzelfde melding (zelfde pagina, zelfde type) wordt maar één keer per 24 u geactiveerd om ruis te vermijden, ook als de cron elk uur draait.

E-mailnotificaties

De meldingen kunnen per e-mail worden verstuurd als een HTML-digest gegroepeerd op ernst, in het Frans of Engels. Schakel ze in via de configuratie en vul het bestemmingsadres in.

Cron en planning

Alle achtergrondtaken lopen via één enkel, met een token beveiligd endpoint, zichtbaar op de configuratiepagina:

https://uw-winkel.nl/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXXXXXXXX

Plan het elke 1 tot 6 uur vanuit het cronpaneel van uw hoster (cPanel, Plesk, o2switch, OVH). Crontab-voorbeeld:

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

Uitgevoerde taken

Standaard voert het endpoint alle taken uit. U kunt er een deel van filteren met de parameter &tasks=:

Taak	Actie
sync	Ophalen van de nieuwe Search Analytics-gegevens (configureerbare lookback)
inspect	Verwerking van de URL-inspectiewachtrij met inachtneming van het quotum
sitemaps	Verversen van de status van de ingediende sitemaps
drops	Detectie van de positie- en klikdalingen
notify	Versturen van de meldingendigest per e-mail
prune	Opschoning van de afgeronde wachtrij-items en de oude quotumtellers

Voorbeeld om alleen de metrieken te synchroniseren zonder de inspectie aan te raken:

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

Referentieconfiguratie

Alle opties staan op de pagina Configureren van de module:

Optie	Sleutel	Standaard
Google Client ID	DFGSC_CLIENT_ID	(in te vullen)
Google Client Secret	DFGSC_CLIENT_SECRET	(in te vullen)
Synchronisatie-lookback (dagen)	DFGSC_LOOKBACK_DAYS	28
Dagquotum URL-inspectie	DFGSC_DAILY_QUOTA	2000
Drempel positiedaling	DFGSC_DROP_POS	5
Drempel klikdaling (%)	DFGSC_DROP_CLICKS	30
Minimumklikken voor dalingsdetectie	DFGSC_DROP_MIN_CLICKS	5
E-mailnotificaties ingeschakeld	DFGSC_ALERT_ENABLED	ja
Bestemmingsadres meldingen	DFGSC_ALERT_EMAIL	admin-e-mail
Crontoken	DFGSC_CRON_TOKEN	auto-gegenereerd

Google API-quota en -limieten

De Search Console API is gratis, maar onderworpen aan Google-quota:

• URL Inspection: 2000 aanroepen per dag per property, 600 per minuut (harde Google-limiet, niet onderhandelbaar)
• Search Analytics: 25000 regels per aanroep, ~1200 aanroepen per minuut, 30000 per dag (soft cap)
• Sitemaps: 5000 aanroepen per dag

De module registreert alle aanroepen per endpoint en per dag in de tabel dfgsc_quota. De inspectiewachtrij stopt netjes wanneer het geconfigureerde quotum is bereikt, met een melding van ernst MEDIUM. De tellers worden na 30 dagen automatisch opgeschoond door de taak prune.

Architectuur en gegevens

De module volgt een klassieke PSR-4-architectuur onder de namespace DataFireflyGscConnect, met een eigen autoloader geleverd in vendor/autoload.php. Geen Composer-afhankelijkheid. Geen externe afhankelijkheid: de Google API-aanroepen gebeuren in native cURL met SSL-verificatie.

Lagen

• Api — HTTP-clients (GoogleOAuth, SearchConsoleClient)
• Model — repositories voor databasetoegang (Token, Site, Metric, Inspection, Sitemap, Alert, Queue, Quota)
• Services — orkestratie (MetricsSync, Inspection, Sitemap, Alert)

Aangemaakte tabellen

Tabel	Rol
dfgsc_token	OAuth-refreshtoken + verval per winkel
dfgsc_site	Bekende Search Console-properties (per winkel, met de standaard)
dfgsc_metric	Search Analytics-regels (per dag, per pagina, optioneel per zoekopdracht)
dfgsc_inspection	Lokale cache van de URL-inspecties met hun volledige verdict
dfgsc_sitemap	Status van de ingediende sitemaps (URL, ingediend, geïndexeerd, fouten, laatste download)
dfgsc_alert	Gegenereerde meldingen (type, ernst, pagina, delta, status)
dfgsc_queue	Inspectiewachtrij met statussen pending/processing/done/failed
dfgsc_quota	Tellers van API-aanroepen per endpoint en per dag

Gebruikte hooks

• actionAdminControllerSetMedia — laden van de BO-assets
• displayBackOfficeHeader — gereserveerd voor toekomstige notificaties
• actionProductUpdate / actionCategoryUpdate — invalidatie van de inspectiecache
• actionObjectProductDeleteAfter / actionObjectCategoryDeleteAfter — opschoning van verweesde inspecties

Beveiliging

• Cookie-gebaseerd CSRF-statetoken op de OAuth-flow
• Validatie hash_equals op het crontoken
• Refreshtoken opgeslagen in de database, nooit gelogd
• Accesstoken nooit gepersisteerd: op verzoek geregenereerd vanuit het refreshtoken en in het geheugen gehouden voor de duur van het verzoek
• Anti-listing index.php-bestanden in alle submappen
• Systematische escaping via Tools::safeOutput op alle template-uitvoer

Probleemoplossing

De knop “Verbinden met Google” verschijnt niet

Controleer of Client ID en Client Secret daadwerkelijk zijn opgeslagen. Sla het formulier op en herlaad de configuratiepagina.

Het Google-scherm toont redirect_uri_mismatch

De redirect-URI in Google Cloud moet strikt identiek zijn aan die in de moduleconfiguratie: zelfde protocol (https), zelfde subdomein (www of niet), zelfde pad, zonder slash aan het einde. Kopieer en plak zonder wijziging.

De synchronisatie brengt geen gegevens terug

Controleer drie punten: (1) de geselecteerde property is daadwerkelijk uw winkel; (2) ze heeft minstens 72 u geschiedenis in Search Console (Google publiceert met ~48 u latentie); (3) het verbonden Google-account heeft daadwerkelijk eigenaars- of gedelegeerde eigenaarstoegang tot deze property.

De inspecties worden niet uitgevoerd

Controleer of de cron daadwerkelijk is gepland en draait. Controleer vervolgens het dagquotum: hebt u de 2000 Google-aanroepen verbruikt, dan staat de wachtrij op pauze tot de volgende dag. U kunt handmatig forceren via de knop De wachtrij nu verwerken.

De e-mailmeldingen komen niet aan

Controleer of het ingevulde adres geldig is, of de SMTP-configuratie van PrestaShop werkt (test bijvoorbeeld met een welkomstmail), en of de notificaties in de moduleconfiguratie zijn ingeschakeld.

401- of 403-fout op de Search Console-aanroepen

Het refreshtoken is waarschijnlijk aan Google-zijde ingetrokken (wachtwoordwijziging, accountbeveiliging, of verlopen toestemming). Verbreek de verbinding en verbind de winkel opnieuw vanuit de configuratie.

Fout Quota Exhausted (429)

Het Google-quotum van de property is bereikt. Dat is door Google beperkt tot 2000 inspecties per dag, onafhankelijk van het aantal modules of tools dat de property bevraagt. De wachtrij hervat automatisch de volgende dag.

Changelog

Zie het bestand CHANGELOG.md in de ZIP van de module voor de volledige lijst van wijzigingen per versie.

---

Neem voor elke hier niet behandelde vraag contact op met de DataFirefly-support via support@datafirefly.com.