GSC Connect — Dokumentation

GSC Connect bringt die volle Leistung der Google Search Console direkt in das PrestaShop-Backoffice: Ein-Klick-OAuth-Verbindung, Sitemap-Übermittlung, URL-Inspektion im Stapel, Klick- und Positionsberichte nach Produkt und Kategorie, automatische Drop- und Deindexierungsalarme. Diese Anleitung behandelt Installation, Google-OAuth-Einrichtung, erste Synchronisation, Cron-Planung, Berichtslektüre, häufige Fehlerbehebung und die interne Architektur.

Installation

Das Modul wird wie jedes Standard-PrestaShop-Modul installiert: keine Composer-Abhängigkeit, kein persistenter Worker, kein externer Dienst außer Google.

1. Laden Sie dfgscconnect.zip aus Ihrem DataFirefly-Konto herunter (Download-Link nach dem Kauf erhalten).
2. Backoffice → Module → Modulmanager → Ein Modul hochladen.
3. ZIP per Drag & Drop hineinziehen. PrestaShop installiert automatisch die 8 dfgsc_*-Tabellen, die Menü-Tabs und die zugehörigen Hooks.
4. Klicken Sie auf Konfigurieren auf der Modul-Karte.

Voraussetzungen

• PrestaShop 8.0.0 bis 9.99.99
• PHP 7.4, 8.0, 8.1, 8.2 oder 8.3
• MySQL 5.6+ oder MariaDB 10.3+
• PHP-curl-Erweiterung aktiviert (standardmäßig bei allen Hostern)
• Ein Google-Konto, das bereits Eigentümer- oder delegierten Eigentümerzugriff auf die Search-Console-Property Ihres Shops hat

Google-OAuth-Einrichtung

Das Modul verwendet OAuth 2.0, um im Namen des Shop-Eigentümers auf Search Console zuzugreifen. Diese Einrichtung erfolgt einmalig und dauert ca. 5 Minuten. Kein Servicekonto erforderlich: Die Authentifizierung verwendet direkt das Google-Konto, das bereits Zugriff auf Ihre Search-Console-Property hat.

Schritt 1 — Google-Cloud-Projekt erstellen

1. Gehen Sie zu console.cloud.google.com mit dem Google-Konto, das den Search-Console-Zugriff hat.
2. Klicken Sie oben auf den Projektselektor und dann auf Neues Projekt.
3. Benennen Sie es z. B. prestashop-gsc und erstellen Sie es.
4. Wählen Sie dieses neue Projekt nach der Erstellung aus.

Schritt 2 — Search Console API aktivieren

1. Menü → APIs & Dienste → Bibliothek.
2. Suchen Sie nach Google Search Console API.
3. Klicken Sie darauf und dann auf Aktivieren.

Schritt 3 — Zustimmungsbildschirm konfigurieren

1. Menü → APIs & Dienste → OAuth-Zustimmungsbildschirm.
2. Wählen Sie External, wenn Ihr Google-Konto nicht Teil einer Google-Workspace-Organisation ist, sonst Internal.
3. Tragen Sie den Anwendungsnamen ein (z. B. GSC Connect), Ihre Support-E-Mail und Ihre Shop-Domain.
4. Auf dem Scopes-Bildschirm fügen Sie den Scope https://www.googleapis.com/auth/webmasters hinzu (Search-Console Lesen/Schreiben).
5. Auf dem Testbenutzer-Bildschirm fügen Sie Ihre Google-Adresse hinzu. Solange der Bildschirm im Testmodus bleibt, ist das für die private Nutzung ausreichend: Die App muss nicht zur Google-Verifizierung eingereicht werden.

Schritt 4 — OAuth-Anmeldedaten erstellen

1. Menü → APIs & Dienste → Anmeldedaten.
2. Anmeldedaten erstellen → OAuth-Client-ID.
3. Anwendungstyp: Webanwendung.
4. Name: GSC Connect (frei).
5. Unter Autorisierte JavaScript-Quellen fügen Sie Ihre Shop-Domain mit HTTPS hinzu: https://ihr-shop.de.
6. Unter Autorisierte Weiterleitungs-URI fügen Sie die exakte URL ein, die in der PrestaShop-Modulkonfiguration angezeigt wird (Feld OAuth-Weiterleitungs-URL).
7. Klicken Sie auf Erstellen. Google zeigt eine Client ID und ein Client Secret.

