Google Indexing API pour Magento 2 - installation et configuration

1. Informations importantes avant le déploiement

Le module intègre Magento 2 à Google Indexing API et permet d’ajouter des URL à une file d’attente centrale de soumissions. La file est traitée par le cron Magento, et chaque soumission est validée, dédupliquée, soumise à des limites et journalisée.

Conformément à la documentation Google, Indexing API est officiellement destinée avant tout aux pages avec des données structurées :

• JobPosting,
• BroadcastEvent intégré dans VideoObject.

L’utilisation de l’API pour des produits, catégories, pages CMS ou articles de blog ne garantit ni l’indexation ni la position dans les résultats de recherche. Le module doit être considéré comme un outil technique pour soumettre des URL, et non comme un substitut au sitemap XML, à des balises canonical correctes, au fichier robots, au hreflang, au maillage interne et à la qualité SEO globale.

Documents officiels Google :

• https://developers.google.com/search/apis/indexing-api/v3/quickstart
• https://developers.google.com/search/apis/indexing-api/v3/prereqs
• https://developers.google.com/search/apis/indexing-api/v3/using-api
• https://developers.google.com/search/apis/indexing-api/v3/quota-pricing

2. Prérequis

Avant l’installation, assurez-vous que l’environnement répond aux exigences suivantes :

• Magento 2.4.x,
• PHP 8.1 ou plus récent,
• Composer,
• cron Magento opérationnel,
• possibilité d’installer le package google/apiclient,
• accès administrateur à Magento,
• projet Google Cloud avec Indexing API activée,
• propriété Google Search Console vérifiée pour le domaine de la boutique,
• compte de service Google ajouté comme propriétaire dans Google Search Console.

Le module nécessite le package :

google/apiclient:^2.16

Le package est déclaré dans le composer.json du module, donc Composer devrait l’installer automatiquement.

3. Installation du module

3.1. Installation via Composer depuis un dépôt VCS

Si le module est installé depuis un dépôt Git privé ou public, ajoutez le dépôt au projet Magento :

composer config repositories.kowal.google.indexing.api vcs https://github.com/kowalco/google-indexing-api

Si le dépôt est privé, configurez le token GitHub :

composer config --global --auth github-oauth.github.com 

Installez le package :

composer require kowal/module-google-indexing-api

Activez le module :

bin/magento module:enable Kowal_GoogleIndexingApi

Exécutez la mise à jour du schéma de base de données :

bin/magento setup:upgrade

Videz le cache :

bin/magento cache:flush

En mode production, exécutez également :

bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush

3.2. Installation locale dans app/code

Si le module est installé sans Composer en tant que code local, placez-le dans le répertoire :

app/code/Kowal/GoogleIndexingApi

Ensuite, installez la dépendance Google API Client dans le projet Magento :

composer require google/apiclient:^2.16

Activez le module et exécutez les commandes Magento standard :

bin/magento module:enable Kowal_GoogleIndexingApibin/magento setup:upgradebin/magento cache:flush

Pour la production :

bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush

3.3. Vérification de l’installation

Vérifiez si le module est actif :

bin/magento module:status Kowal_GoogleIndexingApi

Après une installation correcte, les éléments suivants doivent être disponibles dans le panneau d’administration :

• Stores > Configuration > Kowal > Google Indexing API,
• menu d’administration Google Indexing API > Indexing Queue,
• Google Indexing API > Import URLs,
• Google Indexing API > API Logs,
• Google Indexing API > Setup Assistant.

Les tables suivantes doivent être créées dans la base de données :

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Préparation de Google Cloud et Search Console

4.1. Création d’un projet Google Cloud

1. Accédez à Google Cloud Console.
2. Créez un nouveau projet ou sélectionnez un projet existant utilisé pour la boutique.
3. Activez l’API :

Indexing API

Sans API activée, le module ne pourra pas envoyer correctement les soumissions.

4.2. Création d’un compte de service

1. Dans Google Cloud, accédez à IAM & Admin > Service Accounts.
2. Créez un nouveau compte de service.
3. Générez une clé au format JSON.
4. Téléchargez le fichier JSON et stockez-le en lieu sûr.

