GSC Connect — Documentation

GSC Connect ramène toute la puissance de Google Search Console directement dans le back-office PrestaShop : connexion OAuth en un clic, soumission de sitemaps, inspection d’URL en masse, rapports clics et positions par produit et catégorie, alertes automatiques de chute et de désindexation. Ce guide couvre l’installation, la configuration OAuth Google, la première synchronisation, la planification cron, la lecture des rapports, la résolution des cas d’erreur courants et l’architecture interne.

Installation

Le module se déploie comme tout module PrestaShop standard : aucune dépendance Composer, aucun worker persistant, aucun service externe à part Google.

1. Téléchargez dfgscconnect.zip depuis votre compte DataFirefly (lien de téléchargement reçu après commande).
2. Back-office → Modules → Gestionnaire de modules → Uploader un module.
3. Glissez-déposez le ZIP. PrestaShop installe automatiquement les 8 tables dfgsc_*, les onglets de menu et les hooks associés.
4. Cliquez sur Configurer sur la fiche du module.

Prérequis

• PrestaShop 8.0.0 à 9.99.99
• PHP 7.4, 8.0, 8.1, 8.2 ou 8.3
• MySQL 5.6+ ou MariaDB 10.3+
• Extension PHP curl activée (par défaut sur tous les hébergeurs)
• Un compte Google qui possède déjà l’accès propriétaire ou propriétaire délégué à la propriété Search Console de votre boutique

Configuration OAuth Google

Le module utilise OAuth 2.0 pour accéder à Search Console au nom du propriétaire de la boutique. Cette étape se fait une seule fois et prend environ 5 minutes. Aucun compte de service n’est requis : l’authentification utilise directement le compte Google qui a déjà l’accès à votre propriété Search Console.

Étape 1 — Créer un projet Google Cloud

1. Rendez-vous sur console.cloud.google.com avec le compte Google qui possède l’accès Search Console.
2. Cliquez sur le sélecteur de projet en haut, puis sur Nouveau projet.
3. Nommez-le par exemple prestashop-gsc et créez-le.
4. Sélectionnez ce nouveau projet une fois créé.

Étape 2 — Activer l’API Search Console

1. Menu → API & Services → Bibliothèque.
2. Recherchez Google Search Console API.
3. Cliquez dessus puis sur Activer.

Étape 3 — Configurer l’écran de consentement

1. Menu → API & Services → OAuth consent screen.
2. Choisissez External si votre compte Google n’est pas membre d’une organisation Google Workspace, sinon Internal.
3. Renseignez le nom de l’application (par exemple GSC Connect), votre adresse de support et votre domaine de boutique.
4. Sur l’écran Scopes, ajoutez le scope https://www.googleapis.com/auth/webmasters (lecture/écriture Search Console).
5. Sur l’écran Test users, ajoutez votre adresse Google. Tant que l’écran reste en mode test, c’est suffisant pour un usage privé : il n’est pas nécessaire de soumettre l’application à vérification par Google.

Étape 4 — Créer les identifiants OAuth

1. Menu → API & Services → Credentials.
2. Create Credentials → OAuth client ID.
3. Type d’application : Web application.
4. Nom : GSC Connect (libre).
5. Dans Origines JavaScript autorisées, ajoutez le domaine de votre boutique avec le protocole HTTPS : https://votre-boutique.fr.
6. Dans URI de redirection autorisé, collez l’URL exacte affichée dans la configuration du module PrestaShop (encadré URL de redirection OAuth).
7. Cliquez sur Create. Google affiche un Client ID et un Client Secret.

Étape 5 — Renseigner les identifiants dans PrestaShop

1. Back-office → module → Configurer.
2. Collez le Client ID et le Client Secret.
3. Enregistrez le formulaire. Un bouton Se connecter avec Google apparaît.
4. Cliquez dessus. Vous êtes redirigé sur la page de consentement Google.
5. Validez les permissions, vous êtes redirigé dans le BO PrestaShop.
6. La liste de vos propriétés Search Console est récupérée automatiquement : le module sélectionne par défaut celle qui correspond au domaine de votre boutique.

Premier lancement

Une fois la connexion OAuth établie, lancez la première synchronisation pour rapatrier vos données :

