DataFirefly Indexing API — Documentation

Présentation

DataFirefly Indexing API soumet automatiquement les produits, catégories et pages CMS de votre boutique PrestaShop aux deux APIs officielles de soumission directe : Google Indexing API (authentification Service Account OAuth2, signature JWT RS256 native) et IndexNow via le relais api.indexnow.org qui propage vers Bing, Yandex, Naver et Seznam en un seul appel. Le module s’accroche aux hooks PrestaShop natifs, enfile chaque modification dans une file d’attente déduplifiée, et un CRON traite le lot toutes les quelques minutes. Vous gardez un journal complet des soumissions et un dashboard du taux d’acceptation.

Prérequis

• PrestaShop 8.0 à 8.99, ou PrestaShop 9.x
• PHP 7.4 à 8.3
• Extensions PHP openssl (pour la signature JWT RS256 de Google) et curl (pour les requêtes HTTP)
• Un CRON système ou un service de CRON externe pour appeler le traitement de la file d’attente toutes les 5 à 15 minutes
• Optionnel — pour Google : un compte Google Cloud avec un projet où activer l’Indexing API et créer un Service Account, et une propriété Search Console vérifiée pour votre domaine

Installation

Étape 1 — Téléchargement

Téléchargez le ZIP dfindexingapi-1.0.0.zip depuis votre compte DataFirefly après achat.

Étape 2 — Installation via le back-office

1. Connectez-vous à votre back-office PrestaShop
2. Allez dans Modules › Gestionnaire de modules › Installer un module
3. Cliquez sur Sélectionner un fichier et choisissez le ZIP téléchargé
4. Validez. PrestaShop décompresse et installe le module
5. Une fois installé, cliquez sur Configurer

Étape 3 — Vérifications post-installation

À l’installation, le module crée automatiquement :

• Les deux tables SQL ps_df_indexapi_queue (file d’attente) et ps_df_indexapi_log (journal)
• Une clé IndexNow alphanumérique de 32 caractères
• Un jeton CRON aléatoire de 32 caractères
• 5 onglets dans le menu admin : parent DataFirefly Indexing API, puis Dashboard, File d’attente, Journal, Configuration

Ouvrez l’onglet Configuration pour passer à l’étape suivante.

Configuration de Google Indexing API

L’API Google Indexing nécessite un Service Account Google Cloud. La procédure prend environ 5 minutes.

Étape 1 — Créer un projet Google Cloud

1. Allez sur console.cloud.google.com et connectez-vous
2. En haut, cliquez sur le sélecteur de projet, puis Nouveau projet
3. Donnez-lui un nom (par exemple Indexing API Boutique) et créez-le
4. Sélectionnez le projet nouvellement créé

Étape 2 — Activer l’Indexing API

1. Dans le menu de gauche, allez dans APIs et services › Bibliothèque
2. Recherchez Indexing API
3. Cliquez sur Activer

Étape 3 — Créer un Service Account

1. Allez dans APIs et services › Identifiants
2. Cliquez sur Créer des identifiants › Compte de service
3. Donnez-lui un nom (par exemple indexing-api-prestashop)
4. Aucun rôle IAM n’est nécessaire — passez à l’étape suivante et finalisez la création
5. Dans la liste des comptes de service, cliquez sur le compte créé
6. Onglet Clés › Ajouter une clé › Créer une nouvelle clé
7. Format JSON. Téléchargez et conservez le fichier — il ne pourra plus être récupéré ensuite

Étape 4 — Ajouter le Service Account à Search Console

1. Copiez l’email du Service Account (forme nom@projet.iam.gserviceaccount.com) depuis Google Cloud
2. Allez sur Google Search Console
3. Sélectionnez votre propriété (le domaine de votre boutique)
4. Allez dans Paramètres › Utilisateurs et autorisations
5. Cliquez sur Ajouter un utilisateur, collez l’email du Service Account, sélectionnez le rôle Propriétaire
6. Validez

Étape 5 — Coller le JSON dans le module

1. Ouvrez le fichier JSON téléchargé dans un éditeur de texte
2. Copiez tout son contenu
3. Dans la configuration du module, section Google Indexing API, cochez Activer Google Indexing API
4. Collez le JSON complet dans le champ Service Account JSON
5. Enregistrez