Schritt 5 — Anmeldedaten in PrestaShop eintragen

1. Backoffice → Modul → Konfigurieren.
2. Fügen Sie Client ID und Client Secret ein.
3. Speichern Sie das Formular. Eine Schaltfläche Mit Google verbinden erscheint.
4. Klicken Sie darauf. Sie werden zur Google-Zustimmungsseite weitergeleitet.
5. Bestätigen Sie die Berechtigungen, Sie werden zurück ins PrestaShop-Backoffice geleitet.
6. Die Liste Ihrer Search-Console-Properties wird automatisch abgerufen: Das Modul wählt standardmäßig diejenige, die zu Ihrer Shop-Domain passt.

Erster Start

Sobald die OAuth-Verbindung steht, starten Sie die erste Synchronisation, um Ihre Daten zu importieren:

1. Dashboard-Tab. Die Standard-Property ist bereits ausgewählt.
2. Klicken Sie auf Jetzt synchronisieren. Das Modul ruft die letzten 28 Tage Daten ab (Klicks, Impressionen, CTR, Position) auf Seiten- und Suchanfragen-Ebene. Rechnen Sie mit 30 Sekunden bis 2 Minuten je nach Katalog-Umfang.
3. Sitemaps-Tab. Kandidaten werden automatisch erkannt (Root-/sitemap.xml + *_sitemap.xml-Muster vom PrestaShop-Modul gsitemap). Klicken Sie auf Übermitteln neben jedem relevanten Sitemap.
4. Inspektion-Tab. Klicken Sie auf Alle aktiven Produkte aufnehmen. Die Queue füllt sich sofort. Die eigentliche Verarbeitung erfolgt über den Cron unter Einhaltung der Google-Quote von 2000 Inspektionen pro Tag.

Dashboard

Das Dashboard fasst 8 KPIs über 28 Tage zusammen:

• Klicks — Gesamte organische Klicks im Fenster
• Impressionen — Gesamte SERP-Impressionen
• Durchschnittliche CTR — Klicks im Verhältnis zu Impressionen in Prozent
• Durchschnittsposition — Gewichtete Durchschnittsposition über alle Suchanfragen
• Ungelesene Alarme — Anzahl der offenen Alarme
• Nicht indexierte Seiten — Anzahl der inspizierten Seiten mit Google-Verdikt FAIL oder NEUTRAL
• Heutiges Kontingent — Verbrauchte URL-Inspection-API-Aufrufe gegen das Tageskontingent
• Letzte Synchronisation — Datum und Uhrzeit des letzten sync-Cron-Durchlaufs

Unter den KPIs zeigt ein 28-Tage-Trenddiagramm Klicks (durchgezogene Linie) und Impressionen (gestrichelte Linie auf der Sekundärachse). Chart.js ist lokal eingebunden, keine CDN-Abhängigkeit wird geladen.

Rechts ordnen die Top 10 Produkte und Top 10 Kategorien Ihre Seiten nach Klicks mit ihrer Durchschnittsposition und CTR. Die URL → Entitäts-Auflösung verwendet das native PrestaShop-Routing: id-slug-Muster für Produkte, link_rewrite für Kategorien, cms_lang für CMS-Seiten.

Klick- und Positionsberichte

Der Berichte-Tab bietet drei detaillierte Ansichten: Produkte, Kategorien, Suchanfragen. Jede Ansicht akzeptiert einen konfigurierbaren Lookback: 7 / 14 / 28 / 90 Tage.

Für jede Zeile erhalten Sie Klicks, Impressionen, CTR und Durchschnittsposition. Klicken Sie auf einen Spaltenkopf zum Sortieren (clientseitig, sofortig). Der CSV-Export erzeugt eine UTF-8-Datei mit BOM und Semikolon-Trennzeichen (nativ Excel-kompatibel), bis zu 5000 Zeilen pro Export.

Fenstervergleich

