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 d’attente est traitée par cron Magento, et chaque soumission est validée, dédupliquée, soumise aux limites et journalisée.

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

• JobPosting,
• BroadcastEventintégré dansVideoObject.

L’utilisation de l’API pour les produits, catégories, pages CMS ou articles de blog ne garantit ni indexation ni position dans les résultats de recherche. Le module est un outil technique de soumission d’URL, pas un remplacement des sitemaps XML, canonical corrects, robots, hreflang, liens internes et de la qualité SEO générale.

Ressources officielles 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 :

• Magento 2.4.x,
• PHP 8.1 ou plus récent,
• Composer,
• cron Magento fonctionnel,
• possibilité d’installer le packagegoogle/apiclient,
• accès administrateur à Magento,
• projet Google Cloud avec Indexing API activée,
• propriété dans 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 lecomposer.jsondu module, Composer devrait donc l’installer automatiquement.

3. Installation du module

3.1. Installation via Composer

Ajoutez le dépôt Composer Kowal au projet Magento :

Les identifiants d’accès au dépôt Composer, c’est-à-dire l’adresse e-mail du client et le token de licence, vous seront envoyés par e-mail après l’achat. Ils sont également disponibles dans l’espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l’adresse e-mail de votre compte et TWOJ_TOKEN par le token reçu. Exécutez les commandes dans le répertoire racine de Magento.

composer config repositories.kowal composer https://repo.kowal.store

Configurez les identifiants d’accès au dépôt Composer Kowal :

composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"

Installez le package :

composer require kowal/module-google-indexing-api

Activez le module :

bin/magento module:enable Kowal_GoogleIndexingApi

Effectuez 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:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3.2. Installation locale dansapp/code

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

app/code/Kowal/GoogleIndexingApi

Installez ensuite 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_GoogleIndexingApi
bin/magento setup:upgrade
bin/magento cache:flush

Pour la production :

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3.3. Vérification de l’installation

Vérifiez que 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’administrationGoogle 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 du 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 du 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 conservez-le en lieu sûr.

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

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

Le champtype doit avoir la valeur :

service_account

4.3. Ajout du 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’adresseclient_emaildu 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 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 scopes Magento :

• Default Config,
• Website,
• Store View.

Cela permet d’avoir des paramètres séparés pour différentes boutiques ou vues 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 vautNo, cron ne traite pas la file d’attente. Les adresses peuvent exister dans la base, mais le processeur de file ne les enverra pas à Google.

Recommandation :

• lors de la première configuration, définissezNoou laissezDry Run = Yes,
• après des tests réussis, définissezYes.

Dry Run

Par défaut :

Yes

Mode de test. LorsqueDry Runest 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 d’attente comme prévu.

Recommandation :

• effectuez toujours les premiers tests avecDry Run = Yes,
• désactivezDry Rununiquement après avoir vérifié credentials, allowed hosts, la file d’attente et les logs.

7. Section Google Access Credentials

Credentials Source

Par défaut :

Encrypted configuration value

Définit d’où le module récupère le JSON du compte de service Google.

Options disponibles :

Recommandation :

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

Service Account JSON

Visible lorsqueCredentials Source = Encrypted configuration value.

Dans ce champ, collez le contenu complet du fichier JSON du compte de service Google.

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

• validité du format JSON,
• présence des champstype,project_id,private_key,client_email,
• valeurtype = service_account.

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

Service Account JSON File

Visible lorsqueCredentials Source = Uploaded JSON file.

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

Le module :

• n’accepte que les fichiers avec l’extension.json,
• valide le contenu du fichier,
• vérifie les champs requistype,project_id,private_key,client_email,
• enregistre le fichier hors du répertoire public, dansvar/google-indexing,
• tente de définir les permissions du fichier sur0600, si le pilote de fichiers le permet.

Le fichier est enregistré avec un nom dépendant du scope de configuration, par exemple pour le scope global :

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 champGoogle Cloud Project IDa une fonction informative et d’organisation de la configuration, en particulier lorsque la boutique utilise plusieurs environnements ou plusieurs projets Google Cloud.

Recommandation :

• saisissez la valeurproject_iddu fichier JSON,
• utilisez des projets Google Cloud séparés pour les environnements de production et de test si cette séparation est prévue 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 effectuer en une journée.

Le limiter compte les requests de type :

• publish,
• publish_dry_run.