1. Onglet Tableau de bord. La propriété par défaut est déjà sélectionnée.
2. Cliquez sur Synchroniser maintenant. Le module récupère les 28 derniers jours de données (clics, impressions, CTR, position) au niveau page et requête. Comptez 30 secondes à 2 minutes selon le volume de votre catalogue.
3. Onglet Sitemaps. Les candidats sont détectés automatiquement (/sitemap.xml racine + pattern *_sitemap.xml généré par le module gsitemap de PrestaShop). Cliquez sur Soumettre à côté de chaque sitemap pertinent.
4. Onglet Inspection. Cliquez sur Enfourner tous les produits actifs. La file se remplit instantanément. Le traitement réel se fait via le cron en respectant le quota Google de 2000 inspections par jour.

Tableau de bord

Le tableau de bord regroupe 8 KPIs sur 28 jours :

• Clics — total des clics organiques sur la fenêtre
• Impressions — total des affichages dans la SERP
• CTR moyen — pourcentage de clics par rapport aux impressions
• Position moyenne — position moyenne pondérée sur l’ensemble des requêtes
• Alertes non lues — nombre d’alertes ouvertes à traiter
• Pages non indexées — nombre de pages inspectées dont le verdict Google est FAIL ou NEUTRAL
• Quota du jour — appels API Inspection consommés sur le quota journalier
• Dernière synchronisation — date et heure de la dernière passe cron sync

Sous les KPIs, un graphique d’évolution sur 28 jours affiche les clics (ligne pleine) et les impressions (ligne pointillée sur axe secondaire). Chart.js est bundlé en local, aucune dépendance CDN n’est chargée.

Sur la droite, le Top 10 produits et le Top 10 catégories classent vos pages par clics avec leur position moyenne et leur CTR. La résolution URL → entité utilise le routing natif PrestaShop : pattern id-slug pour les produits, link_rewrite pour les catégories, cms_lang pour les pages CMS.

Rapports clics et positions

L’onglet Rapports propose trois vues détaillées : Produits, Catégories, Requêtes. Chaque vue accepte un lookback configurable : 7 / 14 / 28 / 90 jours.

Pour chaque ligne, vous obtenez les clics, les impressions, le CTR et la position moyenne. Cliquez sur n’importe quel en-tête de colonne pour trier (tri client, instantané). L’export CSV produit un fichier UTF-8 avec BOM et séparateur point-virgule (compatible Excel natif), jusqu’à 5000 lignes par export.

Comparaison de fenêtres

Pour chaque produit ou catégorie listé, le rapport affiche également la variation par rapport à la fenêtre précédente de même durée. Une chute de position significative apparaît en rouge, une amélioration en vert.

Sitemaps

L’onglet Sitemaps détecte automatiquement les candidats sur votre boutique :

• https://votre-boutique.fr/sitemap.xml — sitemap racine
• https://votre-boutique.fr/sitemap_index.xml — index de sitemaps
• Pattern *_sitemap.xml à la racine — généré par le module gsitemap de PrestaShop, un fichier par boutique et par langue

Soumettez en un clic. Le module suit ensuite pour vous :

• Le nombre d’URL soumises (déclaré par votre sitemap)
• Le nombre d’URL réellement indexées (rapporté par Google)
• Le nombre d’erreurs détectées par Google
• La date du dernier téléchargement par Googlebot

Si Google détecte des erreurs sur un sitemap, une alerte automatique est levée : sévérité HIGH si ≥ 10 erreurs, sinon MEDIUM.

Inspection d’URL en masse

L’API URL Inspection de Google est limitée à 2000 appels par jour par propriété. GSC Connect gère cette limite via une file d’attente avec retry automatique.

Actions disponibles

• Enfourner tous les produits actifs — ajoute tous les produits avec visibilité both, search ou catalog
• Enfourner toutes les catégories — ajoute toutes les catégories actives (la racine est exclue)
• Re-inspecter les pages modifiées — ajoute uniquement les entités marquées comme périmées par les hooks actionProductUpdate et actionCategoryUpdate
• Traiter la file maintenant — pour les tests, sans attendre le cron
• Inspecter une URL ad-hoc — pour valider une correction immédiate sur une page précise

Données enregistrées

Pour chaque URL inspectée, le module enregistre :

