citlyze docs
Utiliser Citlyze

Robots d'IA

Découvrez quels robots d'IA visitent réellement votre site, et comment installer le suivi.

Le suivi des robots d'IA montre quels moteurs IA visitent réellement votre site : GPTBot, ClaudeBot, PerplexityBot, Bingbot et d'autres. Il complète les audits GEO : les audits indiquent si les bots peuvent atteindre une page ; le suivi des robots montre s'ils le font vraiment.

Pourquoi une capture côté serveur

Les robots d'entraînement IA n'exécutent pas JavaScript : un pixel Google Tag Manager ou JavaScript ne voit donc jamais GPTBot ni ClaudeBot. Citlyze capture les visites côté serveur, là où le véritable User-Agent de la requête est visible : même les robots qui n'exécutent pas JavaScript sont ainsi comptés.

Pour les visiteurs humains, c'est différent : ceux qui arrivent depuis une réponse IA exécutent JavaScript. Pour le Trafic IA, un extrait de code dans le navigateur ou une installation via Tag Manager suffit donc (voir Installer le suivi du trafic IA). Les installations côté serveur décrites sur cette page capturent les deux types de visites à la fois.

Installer le suivi

Allez dans Paramètres → Connexions → Suivi du site web et générez une clé de site. La clé comporte deux éléments, un identifiant de clé et un secret de signature, affichés une seule fois : copiez-les tous les deux. Ajoutez ensuite l'extrait correspondant à votre plateforme (pour un guide pas à pas de chaque option, voir Installer le suivi des robots d'IA) :

  • Cloudflare (recommandé) : déployez l'extrait Worker devant votre site.
  • Vercel / reverse proxy : ajoutez l'extrait middleware.
  • WordPress : téléchargez l'extension AI Crawler Control by Citlyze, téléversez-la dans wp-admin → Extensions, puis remplissez les trois champs de ses réglages : Tracker base URL (https://app.citlyze.com), Key ID et Signing secret. Utilisez Envoyer un événement de test (« Send test event ») pour vérifier que les événements arrivent bien. L'extension n'envoie rien tant que l'URL de base du tracker n'est pas renseignée.
  • Serveur personnalisé / Node : pour les sites auto-hébergés (AWS, GCP, Azure, serveurs physiques, conteneurs), ajoutez l'extrait middleware de style Express (Node 20+). Il s'adapte à Fastify, Koa ou au module http natif, et les autres langages peuvent implémenter directement le protocole de beacon signé.

Les extraits Cloudflare, Vercel et serveur personnalisé lisent le secret de signature dans une variable d'environnement, CITLYZE_SIGNING_SECRET (un secret chiffré du Worker sur Cloudflare) : le secret ne figure donc jamais dans du code que vous versionnez ou partagez. L'extension WordPress le conserve quant à elle dans ses réglages.

Chaque événement est signé avec votre secret, ce qui permet au tracker de rejeter les beacons falsifiés.

Cette signature prouve que l'événement vient bien de votre site ; elle ne dit rien de l'identité du visiteur. Confirmer qu'un visiteur était réellement GPTBot est une étape distincte, décrite dans Comment fonctionne la vérification.

Les boutiques Shopify standard ne peuvent pas exécuter de capture côté serveur, et Shopify ne permet pas de placer un proxy (comme Cloudflare) devant une boutique : le suivi complet des robots n'est donc pas disponible sur Shopify standard. Les vitrines headless Hydrogen ou Oxygen exécutent du code côté serveur et peuvent utiliser l'extrait serveur personnalisé. L'hébergement Webflow ne permet pas non plus d'exécuter du code serveur ; avec Webflow Enterprise, un reverse proxy que vous gérez vous-même peut exécuter le Worker Cloudflare ou l'extrait serveur personnalisé au niveau du proxy.

Les collecteurs indiquent ce qu'il est advenu de chaque requête :

  • Le Worker Cloudflare, le middleware serveur personnalisé et l'extension WordPress envoient le statut HTTP exact (200, 301, 404, 410, 500, etc.), qui alimente les analyses d'erreurs et de redirections décrites plus bas. Le middleware Vercel s'exécute avant que la réponse soit générée : il ne peut donc pas l'envoyer. Pour obtenir les codes de statut sur Vercel, utilisez le log drain Vercel, dans Suivi du site web → Logs serveur, à la place du middleware.
  • Pour une redirection, ces trois mêmes collecteurs envoient aussi sa destination : le chemin s'il s'agit d'une page de votre site, uniquement le domaine pour tout autre site.
  • Pour les visites de robots, la query string est aussi envoyée (par exemple ?page=2). La query string d'un visiteur humain ne quitte jamais votre site.

