Predictive SEO — Documentation complète

Vue d’ensemble

DataFirefly Predictive SEO connecte votre PrestaShop à Google Search Console, applique un moteur de prédiction ML embarqué sur l’historique de recherche et identifie automatiquement les pics saisonniers à venir. Pour chaque opportunité détectée, vous pouvez générer en un clic un brief de contenu structuré via Mistral, OpenAI ou Claude.

Pré-requis

• PrestaShop 8.0+ ou PrestaShop 9.x
• PHP 8.1 minimum
• MySQL 5.7+ ou MariaDB 10.3+
• Un compte Google avec accès à la propriété Search Console de la boutique
• Une clé API d’un provider IA (Mistral, OpenAI ou Anthropic — Mistral par défaut, environ 0,002 € par brief)
• Au minimum 60 à 90 jours d’historique GSC pour des prédictions fiables

Installation

Installation depuis le ZIP

1. Téléchargez le ZIP dfpredictiveseo.zip depuis votre espace client DataFirefly.
2. Dans le back-office PrestaShop, allez dans Modules → Gestionnaire de modules.
3. Cliquez sur Téléverser un module et déposez le ZIP.
4. Le module s’installe automatiquement, crée les 7 tables dfpseo_*, enregistre les 6 onglets sous IMPROVE et génère un token de cron unique.
5. Une fois installé, vous trouvez le module dans le menu Améliorer → Predictive SEO.

Schéma de base de données

L’installation crée 7 tables avec le préfixe dfpseo_ :

• dfpseo_keyword — mots-clés trackés depuis GSC
• dfpseo_history — historique journalier (impressions, clics, CTR, position)
• dfpseo_forecast — prédictions journalières avec intervalles de confiance
• dfpseo_opportunity — opportunités saisonnières détectées
• dfpseo_recommendation — briefs de contenu générés par l’IA
• dfpseo_seasonality — indices saisonniers (jour-de-semaine × mois) par mot-clé
• dfpseo_sync_log — journal des synchronisations GSC

Configuration Google Search Console

Le module utilise le protocole OAuth2 standard. Vous créez un OAuth Client dans Google Cloud, collez les identifiants dans les réglages, et lancez le flow d’autorisation depuis le bouton Connecter.

Étape 1 — Créer un projet Google Cloud

1. Rendez-vous sur console.cloud.google.com et connectez-vous avec le compte Google qui a accès à votre propriété Search Console.
2. Cliquez sur le sélecteur de projet en haut à gauche, puis sur Nouveau projet.
3. Nommez-le par exemple DataFirefly Predictive SEO et créez-le.

Étape 2 — Activer l’API Search Console

1. Dans le menu de gauche, allez dans APIs & Services → Bibliothèque.
2. Recherchez Search Console API et cliquez sur Activer.

Étape 3 — Configurer l’écran de consentement OAuth

1. Allez dans APIs & Services → Écran de consentement OAuth.
2. Type d’utilisateur : Externe.
3. Remplissez nom de l’app, email de support, domaine autorisé (votre boutique).
4. Dans Champs d’application, ajoutez https://www.googleapis.com/auth/webmasters.readonly (lecture seule Search Console).
5. En mode test, ajoutez votre email dans Utilisateurs de test. Vous pouvez passer en production plus tard sans modification du module.

Étape 4 — Créer le Client OAuth

1. Allez dans APIs & Services → Identifiants.
2. Cliquez sur Créer des identifiants → ID client OAuth.
3. Type d’application : Application Web.
4. Nom : libre (par exemple Predictive SEO Production).
5. URI de redirection autorisé : copiez l’URI affichée dans les réglages du module (Improve → Predictive SEO → Réglages → Google Search Console → URI de redirection). Format : https://votre-boutique.com/module/dfpredictiveseo/settings/oauth_callback.
6. Cliquez sur Créer — Google affiche le client_id et le client_secret.

Étape 5 — Connecter le module

1. Dans les réglages Predictive SEO, collez le client_id et le client_secret.
2. Sauvegardez.
3. Cliquez sur Connecter à Google Search Console.
4. Vous êtes redirigé vers la page de consentement Google. Autorisez l’accès en lecture seule.
5. De retour sur le back-office, le module a stocké le refresh_token chiffré et est prêt à synchroniser.
6. Sélectionnez ensuite la propriété Search Console à tracker dans le dropdown (le module la détecte automatiquement après la connexion).

Configuration du provider IA