• Le verdict global Google : PASS, PARTIAL, FAIL ou NEUTRAL
• L’état de couverture (Indexed, Discovered, Crawled but not indexed, etc.)
• Le statut robots.txt et l’indexabilité déclarée
• Les résultats enrichis détectés (Product, Breadcrumb, Review, etc.)
• Le statut AMP et la conformité mobile-friendly
• Le sitemap référent et les URL référentes
• La date de la dernière exploration par Googlebot

Alertes et chutes

Trois familles d’alertes sont gérées automatiquement par le module :

Chutes de position

Détecte une chute significative de position sur une page déjà bien classée. Par défaut : chute de 5 places ou plus sur une page positionnée à ≤ 50. Seuil ajustable dans la configuration (DFGSC_DROP_POS).

Chutes de clics

Détecte une chute significative du nombre de clics sur une page qui en générait un volume minimum. Par défaut : chute de 30 % avec un minimum de 5 clics sur la fenêtre précédente. Seuils ajustables dans la configuration (DFGSC_DROP_CLICKS, DFGSC_DROP_MIN_CLICKS).

Désindexations

Levée automatiquement quand une URL inspectée revient avec un verdict FAIL ou NEUTRAL, ou un état de couverture DEINDEXED / INDEXING_NOT_ALLOWED.

Mécanique de comparaison

La comparaison drops se fait sur une fenêtre glissante de 7 jours contre les 7 jours précédents, avec un offset de 2 jours pour respecter la latence de Search Console. Le module compare D-9..D-2 à D-16..D-9.

Déduplication 24h

Une même alerte (même page, même type) ne se déclenche qu’une fois par 24h pour éviter le bruit, même si le cron tourne toutes les heures.

Notifications e-mail

Les alertes peuvent être envoyées par e-mail sous forme de digest HTML groupé par sévérité, en français ou en anglais. Activez-les depuis la configuration et renseignez l’adresse destinataire.

Cron et planification

Toutes les tâches en arrière-plan passent par un endpoint unique protégé par token, visible dans la page de configuration :

https://votre-boutique.fr/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXXXXXXXX

Programmez-le toutes les 1 à 6 heures depuis le panneau cron de votre hébergeur (cPanel, Plesk, o2switch, OVH). Exemple crontab :

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

Tâches exécutées

Par défaut, l’endpoint exécute toutes les tâches. Vous pouvez en filtrer une partie avec le paramètre &tasks= :

Tâche	Action
sync	Récupération des nouvelles données Search Analytics (lookback configurable)
inspect	Traitement de la file d’inspection d’URL en respectant le quota
sitemaps	Rafraîchissement du statut des sitemaps soumis
drops	Détection des baisses de position et de clics
notify	Envoi du digest d’alertes par e-mail
prune	Purge des entrées de file terminées et des compteurs de quota anciens

Exemple pour ne synchroniser que les métriques sans toucher à l’inspection :

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

Configuration de référence

Toutes les options sont dans la page Configurer du module :

Option	Clé	Défaut
Client ID Google	DFGSC_CLIENT_ID	(à renseigner)
Client Secret Google	DFGSC_CLIENT_SECRET	(à renseigner)
Lookback synchronisation (jours)	DFGSC_LOOKBACK_DAYS	28
Quota journalier inspection URL	DFGSC_DAILY_QUOTA	2000
Seuil chute de position	DFGSC_DROP_POS	5
Seuil chute de clics (%)	DFGSC_DROP_CLICKS	30
Clics minimum pour détecter chute	DFGSC_DROP_MIN_CLICKS	5
Notifications e-mail activées	DFGSC_ALERT_ENABLED	oui
Adresse destinataire alertes	DFGSC_ALERT_EMAIL	e-mail admin
Token cron	DFGSC_CRON_TOKEN	auto-généré

Quotas et limites API Google

L’API Search Console est gratuite, mais soumise à des quotas Google :

• URL Inspection : 2000 appels par jour par propriété, 600 par minute (hard limit Google, non négociable)
• Search Analytics : 25000 lignes par appel, ~1200 appels par minute, 30000 par jour (soft cap)
• Sitemaps : 5000 appels par jour