Étape 6 — Tester la connexion

Cliquez sur le bouton Tester Google dans la page de configuration. Le module signe un JWT RS256, l’échange contre un jeton OAuth2, et affiche le résultat. Si tout est correct, vous voyez un message vert Authentification OK.

Configuration d’IndexNow

IndexNow est plus simple à configurer : pas de Service Account, pas d’OAuth, pas de quota. Juste une clé à publier à la racine de votre domaine.

Comprendre IndexNow

IndexNow est un protocole ouvert poussé par Microsoft Bing et Yandex en 2021, rejoint depuis par Naver et Seznam. Vous générez une clé alphanumérique, vous la publiez à la racine de votre domaine sous la forme d’un fichier accessible publiquement, et vous appelez api.indexnow.org avec une liste d’URLs. Le serveur vérifie la clé en lisant le fichier de votre domaine, puis propage les URLs aux moteurs participants.

Méthode 1 — Récriture .htaccess (recommandée)

C’est la méthode la plus simple : le module sert lui-même le contenu du fichier clé via un contrôleur frontend, et une règle .htaccess à la racine de votre boutique réécrit la requête vers ce contrôleur.

1. Dans la configuration du module, ouvrez l’onglet IndexNow
2. Cochez Activer IndexNow
3. Vérifiez le champ Hôte — il doit correspondre au domaine de votre boutique sans le protocole (par exemple ma-boutique.fr)
4. Enregistrez
5. Copiez le snippet .htaccess affiché dans la page de configuration — il est généré dynamiquement avec votre clé courante
6. Collez ce snippet en haut du fichier .htaccess à la racine de PrestaShop, juste après le bloc RewriteEngine on
7. Cliquez sur Tester IndexNow dans la configuration — le module appelle l’URL du fichier clé sur votre domaine et vérifie qu’elle renvoie bien le contenu attendu en text/plain

Méthode 2 — Fichier physique

Si vous ne pouvez pas modifier le .htaccess, créez manuellement un fichier physique à la racine du domaine.

1. Récupérez votre clé IndexNow depuis la configuration du module (champ Clé IndexNow)
2. Créez un fichier dont le nom est exactement la clé + .txt (par exemple a1b2c3d4e5f6.txt) à la racine de votre domaine
3. Le contenu du fichier doit être uniquement la clé elle-même, sans saut de ligne
4. Vérifiez que https://votre-domaine.com/a1b2c3d4e5f6.txt renvoie bien la clé en text/plain
5. Cliquez sur Tester IndexNow

Configuration du CRON

Le CRON est l’élément qui fait tourner le traitement de la file d’attente. Sans CRON appelé régulièrement, les soumissions s’empilent mais ne partent jamais.

Action process — traitement de la file d’attente

À appeler toutes les 5 à 15 minutes. Le module traite un lot configurable (par défaut 50 jobs) en suivant la déduplication et les filtres d’indexation, puis met à jour le journal et la file.

L’URL exacte est affichée dans la configuration. Elle ressemble à :

https://votre-domaine.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=VOTRE_JETON

Action purge — nettoyage du journal

À appeler une fois par jour. Le module supprime les jobs et logs traités au-delà de la rétention configurée (par défaut 30 jours).

https://votre-domaine.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=VOTRE_JETON

Action key — fichier clé IndexNow

Utilisée uniquement par la récriture .htaccess. Vous n’appelez jamais cette URL manuellement.

Configurer votre CRON système

Sous Linux/cPanel, ajoutez deux lignes dans crontab :

# Toutes les 10 minutes — traitement de la file d'attente
*/10 * * * * curl -s "https://votre-domaine.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=process&token=VOTRE_JETON" > /dev/null

# Une fois par jour à 3h — purge du journal
0 3 * * * curl -s "https://votre-domaine.com/index.php?fc=module&module=dfindexingapi&controller=cron&dfaction=purge&token=VOTRE_JETON" > /dev/null

Sécurité du jeton CRON

Le jeton est un secret de 32 caractères généré à l’installation. Sans le bon jeton dans le paramètre token=, le contrôleur renvoie HTTP 403. Vous pouvez régénérer le jeton à tout moment depuis la configuration (bouton Régénérer le jeton CRON) — pensez alors à mettre à jour vos lignes crontab avec le nouveau jeton.