Le module supporte 3 providers IA pour générer les briefs de contenu. Vous n’avez besoin que d’un seul, et vous fournissez votre propre clé API du provider choisi — DataFirefly ne prélève aucune commission sur l’usage.

Mistral (par défaut, recommandé)

• Modèle : mistral-small-latest
• Coût indicatif : environ 0,002 € par brief généré
• Créer la clé : console.mistral.ai → API Keys
• Coller la clé dans Réglages → Provider IA → Clé API Mistral

OpenAI

• Modèle : gpt-4o-mini
• Coût indicatif : environ 0,005 € par brief
• Créer la clé : platform.openai.com → API keys
• Coller la clé dans Réglages → Provider IA → Clé API OpenAI

Anthropic (Claude)

• Modèle : claude-3-5-haiku-latest
• Coût indicatif : environ 0,004 € par brief
• Créer la clé : console.anthropic.com → API Keys
• Coller la clé dans Réglages → Provider IA → Clé API Anthropic

Sélectionnez ensuite le provider actif dans le dropdown Provider IA actif. Si vous changez de provider, les briefs déjà générés ne sont pas régénérés automatiquement.

Synchronisation des données

Première synchronisation

Une fois la connexion GSC établie, lancez une première synchronisation manuelle : Réglages → Lancer la synchronisation. Le module rapatrie l’historique des 90 derniers jours pour la propriété sélectionnée — jusqu’à 250 000 lignes par sync, avec les dimensions date × requête × page. La première sync peut prendre 30 secondes à 2 minutes selon le volume.

Cron quotidien

Pour les synchronisations automatiques, configurez un cron quotidien (recommandé : tôt le matin, 4h-6h heure de Paris) qui appelle l’endpoint sécurisé du module.

L’URL exacte et le token sont affichés dans Réglages → Cron. Format générique :

https://votre-boutique.com/module/dfpredictiveseo/cron/sync?token=VOTRE_TOKEN_GENERE

Exemple de ligne crontab (cron Unix) :

0 5 * * * curl -s "https://votre-boutique.com/module/dfpredictiveseo/cron/sync?token=VOTRE_TOKEN" > /dev/null 2>&1

Pipeline d’une synchronisation

Chaque sync exécute en séquence :

1. Pull GSC sur les 90 derniers jours glissants (dimensions date/query/page)
2. Insertion/mise à jour dans dfpseo_keyword et dfpseo_history
3. Recalcul des indices saisonniers (par mot-clé ayant assez d’historique)
4. Génération des forecasts sur l’horizon configuré
5. Détection des opportunités sur la fenêtre future
6. Log dans dfpseo_sync_log

Dashboard

Le dashboard (Improve → Predictive SEO → Tableau de bord) regroupe les indicateurs clés :

• 4 KPI cards : mots-clés suivis, opportunités à venir, clics prévus sur 14 jours, dernière sync GSC
• Graphique principal : courbe agrégée historique (90 jours) + forecast (horizon configuré, 30 jours par défaut), avec bande de confiance 95 %
• Top opportunités : les 10 prochains pics saisonniers triés par score
• Journal de syncs : les 5 dernières synchronisations avec leur statut

Statut de la connexion

Deux badges en haut du dashboard indiquent l’état des intégrations : GSC connecté (vert/rouge) et Provider IA configuré (vert/rouge). Si l’un des deux est rouge, suivez le lien direct vers les réglages correspondants.

Mots-clés & prévisions

Liste des mots-clés

L’onglet Mots-clés affiche la grille native PrestaShop avec toutes les requêtes synchronisées. Colonnes : requête, page d’atterrissage, impressions 30 j, clics 30 j, CTR, position moyenne, dernière mise à jour. Vous pouvez filtrer, trier et exporter.

Vue détaillée par mot-clé

Un clic sur un mot-clé ouvre sa fiche :

• Courbe individuelle historique + forecast personnel
• Intervalle de confiance 95 % autour de la prédiction
• Heatmap saisonnière 12 × 7 (mois × jour-de-semaine)
• Indices saisonniers calculés
• Liste des opportunités liées à ce mot-clé

Heatmap de saisonnalité

La heatmap visualise les indices saisonniers multiplicatifs. Lecture :

• Cellule à 1,00 → trafic moyen sur cette combinaison mois × jour
• Cellule à 1,50 → trafic 50 % au-dessus de la moyenne (pic saisonnier)
• Cellule à 0,60 → trafic 40 % en-dessous de la moyenne (creux)