Le module exige que le JSON contienne au minimum les champs suivants :

• type,
• project_id,
• private_key,
• client_email.

Le champ type doit avoir la valeur :

service_account

4.3. Ajouter le compte de service comme propriétaire dans Search Console

1. Ouvrez Google Search Console.
2. Sélectionnez la propriété correspondant au domaine de la boutique.
3. Assurez-vous que la propriété est vérifiée.
4. Ajoutez l’adresse client_email du fichier JSON comme propriétaire de la propriété.

Exemple d’adresse de compte de service :

my-service-account@project-name.iam.gserviceaccount.com

Si le compte de service n’est pas propriétaire de la propriété Search Console, Google peut renvoyer des erreurs d’autorisation, par exemple l’absence de confirmation de propriété de l’URL.

5. Configuration du module dans Magento

La configuration se trouve dans :

Stores > Configuration > Kowal > Google Indexing API

La configuration prend en charge les portées Magento :

• Default Config,
• Website,
• Store View.

Ainsi, il est possible d’avoir des paramètres distincts pour différentes boutiques ou vues de boutique, si le projet l’exige.

6. Section General

Enable

Par défaut :

No

Active ou désactive le fonctionnement du module.

Lorsque le champ a la valeur No, le cron ne traite pas la file d’attente. Les adresses peuvent exister dans la base, mais le processeur de la file ne les enverra pas à Google.

Recommandation :

• pendant la première configuration, définissez No ou laissez Dry Run = Yes,
• après des tests concluants, définissez Yes.

Dry Run

Par défaut :

Yes

Mode de test. Lorsque Dry Run est activé, le module traite les enregistrements de la file, enregistre les statuts et les logs, mais n’envoie pas de soumission réelle à Google.

C’est le mode le plus sûr pour le premier lancement, les tests de configuration et la vérification que les URL arrivent dans la file comme prévu.

Recommandation :

• effectuez toujours les premiers tests avec Dry Run = Yes,
• désactivez Dry Run uniquement après avoir vérifié les credentials, les allowed hosts, la file et les logs.

7. Section Google Access Credentials

Credentials Source

Par défaut :

Encrypted configuration value

Détermine la source à partir de laquelle le module récupère le JSON du compte de service Google.

Options disponibles :

Recommandation :

• pour les déploiements simples, la valeur chiffrée dans la configuration peut être utilisée,
• pour les environnements avec contrôle d’accès aux fichiers, l’upload du fichier JSON peut être plus pratique.

Service Account JSON

Visible lorsque Credentials Source = Encrypted configuration value.

Dans ce champ, il faut coller le contenu complet du fichier JSON du compte de service Google.

Le module valide le JSON avant l’enregistrement. Sont vérifiés :

• la validité du format JSON,
• la présence des champs type, project_id, private_key, client_email,
• la valeur type = service_account.

La valeur est enregistrée comme configuration chiffrée Magento.

Service Account JSON File

Visible lorsque Credentials Source = Uploaded JSON file.

Permet de téléverser le fichier JSON du compte de service Google.

Le module :

• accepte uniquement les fichiers avec l’extension .json,
• valide le contenu du fichier,
• vérifie les champs requis type, project_id, private_key, client_email,
• enregistre le fichier hors du répertoire public, dans var/google-indexing,
• essaie de définir les permissions du fichier à 0600, si le pilote de fichiers le permet.

Le fichier est enregistré avec un nom dépendant de la portée de configuration, par exemple pour la portée globale :

var/google-indexing/service-account-default-0.json

Google Cloud Project ID

Champ texte pour l’identifiant du projet Google Cloud.

Dans l’implémentation actuelle du module, l’autorisation principale repose sur les données du JSON du compte de service. Le champ Google Cloud Project ID remplit une fonction informative et structurante pour la configuration, en particulier lorsque la boutique utilise plusieurs environnements ou plusieurs projets Google Cloud.

Recommandation :

• saisissez la valeur project_id du fichier JSON,
• utilisez des projets Google Cloud distincts pour les environnements de production et de test, si cette séparation est adoptée dans le projet.