Si la limite est utilisée, le processeur de file ne récupérera pas d’autres enregistrements à envoyer jusqu’à la prochaine fenêtre quotidienne.

Recommandation :

• laissez200si le projet utilise la limite d’onboarding Google par défaut,
• augmentez la valeur uniquement si le projet Google Cloud dispose d’une limite plus élevée approuvée,
• le réglage0bloque l’envoi, car le nombre de slots disponibles sera0.

Requests Per Minute Limit

Par défaut :

60

Définit le nombre maximal de requests publish par minute.

Le module compare cette valeur avec le nombre de requests enregistrés dans les logs de la dernière minute. Si la limite par minute est atteinte, cron ne traitera pas d’autres enregistrements lors du passage donné.

Recommandation :

• pour un déploiement typique, laissez la valeur par défaut,
• diminuez la valeur si vous souhaitez solliciter l’API de manière plus conservatrice,
• ne définissez pas0, sauf si vous souhaitez arrêter temporairement les envois.

Cron Batch Size

Par défaut :

20

Définit le nombre maximal d’enregistrements de file d’attente traités lors d’un passage 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 datescheduled_at.

Recommandation :

• 20est une valeur de départ sûre,
• pour les grandes files d’attente, la valeur peut être augmentée, mais uniquement en tenant compte des limites 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 à :

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

Dans l’implémentation actuelle, ce paramètre est utilisé lorsque la soumission n’a 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 manuellement une liste d’URL, chaque adresse valide sera planifiée avec ce délai.

Recommandation :

• définissez0si l’import manuel doit arriver immédiatement dans la file d’attente,
• laissez15si 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 :

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

Recommandation :

• pour les opérations de masse, laissez la valeur15ou 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 d’attente.

Si Google renvoie une erreur temporaire, le module définira le statutretry, à condition que le nombre de tentatives soit inférieur àMax Attempts. Après dépassement de la limite, l’enregistrement recevra le statutfailed_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 croissant. Le multiplicateur dépend du nombre de tentatives et est plafonné à24. Ainsi, les tentatives suivantes ne sont pas effectuées de manière trop agressive.

Exemple pour la valeur15:

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 commeskipped.

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 d’attente.

Allowed URL Hosts

Par défaut :

puste

Liste des hôtes 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 a 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 versionwww, 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émahttps.

Lorsque le champ est activé, une adresse avechttp sera rejetée avec l’erreur :

https_required

Recommandation :

• pour les boutiques de production, conservezYes,
• Noà utiliser uniquement dans des environnements de test exceptionnels.

9. Section Auto-Indexing

Enable Auto-Indexing

Par défaut :

No

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

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

Recommandation :

• laissezNosi auto-indexing n’a pas été déployé dans le projet,
• activez-le seulement 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 :

• 90jours est une valeur raisonnable pour le diagnostic,
• en cas de grand nombre de requests, la rétention peut être réduite,
• pour les audits SEO, la rétention peut être augmentée en tenant compte de la taille de la table de 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 :

SiCredentialsa le statutMissing or invalid, retournez dans la configuration et corrigez le JSON ou le fichier credentials.

SiAllowed HostsafficheNot configured, le module ne limite pas les hôtes. Techniquement, cela peut fonctionner, mais en production il est recommandé d’indiquer explicitement les hôtes de la boutique.

11.2. Section Setup Steps

L’assistant affiche la liste des étapes nécessaires avant le premier request réel :

1. Création ou sélection d’un projet Google Cloud.
2. Activation d’Indexing API et création d’une JSON key pour le compte de service.
3. Collage du JSON ou téléversement du fichier JSON dans la configuration Magento.
4. Ajout du service account email comme propriétaire dans Google Search Console.
5. Lancement des tests, puis import d’une URL avecDry Run.

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 valide,
• la clé privée peut être utilisée,
• Google a délivré un token OAuth.

Un résultat négatif peut indiquer :

• un JSON invalide,
• un élément incorrect ou endommagé :private_key,
• un champ requis manquant dans le JSON,
• un problème de communication avec Google,
• une clé qui n’est pas celle d’un compte de service.

Ce test ne confirme pas encore que le compte de service possède l’accès propriétaire au domaine dans Search Console. Un test URL metadata ou la soumission réelle d’une URL de test est nécessaire.

11.4. Test URL Metadata

Formulaire :

Test URL Metadata