Für jedes gelistete Produkt oder jede Kategorie zeigt der Bericht auch die Abweichung zum vorherigen Fenster gleicher Dauer. Ein signifikanter Positionsverlust erscheint rot, eine Verbesserung grün.

Sitemaps

Der Sitemaps-Tab erkennt automatisch Kandidaten auf Ihrem Shop:

• https://ihr-shop.de/sitemap.xml — Root-Sitemap
• https://ihr-shop.de/sitemap_index.xml — Sitemap-Index
• *_sitemap.xml-Muster im Root — vom PrestaShop-Modul gsitemap generiert, eine Datei pro Shop und pro Sprache

Mit einem Klick übermitteln. Das Modul verfolgt dann für Sie:

• Die Anzahl der übermittelten URLs (von Ihrem Sitemap deklariert)
• Die Anzahl der tatsächlich indexierten URLs (von Google gemeldet)
• Die Anzahl der von Google erkannten Fehler
• Das Datum des letzten Googlebot-Downloads

Wenn Google Fehler auf einem Sitemap meldet, wird ein automatischer Alarm ausgelöst: HIGH-Schweregrad bei ≥ 10 Fehlern, sonst MEDIUM.

URL-Inspektion im Stapel

Die URL-Inspection-API von Google ist auf 2000 Aufrufe pro Tag pro Property begrenzt. GSC Connect verwaltet dieses Limit über eine Queue mit automatischem Retry.

Verfügbare Aktionen

• Alle aktiven Produkte aufnehmen — fügt alle Produkte mit Sichtbarkeit both, search oder catalog hinzu
• Alle Kategorien aufnehmen — fügt alle aktiven Kategorien hinzu (die Root wird ausgeschlossen)
• Geänderte Seiten neu inspizieren — fügt nur Entitäten hinzu, die durch die actionProductUpdate– und actionCategoryUpdate-Hooks als veraltet markiert sind
• Queue jetzt verarbeiten — für Tests, ohne auf den Cron zu warten
• Ad-hoc-URL inspizieren — um eine sofortige Korrektur auf einer bestimmten Seite zu validieren

Gespeicherte Daten

Für jede inspizierte URL speichert das Modul:

• Das globale Google-Verdikt: PASS, PARTIAL, FAIL oder NEUTRAL
• Den Abdeckungsstatus (Indexed, Discovered, Crawled but not indexed, etc.)
• Den robots.txt-Status und die erklärte Indexierbarkeit
• Die erkannten Rich Results (Product, Breadcrumb, Review, etc.)
• Den AMP-Status und die Mobile-Friendliness
• Den verweisenden Sitemap und die verweisenden URLs
• Das Datum des letzten Googlebot-Crawls

Alarme und Drops

Drei Alarm-Familien werden automatisch vom Modul verwaltet:

Positionsverluste

Erkennt einen signifikanten Positionsverlust auf einer bereits gut platzierten Seite. Standard: Verlust von 5 Positionen oder mehr auf einer Seite, die ≤ 50 platziert ist. Schwellenwert in den Einstellungen anpassbar (DFGSC_DROP_POS).

Klickeinbrüche

Erkennt einen signifikanten Klickrückgang auf einer Seite, die ein Mindestvolumen generierte. Standard: Rückgang von 30 % mit mindestens 5 Klicks im vorherigen Fenster. Schwellenwerte in den Einstellungen anpassbar (DFGSC_DROP_CLICKS, DFGSC_DROP_MIN_CLICKS).

Deindexierungen

Wird automatisch ausgelöst, wenn eine inspizierte URL ein FAIL- oder NEUTRAL-Verdikt oder einen DEINDEXED- / INDEXING_NOT_ALLOWED-Abdeckungsstatus zurückgibt.

Vergleichsmechanik

Der Drops-Vergleich läuft auf einem gleitenden Fenster von 7 Tagen gegen die vorherigen 7 Tage, mit einem 2-Tage-Versatz für die Search-Console-Latenz. Das Modul vergleicht D-9..D-2 mit D-16..D-9.

24-Stunden-Deduplizierung

Derselbe Alarm (gleiche Seite, gleicher Typ) wird nur einmal pro 24 Stunden ausgelöst, um Rauschen zu vermeiden, selbst wenn der Cron stündlich läuft.