8. Section Queue and Limits

Daily Publish Limit

Par défaut :

200

Définit le nombre maximal de soumissions publish que le module peut exécuter au cours d’une journée.

Le limiteur compte les requêtes de type :

• publish,
• publish_dry_run.

Si la limite est atteinte, le processeur de file n’extraira plus d’autres enregistrements à envoyer jusqu’à la prochaine fenêtre quotidienne.

Recommandation :

• laissez 200 si le projet utilise la limite d’onboarding par défaut de Google,
• augmentez cette valeur uniquement si le projet Google Cloud dispose d’une limite supérieure approuvée,
• la valeur 0 bloque l’envoi, car le nombre de slots disponibles sera 0.

Requests Per Minute Limit

Par défaut :

60

Définit le nombre maximal de requêtes publish par minute.

Le module compare cette valeur avec le nombre de requêtes enregistrées dans les logs au cours de la dernière minute. Si la limite par minute est atteinte, cron ne traitera pas d’autres enregistrements lors de cette exécution.

Recommandation :

• pour un déploiement standard, laissez la valeur par défaut,
• réduisez-la si vous souhaitez solliciter l’API de manière plus prudente,
• ne définissez pas 0, sauf si vous souhaitez suspendre temporairement l’envoi.

Cron Batch Size

Par défaut :

20

Définit le nombre maximal d’enregistrements de la file traités lors d’une seule exécution du cron.

Le nombre réel d’enregistrements traités est également limité par :

• Daily Publish Limit,
• Requests Per Minute Limit,
• le nombre d’enregistrements prêts à être envoyés,
• le statut et la date scheduled_at.

Recommandation :

• 20 est une valeur de départ sûre,
• pour les files importantes, il est possible d’augmenter cette valeur, mais uniquement en tenant compte des limites de Google.

Default Indexing Lag (minutes)

Par défaut :

15

Définit le délai par défaut entre l’ajout d’une URL à la file d’attente et le moment à partir duquel elle peut être envoyée.

Le délai aide à :

• limiter les doublons,
• éviter un envoi après chaque petite modification,
• laisser à l’administrateur le temps de corriger le contenu,
• mieux gérer la limite de l’API.

Dans l’implémentation actuelle, ce paramètre est utilisé lorsque la soumission ne possède pas son propre délai.

Manual Form Indexing Lag (minutes)

Par défaut :

15

Définit le délai pour les URL ajoutées via le formulaire :

Google Indexing API > Import URLs

Si l’administrateur colle une liste d’URL manuellement, chaque adresse valide sera planifiée avec ce délai.

Recommandation :

• définissez 0 si l’import manuel doit arriver immédiatement dans la file,
• laissez 15 si vous souhaitez conserver une marge pour la déduplication et le contrôle des soumissions.

Mass Action Indexing Lag (minutes)

Par défaut :

15

Définit le délai pour les URL ajoutées via :

• les actions de masse sur les produits,
• les actions de masse sur les pages CMS,
• les boutons de soumission à l’indexation sur les écrans d’édition de produit, catégorie et page CMS.

Recommandation :

• pour les opérations de masse, laissez la valeur 15 ou plus,
• pour les petites boutiques et le travail administratif manuel, une valeur plus faible peut être envisagée.

Max Attempts

Par défaut :

5

Définit le nombre maximal de tentatives d’envoi d’un enregistrement de file.

Si Google renvoie une erreur temporaire, le module définira le statut retry, tant que le nombre de tentatives est inférieur à Max Attempts. Une fois la limite dépassée, l’enregistrement recevra le statut failed_permanent.

Erreurs considérées comme temporaires :

• 408,
• 409,
• 412,
• 429,
• 500,
• 502,
• 503,
• 504.

Retry Delay (minutes)

Par défaut :

15

Délai de base avant la tentative d’envoi suivante après une erreur temporaire.

Cron utilise un délai progressif. Le multiplicateur dépend du nombre de tentatives et est plafonné à 24. Ainsi, les tentatives suivantes ne sont pas exécutées de manière trop agressive.