Les cellules sont colorées du bleu pâle (creux) au bleu profond et rouge-orange (pic). Un coup d’œil suffit pour repérer les semaines à exploiter.

Opportunités saisonnières

Détection automatique

Une opportunité est détectée lorsque, sur une fenêtre future de 14 jours (configurable via DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS) :

• La prédiction dépasse la baseline du mot-clé × 1,25 (seuil de pic)
• ET l’indice saisonnier de la combinaison mois × jour est supérieur à 1,10

Les pics contigus (gap ≤ 2 jours) sont regroupés en une seule opportunité couvrant la fenêtre complète.

Score d’opportunité

Le score combine trois facteurs :

score = clics_attendus × lift × confiance

• clics_attendus : somme des clics prédits sur la fenêtre
• lift : rapport pic / baseline
• confiance : largeur de l’intervalle de prédiction (plus l’intervalle est étroit, plus le score est élevé)

Un score > 80 indique une opportunité à fort potentiel et fort signal saisonnier. Un score 40-80 indique une opportunité modérée. En-dessous de 40, le signal est trop faible ou trop incertain pour justifier une action prioritaire.

Workflow d’opportunité

Chaque opportunité a un statut :

• Nouveau — fraîchement détectée, en attente de décision
• En cours — un brief a été généré, en travail rédactionnel
• Traitée — contenu publié, opportunité exploitée
• Ignorée — décision de ne pas traiter (faux positif, hors stratégie)

Recommandations IA

Générer un brief

Depuis n’importe quelle opportunité, cliquez sur Générer le brief. Le module envoie une requête au provider IA actif avec le contexte du mot-clé (volume, saisonnalité, position actuelle, page concernée) et reçoit un brief structuré JSON contenant :

• summary — résumé stratégique du brief
• meta_description — meta description SEO prête à coller (150-160 caractères)
• search_intent — intention de recherche dominante (informationnelle / transactionnelle / navigationnelle / commerciale)
• outline — plan détaillé h1/h2/h3 de l’article ou de la page
• keywords_to_include — mots-clés sémantiques à inclure
• internal_links — suggestions de maillage interne vers d’autres pages du site
• rationale — justification stratégique de la recommandation

La génération prend 1 à 3 secondes selon le provider.

Workflow d’approbation

Chaque brief passe par les statuts :

1. Pending — généré, en attente de revue
2. Approved — validé pour rédaction
3. Published — contenu mis en ligne (à marquer manuellement)
4. Rejected — refusé (brief de mauvaise qualité ou hors sujet)
5. Draft — en cours de modification

Le workflow vous permet de garder une trace claire de ce qui a été traité.

Architecture technique

Stack

• Architecture PSR-4, namespace DfPredictiveSeo → src/
• Controllers Symfony étendant FrameworkBundleAdminController
• Repositories Doctrine DBAL (pas d’ObjectModel)
• GSC accédée en REST direct via cURL + OAuth2 (pas de google/apiclient, pour rester léger)
• Aucune dépendance Composer obligatoire à l’installation (autoloader PSR-4 embarqué)

Pipeline ML

1. Décomposition saisonnière multiplicative : indices jour-de-semaine et mois calculés via moyenne mobile centrée 28 jours et moyenne tronquée 10 %
2. Régression OLS sur log(impressions+1) pour modéliser la tendance log-linéaire
3. Forecast : exp(prediction_log) × indice_saisonnier_jour × indice_saisonnier_mois
4. Intervalles 95 % : approximation Student sur l’erreur résiduelle de la régression, élargissement progressif avec l’horizon

Endpoint cron

L’endpoint est public mais protégé par token. Exemple en PHP pour appel programmatique :

$token = 'votre_token_cron';
$url = 'https://votre-boutique.com/module/dfpredictiveseo/cron/sync?token=' . $token;
$response = file_get_contents($url);
$data = json_decode($response, true);
// $data['status'] = 'ok' | 'error'
// $data['keywords_synced'] = nombre de mots-clés mis à jour
// $data['opportunities_detected'] = nombre d'opportunités nouvellement détectées

Variables de configuration

Le module stocke 18 clés de configuration dans la table ps_configuration :