Les événements sont envoyés par lots signés. Si Citlyze est brièvement injoignable, le Worker Cloudflare et le middleware serveur personnalisé réessaient une fois, et l'extension WordPress conserve les événements non transmis dans votre base de données WordPress pendant un jour au maximum, en continuant de réessayer. Un renvoi n'est jamais compté deux fois. Chaque collecteur installé met aussi à jour sa liste de robots connus au moins une fois par jour : un robot qui vient d'apparaître est donc reconnu sans mise à jour de l'extrait ou de l'extension. La page Suivi du site web vous signale lorsqu'une version plus récente de votre extrait ou de votre extension est disponible.

L'extension WordPress voit toutes les requêtes qui atteignent WordPress, y compris celles qu'une autre extension redirige avant l'affichage de la page. Elle ne voit pas ce qui n'atteint jamais WordPress : 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. La page de réglages de l'extension vous signale lorsqu'elle détecte un cache de pages. Pour les sites fortement mis en cache, utilisez le Worker Cloudflare ou importez les logs de votre serveur. Si WordPress tourne derrière un proxy ou un répartiteur de charge autre que Cloudflare, indiquez dans les réglages de l'extension l'en-tête d'IP client et les adresses du proxy, afin que les robots soient vérifiés à partir de leur adresse réelle.

Utilisez un seul collecteur par site. Si un collecteur de site web et une source de logs serveur remontent le même domaine, chaque visite est comptée deux fois ; la page Suivi du site web vous prévient dans ce cas.

Serveurs personnalisés et autres langages

L'onglet serveur personnalisé fournit un middleware Node, mais n'importe quelle stack peut envoyer des événements : envoyez des requêtes POST HTTPS signées vers https://app.citlyze.com/api/track avec un corps JSON (256 Ko au maximum) et Content-Type: application/json. Chaque requête contient un lot de 1 à 50 événements.

En-têtes requis :

En-têteValeur
x-aeo-schemaLa chaîne littérale 3.
x-aeo-key-idVotre ID de clé (l'UUID affiché lors de la génération de la clé de site).
x-aeo-tsHorodatage Unix en secondes ; il ne doit pas s'écarter de plus de 5 minutes de l'horloge du tracker.
x-aeo-nonceUnique pour chaque lot : 16 à 64 caractères, chiffres hexadécimaux et tirets. Un UUID dont on a retiré les tirets convient.
x-aeo-signatureHMAC en hexadécimal minuscule, calculé comme indiqué ci-dessous.

Calcul de la signature :

  1. Dérivez la clé de signature : le SHA-256 de votre secret de signature (la chaîne ctk_... complète), en hexadécimal minuscule sur 64 caractères. Utilisez les octets UTF-8 de cette chaîne hexadécimale comme clé HMAC ; ne la décodez pas depuis l'hexadécimal.
  2. Construisez le message : "3\n" + timestamp + "\n" + nonce + "\n" + bodyDigest, où bodyDigest est le SHA-256, en hexadécimal minuscule, des octets exacts du corps envoyé. Toute resérialisation du corps après la signature rend celle-ci invalide.
  3. x-aeo-signature est le HMAC-SHA256, en hexadécimal minuscule, de ce message, calculé avec la clé de signature de l'étape 1.

Conservez le secret de signature dans une variable d'environnement ou dans le gestionnaire de secrets de votre plateforme, jamais dans le code source.

Champs du corps :

  • collector : un nom court pour votre intégration, par exemple my-app/1.0 (lettres, chiffres, ., _, / et -, 64 caractères au maximum).
  • events : la liste des événements. Chaque événement comporte les champs suivants (obligatoires sauf mention contraire) :
    • occurredAt : le moment de la requête, en millisecondes depuis l'epoch Unix. Les événements de plus de 48 heures sont ignorés.
    • host : le nom d'hôte de la requête sans le port, ou une chaîne vide. Les événements dont l'hôte n'est ni le domaine de votre clé de site ni l'un de ses sous-domaines sont ignorés.
    • userAgent : le User-Agent du visiteur, 1024 caractères au maximum.
    • path : le chemin de la requête, commençant par /, sans query string ni fragment, 2048 caractères au maximum.
    • query (facultatif) : la query string sans le ?, uniquement pour les requêtes de robots.
    • visitorIp : l'IP du client telle que votre serveur la voit. Derrière un répartiteur de charge ou un reverse proxy, prenez-la dans l'en-tête de transfert défini par votre propre proxy ; c'est sur ce champ que porte la vérification de l'identité des robots.
    • referrer : une chaîne vide, ou une URL référente en https://, sans query ni fragment. Utile uniquement pour les visites humaines arrivant depuis des réponses IA.
    • utmSource (facultatif) : la valeur de utm_source, lorsqu'une visite issue d'une réponse IA arrive sans référent.
    • status : le statut HTTP à trois chiffres de la réponse, ou unknown si vous envoyez l'événement avant que la réponse existe.
    • method : la méthode HTTP, en majuscules.
    • redirectTarget (facultatif) : pour une réponse 3xx, le Location vers lequel elle redirigeait.

N'envoyez que les requêtes dont le user agent semble automatisé ou dont le référent est un moteur de réponse IA, et envoyez les lots après la réponse, jamais pendant qu'un visiteur attend. Si un lot échoue avec une erreur réseau, un 429 ou un 5xx, renvoyez-le avec le même nonce et le même corps et un nouvel horodatage : un lot déjà arrivé est reconnu grâce à son nonce et n'est compté qu'une fois. Une réponse 429 comporte un en-tête Retry-After. Tout autre 4xx signifie que le lot lui-même n'est pas valide : ne le renvoyez pas.

Si vous le souhaitez, récupérez une fois par jour la liste à jour des identifiants de robots connus et des hôtes référents IA sur GET https://app.citlyze.com/api/track/registry, avec votre ID de clé dans l'en-tête x-aeo-key-id. L'en-tête de réponse x-aeo-registry-signature contient le HMAC-SHA256, en hexadécimal minuscule, de "citlyze-registry-1\n" + bodyDigest, calculé avec la clé de signature de l'étape 1 ; ignorez la liste si la signature ne correspond pas.

Pour tester votre intégration, envoyez un lot avec "test": true contenant un seul événement dont le userAgent commence par citlyze-connection-test/ et dont le path est /citlyze-test. Un test correctement signé renvoie HTTP 200 et n'enregistre rien ; les vrais lots renvoient 204, que les visites apparaissent ou non dans vos rapports.

Renouveler ou révoquer une clé

Si un secret de signature a pu fuiter (par exemple s'il a été versionné dans un dépôt ou partagé dans une capture d'écran), utilisez Renouveler à côté de la clé. Le renouvellement génère un nouveau secret pour la même clé : l'identifiant, le nom, le domaine et tout l'historique enregistré sont conservés, mais l'ancien secret cesse immédiatement de fonctionner. Mettez donc à jour sans attendre CITLYZE_SIGNING_SECRET (ou le réglage de l'extension) avec le nouveau secret. Révoquer est différent : la clé est désactivée définitivement et le suivi de ce site s'arrête.