Le Dashboard

L’onglet Dashboard est votre vue d’ensemble en temps réel.

Compteurs de file d’attente

Cinq cartes en haut de page :

• En attente — jobs créés mais pas encore traités
• En cours — jobs verrouillés en traitement par un CRON actif
• Soumis — jobs traités avec succès (cumul historique non purgé)
• Erreur — jobs ayant échoué après N tentatives maximales
• Ignoré — jobs créés mais ignorés par un filtre (par exemple URL_DELETED en IndexNow)

Diagnostic des providers

Deux cartes affichent l’état de configuration :

• Google Indexing API — actif, mal configuré, ou désactivé. Indique si le JSON Service Account est présent et valide
• IndexNow — actif, mal configuré, ou désactivé. Indique si la clé et l’hôte sont configurés

Taux d’acceptation 30 jours

Tableau croisé provider × statut sur les 30 derniers jours, avec coloration sémantique : vert au-dessus de 90 %, orange entre 60 et 90 %, rouge en dessous. Si Google chute sous 90 %, c’est généralement un signe que vous avez dépassé le quota ou que des URLs ne sont plus accessibles.

Graphique des soumissions quotidiennes

Graphique Chart.js superposant deux courbes par jour : total soumis et total accepté. Utile pour repérer rapidement les chutes ou les pics anormaux.

La File d’attente

L’onglet File d’attente liste tous les jobs (pending, processing, submitted, error, skipped) avec filtres natifs PrestaShop par boutique, type d’objet, ID, provider, statut, date.

Statuts des jobs

• pending — créé, en attente de traitement par le prochain CRON
• processing — verrouillé par un CRON actif (transition logique pour éviter le double traitement en parallèle)
• submitted — soumission réussie à l’API. Le compteur de tentatives est gelé
• error — toutes les tentatives ont échoué. Reste consultable avec le message d’erreur exact retourné par l’API
• skipped — créé puis ignoré (par exemple URL_DELETED IndexNow, ou filtre désactivé)

Actions individuelles

Chaque ligne propose :

• Relancer — remet le job en pending et réinitialise le compteur de tentatives
• Supprimer — efface le job de la file

Actions en masse

Boutons en haut de liste :

• Relancer tous les jobs en erreur — remet en pending tous les jobs en statut error
• Purger les jobs traités — supprime tous les submitted/skipped quel que soit leur âge

Le Journal

L’onglet Journal liste chaque soumission individuelle réalisée : provider, type, ID d’objet, URL soumise, action (URL_UPDATED ou URL_DELETED), code HTTP retourné, indicateur accepté/refusé, message complet de réponse, et date. Filtrable, triable, exportable en CSV via le HelperList PrestaShop standard.

Filtres d’indexation

Dans la configuration, vous pouvez activer ou désactiver indépendamment trois types d’objets :

• Produits — soumission sur création, modification, suppression, désactivation
• Catégories — soumission sur création, modification, suppression. La racine catégorie (ID 1 et 2) est ignorée par sécurité
• Pages CMS — soumission sur création, modification, suppression

Désactiver un filtre arrête immédiatement l’enfilage pour ce type, mais ne purge pas la file existante.

Multi-boutique

Le module est nativement multi-boutique. La configuration (clés Google, clé IndexNow, hôte, activations) est indépendante par sous-boutique. Les jobs et logs sont scopés par id_shop — un même produit dans deux sous-boutiques génère deux jobs distincts avec leurs propres URLs canoniques.

Pour configurer indépendamment chaque sous-boutique, utilisez le sélecteur multistore en haut de l’admin avant d’ouvrir la configuration.

Hooks PrestaShop écoutés

Le module enregistre les hooks suivants à l’installation :

• actionProductSave — création ou modification d’un produit. Si actif, enfile URL_UPDATED ; sinon URL_DELETED
• actionProductDelete — suppression définitive d’un produit. Enfile URL_DELETED
• actionObjectCmsAddAfter — création d’une page CMS
• actionObjectCmsUpdateAfter — modification d’une page CMS
• actionObjectCmsDeleteAfter — suppression d’une page CMS
• actionCategoryAdd — création d’une catégorie
• actionCategoryUpdate — modification d’une catégorie
• actionCategoryDelete — suppression d’une catégorie
• displayBackOfficeHeader — injection d’un fragment CSS pour le styling du dashboard