E-Mail-Benachrichtigungen

Alarme können per E-Mail als HTML-Digest gruppiert nach Schweregrad gesendet werden, auf Französisch oder Englisch. Aktivieren Sie sie in den Einstellungen und setzen Sie die Empfängeradresse.

Cron und Planung

Alle Hintergrundaufgaben laufen über einen einzelnen Token-geschützten Endpunkt, sichtbar auf der Konfigurationsseite:

https://ihr-shop.de/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXXXXXXXX

Planen Sie ihn alle 1 bis 6 Stunden über das Cron-Panel Ihres Hosters (cPanel, Plesk, o2switch, OVH). Beispiel crontab:

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

Ausgeführte Aufgaben

Standardmäßig führt der Endpunkt jede Aufgabe aus. Sie können einige mit dem Parameter &tasks= filtern:

Aufgabe	Aktion
sync	Holt neue Search-Analytics-Daten (konfigurierbarer Lookback)
inspect	Verarbeitet die URL-Inspektions-Queue unter Einhaltung des Kontingents
sitemaps	Aktualisiert den Status übermittelter Sitemaps
drops	Erkennt Positions- und Klickeinbrüche
notify	Sendet E-Mail-Alarm-Digest
prune	Bereinigt abgeschlossene Queue-Einträge und alte Kontingentzähler

Beispiel, um nur Metriken zu synchronisieren, ohne die Inspektion zu berühren:

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

Konfigurationsreferenz

Alle Optionen sind auf der Konfigurieren-Seite des Moduls:

Option	Schlüssel	Standard
Google Client ID	DFGSC_CLIENT_ID	(auszufüllen)
Google Client Secret	DFGSC_CLIENT_SECRET	(auszufüllen)
Sync-Lookback (Tage)	DFGSC_LOOKBACK_DAYS	28
Tägliches URL-Inspection-Kontingent	DFGSC_DAILY_QUOTA	2000
Positionsverlust-Schwelle	DFGSC_DROP_POS	5
Klickeinbruchsschwelle (%)	DFGSC_DROP_CLICKS	30
Mindestklicks zur Erkennung von Einbrüchen	DFGSC_DROP_MIN_CLICKS	5
E-Mail-Benachrichtigungen aktiviert	DFGSC_ALERT_ENABLED	ja
Empfängeradresse für Alarme	DFGSC_ALERT_EMAIL	Admin-E-Mail
Cron-Token	DFGSC_CRON_TOKEN	automatisch generiert

Google-API-Kontingente und -Limits

Die Search-Console-API ist kostenlos, unterliegt jedoch Google-Kontingenten:

• URL Inspection: 2000 Aufrufe pro Tag pro Property, 600 pro Minute (Google hard limit, nicht verhandelbar)
• Search Analytics: 25000 Zeilen pro Aufruf, ~1200 Aufrufe pro Minute, 30000 pro Tag (soft cap)
• Sitemaps: 5000 Aufrufe pro Tag

Das Modul speichert alle Aufrufe pro Endpunkt und Tag in der dfgsc_quota-Tabelle. Die Inspektions-Queue stoppt sauber, wenn das konfigurierte Kontingent erreicht ist, und löst einen MEDIUM-Schweregrad-Alarm aus. Zähler werden automatisch nach 30 Tagen durch die prune-Aufgabe bereinigt.

Architektur und Daten

Das Modul folgt einer klassischen PSR-4-Architektur unter dem Namespace DataFirefly/GscConnect/, mit einem eigenen Autoloader in vendor/autoload.php. Keine Composer-Abhängigkeit. Keine externe Abhängigkeit: Google-API-Aufrufe erfolgen über natives cURL mit SSL-Verifizierung.

Schichten

• Api/ — HTTP-Clients (GoogleOAuth, SearchConsoleClient)
• Model/ — Datenbankzugriffs-Repositorys (Token, Site, Metric, Inspection, Sitemap, Alert, Queue, Quota)
• Services/ — Orchestrierung (MetricsSync, Inspection, Sitemap, Alert)

Erstellte Tabellen