Lire les statistiques

La page Diagnostiquer → Activité des robots d'IA → Vue d'ensemble affiche, pour la période sélectionnée :

  • des vignettes de synthèse : nombre total de visites de robots, robots distincts, robot le plus actif et tendance
  • les visites de robots dans le temps (totaux quotidiens)
  • les heures de passage des robots : visites par heure de la journée
  • l'évolution par robot (une courbe par robot)
  • le détail par robot : organisation, finalité, visites et tendance
  • les pages les plus explorées (top 10, avec un lien vers la liste complète)
  • les bots non reconnus : des user agents de type bot qui ne correspondent à aucun robot IA connu, regroupés sous « Bot inconnu » pour repérer rapidement les nouveaux robots

Les jours et les heures suivent le fuseau horaire de votre navigateur : une visite à 21 h à New York compte pour ce jour-là, pas pour le lendemain. Le tableau par page utilise des jours UTC.

Les tendances ne comparent que des jours complets. Tant que la journée en cours n'est pas terminée, elle est exclue de la comparaison, et chaque jour complet est comparé au jour correspondant de la période précédente. Un robot sans visite sur la période précédente affiche Nouveau au lieu d'un pourcentage, et si le suivi a commencé après le début de la période précédente, aucune tendance n'est encore affichée.

Utilisez les périodes prédéfinies (7/30/90 jours), la plage de dates personnalisée et le filtre par robot pour affiner l'affichage. Les espaces de travail qui suivent plusieurs sites disposent aussi d'un filtre par site. Les visiteurs arrivés depuis des réponses IA sont traités dans la page Trafic IA.

Comment fonctionne la vérification

N'importe quel client peut écrire GPTBot dans son user agent. Un user agent est donc une simple déclaration, pas une preuve, et Citlyze le traite comme tel : les chiffres principaux ne comptent que le trafic que nous avons pu confirmer de façon indépendante.

Chaque visite reçoit l'un de ces trois niveaux de confiance :

  • Vérifié : nous avons confirmé l'identité réseau du visiteur à partir d'informations publiées par l'opérateur. Seules ces visites sont comptées dans vos totaux de robots.
  • Probable : des indices concordants, par exemple votre CDN qui signale la requête comme provenant d'un bot connu, mais sans confirmation indépendante.
  • Non vérifié : le user agent indique un robot et rien ne le contredit, mais nous n'avons pas pu le confirmer. Ces visites sont affichées à part, jamais ajoutées à vos totaux.

