# 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…
- Page:
- Langue: fr
- Mis à jour le: 2026-06-29
- Autres langues: [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), [nl](https://www.datafirefly.com/nl/documentation/dfgscconnect/index.md)
- Index:
**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.
**Multi-boutique natif.** Le module est multishop. Chaque boutique stocke son propre jeton OAuth, sa propre propriété Search Console et son propre historique de métriques. Vous pouvez connecter une boutique sans toucher aux autres.
### 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](https://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**.
**L'URL de redirection doit être strictement identique.** Y compris le protocole (`https`), les sous-domaines (`www` ou non) et l'absence de slash final. Une seule différence et Google bloque la connexion avec `redirect_uri_mismatch`.
### É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.
**Latence Search Console.** Google diffuse les données de Search Analytics avec environ 48 h de retard. Si vous venez tout juste de vous connecter, certaines métriques de la veille ou de l'avant-veille ne seront pas encore disponibles. C'est normal. Le module en tient compte automatiquement dans les calculs de drops (fenêtre glissante avec offset de 2 jours).
## 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
**Désindexation détectée → alerte automatique.** Si le verdict est FAIL ou NEUTRAL, ou si l'état de couverture est DEINDEXED ou INDEXING_NOT_ALLOWED, une alerte HIGH est levée automatiquement avec la raison renvoyée par Google.
## 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"
```
**Hébergement mutualisé compatible.** Aucune dépendance Redis, BullMQ, worker persistant ou PHP-FPM dédié. L'endpoint cron est un simple URL HTTPS protégé par token. Fonctionne nativement sur o2switch, OVH mutualisé et tout hébergement Linux standard.
## 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._