Installer le suivi des robots d'IA
Guides d'installation pas à pas pour Cloudflare, Vercel, WordPress, serveurs Node personnalisés, Webflow et Shopify.
Cette page décrit pas à pas chaque méthode d'installation. Pour savoir ce que mesure le suivi des robots et comment fonctionne la vérification, voir Robots d'IA. La même installation remonte aussi les visites humaines issues des réponses IA : elle alimente donc également la page Trafic IA. Les options d'installation côté navigateur uniquement, pour cette page, sont décrites dans Installer le suivi du trafic IA.
Choisissez le guide qui correspond à l'hébergement de votre site :
| Votre configuration | Guide à suivre |
|---|---|
| Site derrière Cloudflare (proxy nuage orange) | Worker Cloudflare |
| Application Next.js sur Vercel (ou Next.js auto-hébergé) | Middleware Vercel / Next.js |
| Site WordPress | Extension WordPress |
| Site développé sur mesure, hébergé sur vos propres serveurs (AWS, GCP, Azure, VPS, conteneurs) | Serveur personnalisé / Node |
| Site Webflow | Webflow |
| Boutique Shopify | Shopify |
Avant de commencer : générer une clé de site
Toute installation nécessite une clé de site, quelle que soit la plateforme :
- Dans l'application, allez dans Paramètres → Connexions → Suivi du site web.
- Cliquez sur Générer une clé de site. Donnez un nom à la clé et, de préférence, indiquez le domaine dont elle remontera les visites ; le domaine renforce aussi la vérification des robots signés pour ce site.
- Copiez les deux valeurs affichées dans la boîte de dialogue de
confirmation : l'identifiant de clé et le secret de signature
(qui commence par
ctk_). Le secret n'est affiché qu'une seule fois ; si vous le perdez, utilisez Renouveler sur la clé pour en générer un nouveau.
Ne divulguez pas le secret de signature : toute personne qui le détient peut
envoyer de faux rapports de trafic pour votre site. Les extraits Cloudflare,
Vercel et serveur personnalisé le lisent dans la variable d'environnement
CITLYZE_SIGNING_SECRET : il n'apparaît donc jamais dans votre code.
L'extension WordPress le conserve dans ses réglages. Ne le versionnez jamais
dans un dépôt et ne le collez jamais dans du code côté client.
Worker Cloudflare
À utiliser si votre DNS est chez Cloudflare et que le trafic du site passe par le proxy Cloudflare (le nuage orange). C'est l'option la plus complète : le Worker voit chaque requête en périphérie du réseau, remonte les vrais codes de statut HTTP et fonctionne quelle que soit la technologie utilisée derrière Cloudflare.
- Dans Paramètres → Connexions → Suivi du site web → Installer le script, ouvrez l'onglet Cloudflare et copiez l'extrait.
- Dans l'extrait, remplacez
SITE_KEY_IDpar votre identifiant de clé. Le secret de signature ne figure pas dans le code : vous l'ajouterez comme secret du Worker à l'étape 5. - Dans le tableau de bord Cloudflare, allez
dans Workers & Pages → Create → Create Worker. Donnez-lui un nom (par
exemple
ai-crawler-tracker) et cliquez sur Deploy pour créer le worker vide. - Cliquez sur Edit code, remplacez l'exemple généré par votre extrait, puis cliquez à nouveau sur Deploy.
- Ajoutez le secret de signature : dans le worker, ouvrez Settings →
Variables and Secrets → Add, choisissez le type Secret, nommez-le
CITLYZE_SIGNING_SECRET, collez votre secret de signature et cliquez sur Deploy. Cloudflare le stocke sous forme chiffrée, et il n'apparaît jamais dans le code du worker. - Reliez le worker à votre site : ouvrez Settings → Domains & Routes →
Add → Route du worker, choisissez votre zone et ajoutez la route
example.com/*. Si votre site est aussi accessible surwww.example.com, ajoutez une seconde route pourwww.example.com/*. - C'est terminé : aucune modification de code n'est nécessaire sur votre site. Le worker transmet chaque requête à votre serveur d'origine sans la modifier et remonte les visites concernées en arrière-plan.
Deux points à vérifier :
- La route doit couvrir tous les chemins (
/*) ; sinon, les visites de robots sur les pages qu'elle ne couvre pas passent inaperçues. - Si un worker tourne déjà sur ces routes : Cloudflare n'exécute qu'un seul worker par route. Intégrez la logique de l'extrait à votre worker existant au lieu d'en ajouter un second.
Middleware Vercel / Next.js
À utiliser pour une application Next.js déployée sur Vercel. Le même fichier fonctionne aussi avec un Next.js auto-hébergé.
- Dans Paramètres → Connexions → Suivi du site web → Installer le script, ouvrez l'onglet Vercel / Proxy et copiez l'extrait.
- Dans votre dépôt Next.js, créez
middleware.tsà la racine du projet (ou danssrc/si votre application s'y trouve) et collez-y l'extrait. - Remplacez
SITE_KEY_IDpar votre identifiant de clé. Le secret de signature ne figure pas dans le fichier. - Dans votre projet Vercel, ouvrez Settings → Environment Variables et
ajoutez
CITLYZE_SIGNING_SECRETavec votre secret de signature pour chaque environnement à suivre. Cochez Sensitive. Vous hébergez Next.js vous-même ? Définissez la même variable dans l'environnement de votre serveur. - Si vous avez déjà un
middleware.ts, n'ajoutez pas de second fichier : Next.js n'en exécute qu'un seul. Copiez le bloc utilitaire de l'extrait dans votre fichier existant, appelez sa fonction d'envoi au début de votre fonction middleware et vérifiez que votre configurationmatchercouvre toujours tous les chemins. - Commitez et déployez.
Remarques :
- Le middleware s'exécute avant que la réponse soit générée : les
événements indiquent donc le statut HTTP
unknown. C'est normal. Pour obtenir les codes de statut, utilisez le log drain Vercel à la place de ce middleware (utiliser les deux compterait chaque visite deux fois), ou l'installation Cloudflare ou serveur personnalisé, qui remontent aussi les redirections. - Sur Vercel, l'IP du visiteur provient d'un en-tête défini par la plateforme et elle est fiable. Si vous hébergez Next.js vous-même derrière votre propre proxy, assurez-vous que l'en-tête d'IP transférée lu par l'extrait est défini par votre proxy, et non transmis tel quel depuis le client.
Extension WordPress
À utiliser pour tout site WordPress sur lequel vous pouvez installer des extensions.
La même extension vérifie aussi, gratuitement, quels crawlers IA votre robots.txt laisse passer et ce qui bloque les autres ; voir Extension WordPress.
-
Dans l'administration WordPress, allez dans Extensions → Ajouter et recherchez AI Crawler Control by Citlyze, puis cliquez sur Installer maintenant et sur Activer. L'extension est publiée dans le répertoire officiel WordPress.org : inutile de téléverser un fichier zip.
-
Vous préférez une installation manuelle ? Dans Paramètres → Connexions → Suivi du site web → Installer le script, ouvrez l'onglet WordPress, cliquez sur Télécharger l'extension, puis téléversez le zip via Extensions → Ajouter → Téléverser une extension.
-
Allez dans Citlyze → Connect Citlyze et remplissez les trois champs :
- Tracker base URL :
https://app.citlyze.com - Key ID : votre identifiant de clé
- Signing secret : votre secret
ctk_...L'extension n'envoie rien tant que l'URL de base n'est pas renseignée.
- Tracker base URL :
-
Cliquez sur Envoyer un événement de test (« Send test event »). Une confirmation « connecté » doit s'afficher : elle prouve que vos identifiants sont valides et que la connexion fonctionne de bout en bout.
-
Derrière un proxy ou un répartiteur de charge autre que Cloudflare ? Dans Visitor IP behind a proxy, choisissez l'en-tête défini par votre proxy et indiquez les adresses du proxy, afin que les robots soient vérifiés à partir de leur IP réelle. Derrière Cloudflare, il n'y a rien à faire.
L'extension remonte chaque requête une fois la page servie, avec le code de statut exact, y compris les requêtes qu'une autre extension redirige avant l'affichage de la page. Les événements sont mis en attente dans votre base de données WordPress, puis envoyés par lots ; l'écran Connect Citlyze indique combien sont en attente et la date du dernier envoi.
À noter : les pages servies depuis un cache de pages complètes, les redirections effectuées par votre serveur web ou votre CDN et les requêtes qu'un pare-feu bloque avant le chargement de WordPress n'atteignent jamais l'extension. L'écran Connect Citlyze vous signale s'il détecte un cache de pages. Si votre site est fortement mis en cache, préférez l'installation par Worker Cloudflare ou importez les logs de votre serveur.
Serveur personnalisé / Node
À utiliser pour les sites développés sur mesure que vous hébergez vous-même : AWS, Google Cloud, Azure, un VPS ou des conteneurs. L'extrait est un middleware de style Express pour Node 20 ou version ultérieure (il fonctionne aussi avec Bun et Deno).
- Dans Paramètres → Connexions → Suivi du site web → Installer le script, ouvrez l'onglet Serveur personnalisé / Node et copiez l'extrait.
- Enregistrez-le sous
aeo-tracker.mjsà côté du point d'entrée de votre serveur. - Remplacez
SITE_KEY_IDpar votre identifiant de clé, et définissez sur le serveur la variable d'environnementCITLYZE_SIGNING_SECRETavec votre secret de signature : dans les paramètres de secrets de votre hébergeur, ou dans un fichier.envqui n'est jamais versionné. Le secret ne figure jamais dans le fichier lui-même. - Enregistrez le middleware avant vos routes :
import { aeoCrawlerTracker } from "./aeo-tracker.mjs"; app.use(aeoCrawlerTracker()); - Si votre serveur se trouve derrière un répartiteur de charge ou un
reverse proxy (nginx, ALB), configurez Express pour qu'il lui fasse
confiance (par exemple
app.set("trust proxy", 1)), afin que le middleware transmette la véritable IP du client et non celle du proxy. C'est cette IP que contrôle la vérification de l'identité des robots. - Déployez. Le middleware envoie les données une fois chaque réponse terminée : il n'ajoute donc aucune latence et inclut les vrais codes de statut HTTP.
Vous n'utilisez pas Express ? Le gestionnaire renvoyé accepte de simples
arguments (req, res, next) et s'adapte à Fastify, Koa ou au serveur http
de Node. Pour d'autres langages (Python, Go, PHP, Ruby, etc.), implémentez le
protocole de beacon signé ;
chaque POST HTTPS signé contient un lot de 50 requêtes correspondantes au
maximum.
Webflow
L'hébergement Webflow ne permet pas d'exécuter du code côté serveur, et les scripts côté navigateur ne voient pas les robots d'entraînement IA : le suivi s'installe donc au niveau d'un proxy placé devant Webflow.
- Webflow prend en charge les reverse proxies gérés par le client avec les forfaits Enterprise ; mettez-le en place avec votre interlocuteur Webflow et faites passer votre domaine par votre proxy (Cloudflare, CloudFront, Fastly ou votre propre nginx).
- Installez le tracker au niveau de ce proxy :
- Proxy sur Cloudflare → suivez le guide Worker Cloudflare.
- Votre propre proxy Node → suivez le guide Serveur personnalisé / Node.
- Toute autre solution → implémentez le protocole de beacon signé dans votre proxy.
- Vérifiez l'installation comme indiqué ci-dessous.
Les applications Webflow Cloud ne permettent pas de suivre l'ensemble du site : elles ne servent que les requêtes situées sous leur chemin de montage et ne voient donc jamais les visites de robots sur vos pages habituelles.
Shopify
Les vitrines Shopify standard ne peuvent pas exécuter ce tracker : Shopify ne permet pas aux marchands d'exécuter du code côté serveur sur les requêtes de la vitrine, ni de placer un proxy (comme Cloudflare) devant une boutique. Un script côté navigateur ne permet pas de contourner le problème : les robots d'entraînement IA n'exécutent jamais JavaScript, et un script navigateur exposerait votre secret de signature.
Ce que vous pouvez faire :
- Les vitrines headless construites avec Hydrogen et hébergées sur Oxygen (ou toute configuration auto-hébergée) exécutent du code côté serveur ; intégrez la logique de l'extrait Serveur personnalisé / Node au gestionnaire de requêtes serveur de votre vitrine.
- Pour les boutiques standard, vos autres mesures Citlyze (suivi des prompts, citations, audits GEO) fonctionnent quel que soit l'hébergement de la boutique.
Vérifier votre installation
- Dans Paramètres → Connexions → Suivi du site web, le tableau des clés de site comporte une colonne Dernier événement. Elle se met à jour dès que votre installation transmet son premier événement accepté ; les visites de robots comme les clics humains issus de réponses IA comptent.
- Avec WordPress, vous pouvez vérifier immédiatement la transmission avec Envoyer un événement de test (les événements de test vérifient les identifiants et la connexion, mais ne mettent pas à jour Dernier événement).
- Soyez patient : sur les sites à faible trafic, la première vraie visite de robot peut se faire attendre plusieurs heures, voire quelques jours. Dès que des événements arrivent, Diagnostiquer → Activité des robots d'IA → Vue d'ensemble se remplit.
- Si rien n'arrive au bout de quelques jours, vérifiez que l'identifiant de
clé de votre extrait (ou des réglages de l'extension) correspond à une clé
active et non révoquée, que
CITLYZE_SIGNING_SECRETcontient le secret de signature actuel de cette clé, et que votre route ou votre middleware couvre tous les chemins. Sans secret valide, l'extrait n'envoie rien et écrit une seule fois dans les logs « Citlyze crawler tracking is off ». - Le tableau des clés de site indique aussi quelle version du collecteur envoie les données de chaque clé, et vous signale lorsqu'une version plus récente de l'extrait ou de l'extension est disponible, ou lorsque l'extension WordPress a détecté un cache de pages.