• DFPSEO_GSC_CLIENT_ID, DFPSEO_GSC_CLIENT_SECRET, DFPSEO_GSC_REFRESH_TOKEN (chiffré), DFPSEO_GSC_PROPERTY
• DFPSEO_AI_PROVIDER, DFPSEO_AI_MISTRAL_KEY, DFPSEO_AI_OPENAI_KEY, DFPSEO_AI_ANTHROPIC_KEY
• DFPSEO_FORECAST_HORIZON_DAYS (défaut : 30)
• DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS (défaut : 14)
• DFPSEO_PEAK_THRESHOLD (défaut : 1.25)
• DFPSEO_SEASONAL_THRESHOLD (défaut : 1.10)
• DFPSEO_CRON_TOKEN (généré à l’installation)
• DFPSEO_LAST_SYNC, DFPSEO_LAST_FORECAST

Dépannage

Erreur redirect_uri_mismatch au moment de la connexion GSC

L’URI de redirection configurée dans Google Cloud ne correspond pas exactement à celle attendue par le module. Vérifiez :

• Protocole : https:// et pas http://
• Pas de trailing slash : ...oauth_callback et pas ...oauth_callback/
• Sous-domaine : www. ou pas selon votre boutique, doit matcher

La sync GSC ne retourne aucun mot-clé

• Vérifiez que la propriété sélectionnée dans les réglages est bien celle qui reçoit du trafic SEO (et pas un domain property vide)
• Vérifiez que le compte Google connecté est propriétaire ou utilisateur autorisé sur cette propriété
• La propriété doit avoir au moins quelques jours d’historique indexé (Google Search Console publie les données avec 2-3 jours de délai)

Les prédictions semblent peu fiables

• Vérifiez que vous avez au moins 60-90 jours d’historique. En-dessous, les indices saisonniers ne peuvent pas être correctement estimés
• Pour les mots-clés erratiques (peu de signal, beaucoup de bruit), la largeur de l’intervalle 95 % est volontairement étendue — le module affiche explicitement une faible confiance
• Pour des prédictions plus précises sur des horizons longs (60-90 jours), attendez d’avoir accumulé 6-12 mois d’historique. Le moteur s’améliore avec le temps

L’endpoint cron retourne une erreur 403

Le token passé en query string ne correspond pas à DFPSEO_CRON_TOKEN. Vérifiez la valeur exacte dans Réglages → Cron. En cas de doute, régénérez le token et mettez à jour votre crontab.

Le brief IA n’est pas généré

• Vérifiez que vous avez bien collé une clé API valide pour le provider actif sélectionné
• Vérifiez votre solde sur la console du provider (Mistral, OpenAI ou Anthropic)
• Si le provider retourne une erreur de rate limit, attendez quelques minutes et réessayez
• Les briefs générés sont stockés dans dfpseo_recommendation ; en cas d’erreur, l’erreur est aussi loggée dans cette table avec le statut error

FAQ

Le module fonctionne-t-il sans Google Search Console ?

Non, GSC est la source de données primordiale. Le module a besoin d’un minimum de 60 à 90 jours d’historique pour produire des prédictions fiables et calculer la saisonnalité. Si votre boutique vient d’être lancée, attendez d’avoir au moins 2 mois de données indexées avant d’installer le module.

Combien coûte un brief IA ?

Cela dépend du provider choisi. Avec Mistral (défaut), comptez environ 0,002 € par brief. OpenAI GPT-4o-mini autour de 0,005 €. Claude Haiku autour de 0,004 €. Vous fournissez votre propre clé API et payez directement le provider — DataFirefly ne prélève aucune commission.

Combien de mots-clés le module peut-il tracker ?

Il n’y a pas de limite codée en dur. Une sync standard rapatrie jusqu’à 250 000 lignes (date × query × page) par appel — ce qui couvre la quasi-totalité des boutiques. Au-delà, augmentez la mémoire PHP allouée au worker cron.

Le module est-il compatible avec d’autres modules SEO ?

Oui, Predictive SEO n’écrit jamais sur les pages produits ou les meta — il ne fait que lire GSC et produire des recommandations. Il est totalement compatible avec tous les modules SEO existants (DataFirefly ou tiers).

Mes données GSC sont-elles stockées chez DataFirefly ?

Non. Toutes les données restent sur votre serveur, dans votre base de données PrestaShop. Le module appelle directement l’API Google avec vos identifiants OAuth, et appelle directement les providers IA avec votre clé API. Aucune donnée ne transite par les serveurs DataFirefly.

Quel horizon de prédiction est le plus fiable ?

L’horizon 7-14 jours est très fiable (intervalle 95 % étroit). L’horizon 30-60 jours est indicatif (intervalle élargi). Au-delà de 90 jours, les prédictions deviennent peu utiles pour des décisions opérationnelles — le module les calcule mais affiche une confiance basse.