Chaque hook construit l’URL canonique via l’objet Link officiel de PrestaShop, ce qui respecte vos préférences SEO friendly URL et les préfixes de langue multilingue.

Dépannage

Le test Google échoue avec un code 401

L’authentification a échoué. Vérifiez que :

• Le JSON Service Account collé est complet et bien formé
• L’Indexing API est bien activée dans Google Cloud (bibliothèque)
• L’horloge système du serveur est correcte — un décalage de plus de 5 minutes invalide le JWT

Le test Google échoue avec un code 403

L’authentification réussit mais Google refuse la requête. Cause habituelle : le Service Account n’a pas été ajouté comme Propriétaire de la propriété Search Console. Re-vérifiez l’étape 4 de la configuration Google.

Le test IndexNow échoue

Le serveur api.indexnow.org n’a pas pu lire le fichier clé sur votre domaine. Causes possibles :

• Le snippet .htaccess n’a pas été collé, ou collé au mauvais endroit (il doit être après RewriteEngine on)
• Le fichier physique n’a pas été créé, ou n’a pas le bon nom (doit être exactement la clé + .txt)
• Le contenu du fichier ne correspond pas à la clé (faute de frappe, saut de ligne supplémentaire)
• Le serveur web sert le fichier avec le mauvais Content-Type (doit être text/plain)
• Le pare-feu ou le CDN bloque les requêtes du robot IndexNow

Ouvrez https://votre-domaine.com/VOTRE_CLE.txt dans un navigateur en navigation privée — vous devez voir uniquement la clé en texte brut.

Des jobs restent bloqués en statut processing

Cela signifie qu’un CRON a verrouillé les jobs mais n’a jamais relâché le lock (par exemple le processus a été tué par un timeout PHP). Vous pouvez les débloquer manuellement en passant par phpMyAdmin :

UPDATE ps_df_indexapi_queue SET status = 'pending', attempts = 0 WHERE status = 'processing';

Si le problème se reproduit régulièrement, augmentez le max_execution_time PHP de votre hébergement, ou réduisez la taille du lot dans la configuration du module.

Le quota Google est dépassé

Google répond avec un code 429 ou un message Quota exceeded. Trois options :

• Attendre 24h — le quota se réinitialise quotidiennement
• Demander une augmentation de quota à Google via la console Cloud (Quotas et limites système). Justifiez en expliquant que votre boutique e-commerce nécessite davantage de soumissions quotidiennes
• Créer un second Service Account et alterner — chaque Service Account a son propre quota de 200 URLs/jour

Réinitialisation complète

Pour repartir de zéro (utile en cas de migration ou de problème complexe) :

1. Désinstaller le module depuis Modules › Gestionnaire
2. Réinstaller — les tables sont recréées, la clé IndexNow et le jeton CRON sont régénérés
3. Reconfigurer Google et IndexNow
4. Mettre à jour le snippet .htaccess avec la nouvelle clé
5. Mettre à jour les lignes crontab avec le nouveau jeton

Limites connues

• IndexNow ne gère pas URL_DELETED — le protocole considère qu’une 404 ou 410 sur l’URL est la bonne façon de signaler une suppression. Le module ignore donc les jobs IndexNow en URL_DELETED (Google les soumet bien, lui)
• Quota Google plafonné à 200 URLs/jour par Service Account par défaut
• Variantes produit non soumises individuellement — l’URL canonique du produit principal suffit, Google consolide naturellement les variantes
• Racine catégorie ignorée (ID 1 et 2) pour éviter de soumettre des URLs non pertinentes
• API Indexing Google officiellement limitée aux pages JobPosting ou BroadcastEvent — l’API accepte les autres types et répond 200, mais Google peut ignorer l’indexation finale. Pour la majorité des boutiques, IndexNow reste la solution la plus impactante en pratique

Support

Pour toute question technique : support@datafirefly.com — réponse sous 24h ouvrées en français ou anglais. Inclus pendant 12 mois après l’achat.