Tabelle	Rolle
dfgsc_token	OAuth-Refresh-Token + Ablauf pro Shop
dfgsc_site	Bekannte Search-Console-Properties (pro Shop, mit der Standard-Property)
dfgsc_metric	Search-Analytics-Zeilen (pro Tag, pro Seite, optional pro Suchanfrage)
dfgsc_inspection	Lokaler Cache der URL-Inspektionen mit vollem Verdikt
dfgsc_sitemap	Status übermittelter Sitemaps (URL, übermittelt, indexiert, Fehler, letzter Download)
dfgsc_alert	Generierte Alarme (Typ, Schweregrad, Seite, Delta, Status)
dfgsc_queue	Inspektions-Queue mit Status pending/processing/done/failed
dfgsc_quota	API-Aufruf-Zähler pro Endpunkt und Tag

Verwendete Hooks

• actionAdminControllerSetMedia — Laden von Backoffice-Assets
• displayBackOfficeHeader — reserviert für zukünftige Benachrichtigungen
• actionProductUpdate / actionCategoryUpdate — Invalidierung des Inspektions-Caches
• actionObjectProductDeleteAfter / actionObjectCategoryDeleteAfter — Bereinigung verwaister Inspektionen

Sicherheit

• Cookie-basierter CSRF-State-Token im OAuth-Flow
• hash_equals-Validierung auf dem Cron-Token
• Refresh-Token in DB gespeichert, nie geloggt
• Access-Token nie persistent: bei Bedarf aus dem Refresh-Token neu generiert und nur für die Anfrage im Speicher gehalten
• Anti-Listing-index.php-Dateien in allen Unterverzeichnissen
• Systematisches Escaping via Tools::safeOutput auf allen Template-Ausgaben

Fehlerbehebung

Die Schaltfläche „Mit Google verbinden“ erscheint nicht

Prüfen Sie, ob Client ID und Client Secret tatsächlich gespeichert wurden. Speichern Sie das Formular, laden Sie dann die Konfigurationsseite neu.

Google-Bildschirm zeigt redirect_uri_mismatch

Die Weiterleitungs-URI in Google Cloud muss genau mit der in der Modulkonfiguration angezeigten übereinstimmen: gleiches Protokoll (https), gleiche Subdomain (www oder nicht), gleicher Pfad, kein abschließender Schrägstrich. Kopieren und einfügen ohne Änderung.

Sync liefert keine Daten

Prüfen Sie drei Punkte: (1) die ausgewählte Property ist tatsächlich Ihr Shop; (2) sie hat mindestens 72 Stunden Historie in Search Console (Google liefert mit ~48h Latenz); (3) das verbundene Google-Konto hat Eigentümer- oder delegierten Eigentümerzugriff auf diese Property.

Inspektionen laufen nicht

Prüfen Sie, ob der Cron geplant ist und läuft. Prüfen Sie dann das Tageskontingent: Wenn Sie die 2000 Google-Aufrufe verbraucht haben, ist die Queue bis zum nächsten Tag pausiert. Sie können manuell über die Schaltfläche Queue jetzt verarbeiten erzwingen.

E-Mail-Alarme kommen nicht an

Prüfen Sie, ob die Adresse gültig ist, ob die SMTP-Konfiguration von PrestaShop funktioniert (testen Sie mit einer Willkommens-E-Mail z. B.) und ob Benachrichtigungen in der Modulkonfiguration aktiviert sind.

401- oder 403-Fehler bei Search-Console-Aufrufen

Der Refresh-Token wurde wahrscheinlich auf Googles Seite widerrufen (Passwortänderung, Kontosicherheit oder abgelaufene Zustimmung). Trennen und verbinden Sie den Shop erneut von der Konfiguration aus.

Quota Exhausted (429)-Fehler

Das Google-Kontingent für die Property ist erreicht. Google begrenzt dies auf 2000 Inspektionen pro Tag, unabhängig davon, wie viele Module oder Tools die Property abfragen. Die Queue setzt am nächsten Tag automatisch fort.

Changelog

Siehe die im Modul-ZIP enthaltene Datei CHANGELOG.md für die vollständige Liste der Änderungen pro Version.

---

Für nicht abgedeckte Fragen kontaktieren Sie den DataFirefly-Support unter support@datafirefly.com.