Exemple pour la valeur 15 :

Allowed Source Types

Par défaut :

manual,product,category,cms_page,amasty_blog_post

Liste des types de sources autorisés, séparés par des virgules.

Valeurs prises en charge :

Si le type de source ne figure pas dans la liste, le scheduler ignorera la soumission et la marquera comme skipped.

Recommandation :

• laissez les valeurs par défaut si la boutique utilise toutes les sources standard,
• supprimez les sources que vous ne souhaitez pas autoriser dans la file.

Allowed URL Hosts

Par défaut :

vide

Liste des hôtes d’URL autorisés, séparés par des virgules.

Exemple :

example.com,www.example.com

Si la liste est renseignée, le module n’acceptera que les adresses appartenant aux hôtes indiqués. Si l’URL possède un autre hôte, la validation renverra l’erreur :

host_not_allowed

Recommandation :

• en production, renseignez toujours cette liste,
• ajoutez tous les hôtes utilisés par la boutique, par exemple le domaine principal, la version www, les domaines de store view et les domaines linguistiques,
• n’ajoutez pas de domaines de test à la configuration de production.

Require HTTPS URLs

Par défaut :

Yes

Impose que les URL soumises utilisent le schéma https.

Si ce champ est activé, une adresse en http sera rejetée avec l’erreur :

https_required

Recommandation :

• pour les boutiques de production, laissez Yes,
• n’utilisez No que dans des environnements de test exceptionnels.

9. Section Auto-Indexing

Enable Auto-Indexing

Par défaut :

No

Ce champ est prévu pour les intégrations automatiques d’enregistrement ou de suppression d’entités ainsi que pour des providers d’URL supplémentaires.

Dans le périmètre actuel du module, des mécanismes manuels et administratifs sont disponibles pour ajouter des URL à la file, notamment l’import d’URL, les Mass Actions et les boutons sur les formulaires d’édition.

Recommandation :

• laissez No si l’auto-indexing n’a pas été mis en œuvre dans le projet,
• activez-le uniquement lorsque le projet inclut la prise en charge d’événements automatiques d’entités utilisant cette configuration.

10. Section Logs

API Log Retention Days

Par défaut :

90

Définit le nombre de jours de conservation des logs API.

Le cron de nettoyage des logs s’exécute chaque jour à :

03:15

Il supprime les entrées plus anciennes que le nombre de jours défini dans ce champ.

Recommandation :

• 90 jours est une valeur raisonnable pour le diagnostic,
• en cas de grand nombre de requêtes, la rétention peut être réduite,
• dans le cadre d’audits SEO, la rétention peut être augmentée, en tenant compte de la taille de la table des logs.

11. Assistant d’installation et de configuration

L’assistant se trouve dans :

Google Indexing API > Setup Assistant

Son objectif est de vérifier rapidement si la configuration côté Magento et Google est prête pour le premier test.

11.1. Section Current Status

L’assistant affiche l’état actuel des éléments les plus importants :

Si Credentials a le statut Missing or invalid, il faut revenir à la configuration et corriger le JSON ou le fichier credentials.

Si Allowed Hosts affiche Not configured, le module ne limite pas les hôtes. Techniquement, cela peut fonctionner, mais en production, il est recommandé de renseigner explicitement les hôtes de la boutique.

11.2. Section Setup Steps

L’assistant affiche une liste des étapes nécessaires avant la première requête réelle :

1. Créer ou sélectionner un projet Google Cloud.
2. Activer Indexing API et créer une clé JSON pour le compte de service.
3. Coller le JSON ou téléverser le fichier JSON dans la configuration Magento.
4. Ajouter l’adresse e-mail du compte de service comme propriétaire dans Google Search Console.
5. Lancer les tests, puis importer une URL avec Dry Run activé.

L’assistant contient des liens vers :

• Google Cloud pour Indexing API,
• la configuration du module dans Magento,
• Google Search Console.

11.3. Test Google Credentials

Bouton :

Test Google Credentials

vérifie si Magento peut utiliser les données du compte de service pour obtenir un token OAuth pour le scope :

https://www.googleapis.com/auth/indexing

