Installer le suivi des robots d'IA

Cette page détaille chaque parcours d'installation, clic par clic. Pour savoir ce que mesure le suivi des robots et comment fonctionne la vérification, voir Robots d'IA.

Choisissez le guide qui correspond à l'endroit où tourne votre site :

Avant de commencer : générer une clé de site

Chaque installation nécessite une clé de site, quelle que soit la plateforme :

1. Dans l'application, allez dans Robots d'IA → Installer le suivi.
2. Cliquez sur Générer une clé de site. Donnez un nom à la clé et, idéalement, le domaine pour lequel elle rapportera ; le domaine renforce aussi la vérification des robots signés pour ce site.
3. Copiez les deux valeurs du dialogue de confirmation : l'identifiant de clé et le secret de signature (il 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.

Gardez le secret de signature privé : quiconque le détient peut soumettre de faux rapports de trafic pour votre site. Ne le commitez pas dans un dépôt public et ne le collez pas dans du code côté client.

Worker Cloudflare

À utiliser quand votre DNS est chez Cloudflare et que le site est proxifié (le bouton nuage orange). C'est l'option la plus complète : elle voit chaque requête à la périphérie, rapporte les vrais codes de statut HTTP et fonctionne quoi qu'il y ait derrière Cloudflare.

1. Sur Robots d'IA → Installer le suivi, ouvrez l'onglet Cloudflare et copiez l'extrait.
2. Remplacez SITE_KEY_ID et ctk_SITE_KEY_SECRET dans l'extrait par votre identifiant de clé et votre secret de signature.
3. 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.
4. Cliquez sur Edit code, remplacez l'exemple généré par votre extrait, puis cliquez à nouveau sur Deploy.
5. Connectez 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 servi sur www.example.com, ajoutez une seconde route pour www.example.com/*.
6. Terminé : aucun changement de code sur votre site. Le worker transmet chaque requête à votre origine sans la modifier et rapporte les visites correspondantes en arrière-plan.

Deux points à vérifier :

• La route doit couvrir tous les chemins (/*), sinon les visites de robots sur les pages non routées sont invisibles.
• Si vous exécutez déjà un worker sur ces routes, Cloudflare n'exécute qu'un seul worker par route ; fusionnez la logique de l'extrait dans 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 sur un Next.js auto-hébergé.

1. Sur Robots d'IA → Installer le suivi, ouvrez l'onglet Vercel / reverse proxy et copiez l'extrait.
2. Dans votre dépôt Next.js, créez middleware.ts à la racine du projet (ou dans src/ si votre application y vit) et collez l'extrait.
3. Remplacez SITE_KEY_ID et ctk_SITE_KEY_SECRET par votre identifiant de clé et votre secret de signature.
4. Si vous avez déjà un middleware.ts, n'ajoutez pas un second fichier : Next.js n'en exécute qu'un. Copiez le bloc utilitaire de l'extrait dans votre fichier existant, appelez sa logique de rapport au début de votre fonction middleware, et vérifiez que votre config matcher couvre toujours tous les chemins.
5. Commitez et déployez.

Remarques :

• Le middleware s'exécute avant que la réponse existe, donc les événements rapportent leur statut HTTP comme unknown. C'est attendu ; les insights d'erreurs nécessitent l'installation Cloudflare ou serveur personnalisé.
• Sur Vercel, l'IP du visiteur provient d'un en-tête défini par la plateforme et est fiable. Si vous auto-hébergez Next.js 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 où vous pouvez installer des extensions.

1. Sur Robots d'IA → Installer le suivi, ouvrez l'onglet WordPress et cliquez sur Télécharger l'extension.
2. Dans l'admin WordPress, allez dans Extensions → Ajouter → Téléverser une extension, choisissez le zip téléchargé, cliquez sur Installer maintenant, puis sur Activer.
3. Allez dans Réglages → AI Crawler Tracker 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.
4. Cliquez sur Envoyer un événement de test. Vous devriez voir une confirmation « connecté », ce qui prouve vos identifiants et la connectivité de bout en bout.

Mise en garde : les caches de page complète et les CDN peuvent répondre aux requêtes sans exécuter WordPress du tout, ce qui sous-compte les visites de robots. Si votre site est fortement mis en cache derrière Cloudflare, préférez l'installation Worker Cloudflare.

Serveur personnalisé / Node

À utiliser pour les sites codé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 plus récent (il fonctionne aussi sur Bun et Deno).

1. Sur Robots d'IA → Installer le suivi, ouvrez l'onglet Serveur personnalisé / Node et copiez l'extrait.
2. Enregistrez-le sous aeo-tracker.mjs à côté du point d'entrée de votre serveur.
3. Remplacez SITE_KEY_ID et ctk_SITE_KEY_SECRET par votre identifiant de clé et votre secret de signature. Si votre équipe préfère les variables d'environnement, lisez-les dans les deux constantes en haut du fichier ; gardez simplement le secret hors du contrôle de version.
4. Enregistrez le middleware avant vos routes :

   import { aeoCrawlerTracker } from "./aeo-tracker.mjs";
   app.use(aeoCrawlerTracker());

5. Si votre serveur est derrière un load balancer ou un reverse proxy (nginx, ALB), configurez Express pour lui faire confiance (par exemple app.set("trust proxy", 1)) afin que le middleware rapporte la vraie IP du client au lieu de celle du proxy. La vérification d'identité des robots contrôle cette IP.
6. Déployez. Le middleware rapporte après la fin de chaque réponse : il n'ajoute donc aucune latence et inclut les vrais codes de statut HTTP.

Pas sur Express ? Le handler renvoyé prend des arguments (req, res, next) simples et s'adapte à Fastify, Koa ou au serveur http de Node. Pour les autres langages (Python, Go, PHP, Ruby, ...), implémentez le protocole de beacon signé : c'est un unique POST HTTPS signé par requête correspondante.

Webflow

L'hébergement de Webflow ne peut pas exécuter de 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 :

1. Webflow prend en charge les reverse proxies autogérés sur les forfaits Enterprise ; organisez-le avec votre contact Webflow et faites passer votre domaine par votre proxy (Cloudflare, CloudFront, Fastly ou votre propre nginx).
2. 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.
3. Vérifiez comme décrit ci-dessous.

Les applications Webflow Cloud ne permettent pas de suivre tout le site : elles ne servent que les requêtes sous leur chemin de montage et ne voient donc jamais les visites de robots sur vos pages normales.

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 et ne prend pas en charge la mise en place d'un proxy (comme Cloudflare) devant une boutique. Les scripts côté navigateur ne sont pas une solution de contournement : 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 sur Hydrogen et hébergées sur Oxygen (ou toute configuration auto-hébergée) exécutent du code côté serveur ; branchez la logique de l'extrait Serveur personnalisé / Node dans le 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

• Sur Robots d'IA → Installer le suivi, le tableau des clés de site a une colonne Dernier événement. Elle se met à jour dès que votre installation livre son premier rapport accepté ; les visites de robots et les clics humains venant de réponses IA comptent tous les deux.
• Les utilisateurs WordPress peuvent confirmer la livraison immédiatement avec Envoyer un événement de test (les événements de test vérifient les identifiants et la connectivité mais ne mettent pas à jour Dernier événement).
• Laissez du temps : sur les sites à faible trafic, la première vraie visite de robot peut prendre des heures, voire quelques jours. Une fois les événements arrivés, Robots d'IA → Analytics se remplit.
• Si rien n'arrive après quelques jours, revérifiez que l'identifiant de clé et le secret de signature de votre installation correspondent à une clé active (non révoquée), et que votre route ou middleware couvre tous les chemins.