# 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,…
- Pagina:
- Taal: nl
- Bijgewerkt op: 2026-09-16
- Andere talen: [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), [pl](https://www.datafirefly.com/pl/documentation/dfgscconnect/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfgscconnect/index.md)
- Index:
**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.
**Native multistore.** De module is multishop. Elke winkel slaat haar eigen OAuth-token, haar eigen Search Console-property en haar eigen metriekengeschiedenis op. U kunt één winkel verbinden zonder de andere aan te raken.
### 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](https://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**.
**De redirect-URL moet strikt identiek zijn.** Inclusief het protocol (`https`), de subdomeinen (`www` of niet) en de afwezigheid van een slash aan het einde. Eén enkel verschil en Google blokkeert de verbinding met `redirect_uri_mismatch`.
### 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.
**Search Console-latentie.** Google publiceert de Search Analytics-gegevens met ongeveer 48 u vertraging. Hebt u zich net verbonden, dan zijn sommige metrieken van gisteren of eergisteren nog niet beschikbaar. Dat is normaal. De module houdt daar automatisch rekening mee in de dalingsberekeningen (glijdend venster met een offset van 2 dagen).
## 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
**De-indexering gedetecteerd → automatische melding.** Is het verdict FAIL of NEUTRAL, of is de dekkingsstatus DEINDEXED of INDEXING_NOT_ALLOWED, dan wordt automatisch een HIGH-melding aangemaakt met de door Google teruggegeven reden.
## 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"
```
**Compatibel met gedeelde hosting.** Geen Redis-, BullMQ-, persistente-worker- of dedicated PHP-FPM-afhankelijkheid. Het cron-endpoint is een simpele HTTPS-URL beveiligd met een token. Werkt native op o2switch, gedeelde OVH en elke standaard Linux-hosting.
## 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._