Un résultat positif signifie que :

• le JSON est correct,
• la clé privée peut être utilisée,
• Google a émis un token OAuth.

Un résultat négatif peut signifier :

• un JSON incorrect,
• une private_key incorrecte ou endommagée,
• l’absence d’un champ requis dans le JSON,
• un problème de communication avec Google,
• l’utilisation d’une clé qui n’est pas une clé de compte de service.

Ce test ne confirme pas encore que le compte de service dispose d’un accès propriétaire au domaine dans Search Console. Pour cela, un test URL metadata ou une soumission réelle d’une URL de test est nécessaire.

11.4. Test URL Metadata

Le formulaire :

Test URL Metadata

permet de saisir une URL publique provenant d’un hôte autorisé et d’exécuter une requête metadata vers Google Indexing API.

Avant d’envoyer la requête, le module :

• normalise l’URL,
• vérifie si l’URL est absolue,
• vérifie le schéma http ou https,
• si Require HTTPS URLs est activé, exige https,
• vérifie Allowed URL Hosts, s’ils ont été configurés.

Résultats possibles :

Le test metadata ne crée pas de nouvelle soumission publish. Il sert au diagnostic de la connexion et du statut de l’URL.

12. Premier lancement étape par étape

Ordre recommandé pour le premier lancement :

1. Installez le module et exécutez setup:upgrade.
2. Dans Magento, accédez à Stores > Configuration > Kowal > Google Indexing API.
3. Définissez Enable = Yes.
4. Laissez Dry Run = Yes.
5. Sélectionnez la source des credentials.
6. Collez le JSON du compte de service ou téléversez le fichier JSON.
7. Renseignez Google Cloud Project ID avec la valeur project_id du JSON.
8. Renseignez Allowed URL Hosts, par exemple example.com,www.example.com.
9. Laissez les limites par défaut si Google n’a pas approuvé des limites supérieures.
10. Enregistrez la configuration et videz le cache.
11. Accédez à Google Indexing API > Setup Assistant.
12. Vérifiez que l’assistant affiche les credentials comme prêts.
13. Cliquez sur Test Google Credentials.
14. Ajoutez l’adresse e-mail du compte de service comme propriétaire dans Google Search Console, si cela n’a pas encore été fait.
15. Exécutez Test URL Metadata pour une URL publique d’un hôte autorisé.
16. Accédez à Google Indexing API > Import URLs.
17. Ajoutez une URL de test avec l’action URL_UPDATED.
18. Exécutez le cron Magento :

bin/magento cron:run

19. Vérifiez Google Indexing API > Indexing Queue.
20. Vérifiez Google Indexing API > API Logs.
21. Si tout fonctionne correctement, désactivez Dry Run.
22. Ajoutez à nouveau une URL de test et vérifiez la réponse réelle de Google.

13. Import d’URL depuis le panneau d’administration

L’import manuel se trouve dans :

Google Indexing API > Import URLs

Le formulaire contient les champs suivants :

Actions disponibles :

Après l’envoi du formulaire, le module affichera un résumé :

• ajoutées,
• mises à jour,
• dédupliquées,
• invalides,
• ignorées.

Les 10 premiers messages de validation sont affichés comme notice dans le panneau d’administration.

14. File d’attente d’indexation

La file d’attente se trouve dans :

Google Indexing API > Indexing Queue

Chaque enregistrement de la file contient notamment :

• URL,
• hash de l’URL,
• store ID,
• website ID,
• type de source,
• ID de l’entité source,
• origine de la requête,
• action URL_UPDATED ou URL_DELETED,
• statut,
• priorité,
• nombre de tentatives,
• nombre maximal de tentatives,
• date d’envoi planifiée,
• date de traitement,
• dernier code d’erreur,
• dernier motif d’erreur,
• dernier message d’erreur,
• réponse de Google,
• information created_by.

Statuts de la file

Actions sur les enregistrements de la file

Attention : Transmit Now exécute une requête réelle si Dry Run = No. Avec Dry Run = Yes, un log dry-run sera enregistré sans envoi réel à Google.

15. Cron