La vérification utilise les méthodes que l'opérateur prend en charge :

MéthodeCe qu'elle prouve
Requête signéeLa requête portait une signature cryptographique, vérifiée à l'aide des clés publiées par l'opérateur. C'est la preuve la plus solide qui soit.
Plage d'IP publiéeL'adresse source appartient à une plage que l'opérateur publie pour ses robots.
DNS inverséL'adresse source renvoie au domaine de l'opérateur, et ce nom renvoie à son tour à la même adresse.
Plage d'IP connueL'adresse source appartient à une plage fixe documentée par l'opérateur.
Attestation du CDNVotre CDN a identifié la requête comme provenant d'un bot connu. Un indice, pas une preuve.
User agent seulRien d'autre que le nom déclaré par le visiteur. Toujours non vérifié.

Les opérateurs qui ne publient aucune information vérifiable ne peuvent jamais dépasser le niveau non vérifié. C'est une caractéristique du robot, pas un problème de votre installation, et c'est pourquoi les vues sont séparées plutôt que fondues en un seul chiffre.

Deux points à retenir :

  • Le trafic des agents est compté à part. Les outils pilotés par des personnes, comme ChatGPT Agent, apparaissent dans l'activité des agents et non dans les totaux de robots : une personne qui clique n'est pas le même signal qu'un robot qui indexe votre site.
  • Il arrive qu'une vérification soit impossible : la liste d'IP d'un opérateur peut être temporairement inaccessible. Ces visites restent non vérifiées au lieu d'être comptées : vos totaux n'incluent donc jamais rien qui n'ait été confirmé.

Pages explorées

Diagnostiquer → Activité des robots d'IA → Pages explorées offre la vue détaillée complète : toutes les pages récupérées par des robots d'IA sur la période sélectionnée, avec recherche, tri et pagination. Chaque ligne affiche le nombre de visites, la part du trafic total des robots, la tendance par rapport à la période précédente, les erreurs, les redirections, le robot le plus actif et la date de dernière visite ; dépliez une ligne pour voir la répartition par robot et les codes de statut exacts reçus par les robots.

Des analyses apparaissent au-dessus du tableau lorsqu'elles sont pertinentes :

  • Explorées mais jamais citées : des pages que les moteurs IA récupèrent mais ne citent jamais dans vos réponses suivies ; elles gagneraient à avoir un contenu plus clair et plus facile à citer.
  • Pages en erreur : des pages qui ont répondu aux robots par une erreur 4xx/5xx. Une page cassée ne peut être ni lue ni citée.
  • Pages qui redirigent : d'anciennes URL que les robots continuent de demander et qui les redirigent ailleurs. Faites pointer vos liens internes et votre sitemap vers les URL finales.
  • Pages récupérées pour la première fois : des pages qu'aucun robot d'IA n'avait récupérées avant cette période depuis le début du suivi. Un nouveau contenu qui apparaît ici a été découvert par les robots.

Les codes de statut et les redirections nécessitent un collecteur qui les transmet : le Worker Cloudflare, le middleware serveur personnalisé, l'extension WordPress ou les logs serveur.

Le tableau peut être téléchargé au format CSV avec les forfaits qui incluent l'export de données.

Journal d’exploration

Diagnostiquer → Activité des robots d'IA → Journal d’exploration liste, jour par jour et dans l'ordre chronologique, toutes les requêtes que les robots d'IA vérifiés et les agents signés ont adressées à votre site, regroupées en sessions d'exploration (les requêtes d'un même robot sans interruption de plus de 30 minutes). Pour chaque requête, vous voyez l'heure, la page et sa query string, le code de statut et, pour les redirections, leur destination et si le robot l'a suivie au cours de la même session. Les pages récupérées plusieurs fois au cours d'une session sont signalées.

Le journal d’exploration ne conserve que les requêtes des robots vérifiés et des agents signés, jamais celles des autres visiteurs, et n'enregistre jamais d'adresse IP ni de user agent. Les valeurs des paramètres de requête susceptibles de contenir des identifiants ou des données personnelles (comme token ou email) sont remplacées par redacted. Le nombre de jours consultables dépend de votre forfait ; voir Forfaits et limites. Le journal d'une journée peut être téléchargé en CSV avec les forfaits qui incluent l'export de données.

Accéder aux données via l'API et MCP

Une fois le suivi installé, les visites de robots sont accessibles par programmation :

Les deux sont en lecture seule et limités à votre espace de travail. La ressource REST permet de filtrer par crawler_id, par site suivi et par path exact ; les visites humaines issues des réponses IA sont disponibles via GET /api/v1/ai-referrals.

Sur cette page