Le module enregistre tous les appels par endpoint et par jour dans la table dfgsc_quota. La file d’inspection s’arrête proprement lorsque le quota configuré est atteint, en générant une alerte de sévérité MEDIUM. Les compteurs sont purgés automatiquement après 30 jours par la tâche prune.

Architecture et données

Le module suit une architecture PSR-4 classique sous le namespace DataFireflyGscConnect, avec un autoloader maison livré dans vendor/autoload.php. Aucune dépendance Composer. Aucune dépendance externe : les appels Google API se font en cURL natif avec vérification SSL.

Couches

• Api — clients HTTP (GoogleOAuth, SearchConsoleClient)
• Model — repositories d’accès à la base (Token, Site, Metric, Inspection, Sitemap, Alert, Queue, Quota)
• Services — orchestration (MetricsSync, Inspection, Sitemap, Alert)

Tables créées

Table	Rôle
dfgsc_token	Refresh token OAuth + expiration par boutique
dfgsc_site	Propriétés Search Console connues (par boutique, avec celle par défaut)
dfgsc_metric	Lignes Search Analytics (par jour, par page, optionnellement par requête)
dfgsc_inspection	Cache local des inspections d’URL avec leur verdict complet
dfgsc_sitemap	État des sitemaps soumis (URL, soumis, indexés, erreurs, dernier téléchargement)
dfgsc_alert	Alertes générées (type, sévérité, page, delta, statut)
dfgsc_queue	File d’inspection avec statuts pending/processing/done/failed
dfgsc_quota	Compteurs d’appels API par endpoint et par jour

Hooks utilisés

• actionAdminControllerSetMedia — chargement des assets BO
• displayBackOfficeHeader — réservé pour notifications futures
• actionProductUpdate / actionCategoryUpdate — invalidation du cache d’inspection
• actionObjectProductDeleteAfter / actionObjectCategoryDeleteAfter — purge des inspections orphelines

Sécurité

• CSRF state token cookie-based sur le flux OAuth
• Validation hash_equals sur le token cron
• Refresh token stocké en base, jamais loggé
• Access token jamais persisté : régénéré à la demande depuis le refresh token et tenu en mémoire le temps de la requête
• Fichiers index.php anti-listing dans tous les sous-répertoires
• Échappement systématique via Tools::safeOutput sur toutes les sorties templates

Dépannage

Le bouton « Se connecter avec Google » n’apparaît pas

Vérifiez que Client ID et Client Secret sont bien enregistrés. Sauvegardez le formulaire, puis rechargez la page de configuration.

L’écran Google affiche redirect_uri_mismatch

L’URI de redirection dans Google Cloud doit être strictement identique à celle affichée dans la configuration du module : même protocole (https), même sous-domaine (www ou non), même chemin, sans slash final. Copiez-collez sans modification.

La synchronisation ne ramène pas de données

Vérifiez trois points : (1) la propriété sélectionnée est bien votre boutique ; (2) elle a au moins 72 h d’historique dans Search Console (Google diffuse avec ~48 h de latence) ; (3) le compte Google connecté a bien l’accès propriétaire ou propriétaire délégué à cette propriété.

Les inspections ne se font pas

Vérifiez que le cron est bien programmé et qu’il s’exécute. Vérifiez ensuite le quota du jour : si vous avez consommé les 2000 appels Google, la file est en pause jusqu’au lendemain. Vous pouvez forcer manuellement via le bouton Traiter la file maintenant.

Les alertes par e-mail n’arrivent pas

Vérifiez que l’adresse renseignée est valide, que la configuration SMTP de PrestaShop fonctionne (testez avec un e-mail de bienvenue par exemple), et que les notifications sont activées dans la configuration du module.

Erreur 401 ou 403 sur les appels Search Console

Le refresh token a probablement été révoqué côté Google (changement de mot de passe, sécurité du compte, ou consentement expiré). Déconnectez et reconnectez la boutique depuis la configuration.

Erreur Quota Exhausted (429)

Le quota Google de la propriété est atteint. C’est limité à 2000 inspections par jour par Google, indépendamment du nombre de modules ou d’outils qui interrogent la propriété. La file reprend automatiquement le lendemain.

Changelog

Voir le fichier CHANGELOG.md inclus dans le ZIP du module pour la liste complète des évolutions par version.

---

Pour toute question non couverte ici, contactez le support DataFirefly à support@datafirefly.com.