Le module ajoute deux tâches cron dans le groupe default.

Traitement de la file

kowal_google_indexing_process_queue

Planification :

*/5 * * * *

La tâche lance le processeur de file toutes les 5 minutes.

Le processeur :

1. Vérifie si le module est activé.
2. Libère les anciens verrous des enregistrements processing de plus de 30 minutes.
3. Déplace les enregistrements scheduled vers pending si scheduled_at <= now.
4. Vérifie les slots disponibles dans les limites quotidiennes et par minute.
5. Récupère les enregistrements pending et retry.
6. Les trie selon la priorité et la date d’envoi planifiée.
7. Envoie une requête à Google ou exécute un dry-run.
8. Enregistre la réponse, le statut et le log API.

Nettoyage des logs

kowal_google_indexing_cleanup_logs

Planification :

15 3 * * *

La tâche supprime les logs API plus anciens que le nombre de jours défini dans le champ :

API Log Retention Days

16. Logs API

Les logs sont disponibles dans :

Google Indexing API > API Logs

Le log comprend :

• ID de l’enregistrement de file,
• store ID,
• type de requête,
• URL de l’endpoint,
• payload,
• statut HTTP,
• body de la réponse,
• durée de la requête,
• date de création du log.

Types de requêtes :

17. Mass Actions et boutons d’administration

Le module ajoute des mécanismes de soumission d’URL depuis le panneau d’administration.

Produits

Une action de masse est disponible dans la grille des produits pour ajouter les URL des produits à la file d’attente.

Le module ignore les produits :

• désactivés,
• non visibles individuellement.

Les URL sont générées sur la base des URL rewrites pour les store view actifs.

Pages CMS

Une action de masse est disponible dans la grille des pages CMS pour ajouter les URL des pages à la file d’attente.

Le module ignore les pages inactives.

Si une page CMS est affectée à tous les store view, le module résout les URL pour tous les store view.

Produit, catégorie et page CMS - boutons sur le formulaire d’édition

Le module ajoute des boutons de soumission à l’indexation sur les écrans d’édition :

• du produit,
• de la catégorie,
• de la page CMS.

Le bouton résout les URL de l’entité pour le store view et les ajoute à la file comme URL_UPDATED.

18. Configuration initiale recommandée

Pour un premier déploiement en production :

19. Problèmes courants et diagnostic

Credentials test failed

Vérifiez :

• si le JSON est correct,
• si le JSON provient d’un compte de service,
• s’il contient private_key et client_email,
• si le champ type a la valeur service_account,
• si le fichier JSON n’a pas été endommagé lors du collage.

Google renvoie une erreur d’autorisation

Vérifiez :

• si le domaine est vérifié dans Search Console,
• si le client_email du compte de service est ajouté comme propriétaire,
• si l’URL testée appartient à la même propriété Search Console,
• si vous utilisez le bon projet Google Cloud et le bon JSON.

L’URL est rejetée avant l’envoi

Vérifiez le message de validation :

La file d’attente n’est pas traitée

Vérifiez :

• si Enable = Yes,
• si le cron Magento fonctionne,
• si les enregistrements ont le statut pending ou retry,
• si scheduled_at n’est pas dans le futur,
• si les limites quotidiennes ou par minute ne sont pas atteintes,
• si Daily Publish Limit et Requests Per Minute Limit ne sont pas définis à 0.

Les enregistrements passent en retry

Vérifiez :

• le statut HTTP dans l’enregistrement de file,
• le log API,
• la réponse de Google,
• s’il n’y a pas de limite 429,
• s’il n’y a pas d’erreurs temporaires 5xx,
• si Max Attempts et Retry Delay sont définis conformément aux attentes.

20. Intégration optionnelle avec Amasty Blog

L’intégration avec Amasty Blog est prévue comme module séparé :

Kowal_GoogleIndexingApiAmastyBlog

Package :

kowal/module-google-indexing-api-amasty-blog

Ce module n’est pas nécessaire au fonctionnement de l’intégration principale. Il ne doit être installé que dans les projets qui utilisent amasty/blog et qui ont besoin d’une action de masse pour les articles de blog.