permet de saisir une URL publique depuis un hôte autorisé et d’effectuer un request metadata vers Google Indexing API.

Avant d’envoyer le request, le module :

• normalise l’URL,
• vérifie que l’URL est absolue,
• vérifie le schémahttpouhttps,
• avecRequire HTTPS URLsactivé, exigehttps,
• vérifieAllowed URL Hostssi ceux-ci 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. Première exécution étape par étape

Ordre recommandé pour le premier lancement :

1. Installez le module et exécutezsetup:upgrade.
2. Dans Magento, accédez àStores > Configuration > Kowal > Google Indexing API.
3. DéfinissezEnable = Yes.
4. LaissezDry Run = Yes.
5. Choisissez la source des credentials.
6. Collez le JSON du compte de service ou téléversez le fichier JSON.
7. RenseignezGoogle Cloud Project IDavec la valeurproject_iddu JSON.
8. RenseignezAllowed URL Hosts, par exempleexample.com,www.example.com.
9. Laissez les limites par défaut si Google n’a pas approuvé de limites plus élevées.
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 surTest Google Credentials.
14. Ajoutez le service account email comme propriétaire dans Google Search Console si cela n’a pas encore été fait.
15. ExécutezTest URL Metadatapour une URL publique d’un hôte autorisé.
16. Accédez àGoogle Indexing API > Import URLs.
17. Ajoutez une URL de test avec l’actionURL_UPDATED.
18. Lancez cron Magento :

bin/magento cron:run

13. Import d’URL depuis l’administration

L’import manuel se trouve dans :

Google Indexing API > Import URLs

Le formulaire contient les champs :

Actions disponibles :

Après l’envoi du formulaire, le module affiche 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’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 du request,
• actionURL_UPDATEDouURL_DELETED,
• statut,
• priorité,
• nombre de tentatives,
• nombre maximal de tentatives,
• date d’envoi planifiée,
• date de traitement,
• dernier code d’erreur,
• dernière raison d’erreur,
• dernier message d’erreur,
• la réponse Google,
• informationcreated_by.

Statuts de la file d’attente

Actions sur les enregistrements de file d’attente

Remarque :Transmit Noweffectue un request réel siDry Run = No. AvecDry Run = Yes, un log dry-run sera enregistré sans envoi réel à Google.

15. Cron

Le module ajoute deux tâches cron dans le groupedefault.

Traitement de la file d’attente

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 enregistrementsprocessingdatant de plus de 30 minutes.
3. Déplace les enregistrementsscheduledverspendingsischeduled_at <= now.
4. Vérifie les slots disponibles dans les limites quotidienne et par minute.
5. Récupère les enregistrementspendingetretry.
6. Les trie par priorité et date d’envoi planifiée.
7. Envoie le request à Google ou effectue 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 request,
• URL de l’endpoint,
• payload,
• statut HTTP,
• body de la réponse,
• durée du request,
• date de création du log.

Types de requests :

17. Mass Actions et boutons d’administration

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

Produits

Sur la grille des produits, une action de masse permet d’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 à partir des URL rewrites pour les store view actives.

Pages CMS

Sur la grille des pages CMS, une action de masse permet d’ajouter les URL des pages à la file d’attente.

Le module ignore les pages inactives.

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

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

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

• produit,
• catégorie,
• page CMS.

Le bouton résout les URL de l’entité pour les store view et les ajoute à la file d’attente commeURL_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 contientprivate_keyetclient_email,
• si le champtypea la valeurservice_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,
• siclient_emaildu 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 :

• siEnable = Yes,
• si cron Magento fonctionne,
• si les enregistrements ont le statutpendingouretry,
• sischeduled_atn’est pas dans le futur,
• si les limites quotidienne ou par minute ne sont pas utilisées,
• siDaily Publish LimitetRequests Per Minute Limitne sont pas définis sur0.

Les enregistrements passent enretry

Vérifiez :

• le statut HTTP dans l’enregistrement de file,
• le log API,
• la réponse Google,
• s’il n’y a pas de limite429,
• s’il n’y a pas d’erreurs temporaires5xx,
• siMax AttemptsetRetry Delaysont définis selon vos attentes.

20. Intégration facultative 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 requis pour le fonctionnement de l’intégration principale. Il ne doit être installé que dans les projets qui utilisentamasty/blog et ont besoin d’une action de masse pour les articles de blog.