AI-crawlers

AI-crawlertracking toont welke AI-engines je site daadwerkelijk bezoeken: GPTBot, ClaudeBot, PerplexityBot, Bingbot en meer. Het vult GEO-audits aan: audits vertellen of bots een pagina kunnen bereiken; crawlertracking vertelt of ze het doen.

Waarom server-side registratie

AI-trainingscrawlers draaien geen JavaScript, dus een Google Tag Manager- of JavaScript-pixel ziet GPTBot of ClaudeBot nooit. Citlyze registreert crawlerbezoeken server-side, waar de echte request-User-Agent zichtbaar is, zodat ook niet-JavaScript-crawlers worden geteld.

De menselijke helft is anders: bezoekers die vanuit AI-antwoorden doorklikken draaien wél JavaScript, dus voor AI-verkeer volstaat een browsersnippet of Tag Manager-installatie (zie AI-verkeertracking installeren). De server-side installaties op deze pagina leggen beide soorten tegelijk vast.

Tracking installeren

Ga naar Instellingen → Koppelingen → Websitetracking en genereer een sitesleutel. De sleutel heeft twee delen, een sleutel-ID en een signeergeheim, die eenmalig worden getoond; kopieer beide. Voeg daarna het passende snippet toe voor je platform (voor klik-voor-klik-instructies bij elke optie, zie AI-crawlertracking installeren):

• Cloudflare (aanbevolen): plak het Worker-snippet vóór je site.
• Vercel / reverse proxy: voeg het middleware-snippet toe.
• WordPress: download AI Crawler Control by Citlyze, upload hem in wp-admin → Plugins en vul in de instellingen alle drie de velden in: Tracker base URL (https://app.citlyze.com), Key ID en Signing secret. Controleer de bezorging met Testgebeurtenis versturen (“Send test event”). De plugin rapporteert niets zolang de tracker-basis-URL leeg is.
• Eigen server / Node: voor zelf gehoste sites (AWS, GCP, Azure, bare metal, containers): voeg het Express-achtige middleware-snippet toe (Node 20+). Het is aan te passen aan Fastify, Koa of kaal http, en andere talen kunnen het signed-beacon-protocol direct implementeren.

De snippets voor Cloudflare, Vercel en eigen servers lezen het signeergeheim uit een omgevingsvariabele, CITLYZE_SIGNING_SECRET (bij Cloudflare een versleuteld Worker-geheim), zodat het geheim nooit in code staat die je commit of deelt. De WordPress-plugin bewaart het in zijn instellingen.

Elk event wordt met je geheim gesigneerd zodat de tracker vervalste beacons kan weigeren. Die handtekening bewijst dat de melding van jouw site kwam; ze zegt niets over wie de bezoeker was. Bevestigen dat een bezoeker echt GPTBot was is een aparte stap, beschreven in Hoe verificatie werkt.

Standaard Shopify-winkels kunnen geen server-side registratie draaien, en Shopify ondersteunt niet dat je een proxy (zoals Cloudflare) voor een winkel zet, dus volledige crawlertracking is op standaard Shopify niet beschikbaar. Headless Hydrogen- of Oxygen-storefronts draaien server-side code en kunnen het snippet voor eigen servers gebruiken. Webflow-hosting kan evenmin servercode draaien; op Webflow Enterprise kan een zelfbeheerde reverse proxy de Cloudflare-Worker of het snippet voor eigen servers op de proxylaag draaien.

Collectors melden wat er met elk verzoek gebeurde:

• De Cloudflare Worker, de middleware voor eigen servers en de WordPress-plugin sturen de exacte HTTP-status mee (200, 301, 404, 410, 500, enzovoort), waarop de fout- en redirect-inzichten hieronder draaien. Vercel-middleware draait voordat het antwoord bestaat en kan dat dus niet; gebruik voor statuscodes op Vercel de Vercel log drain onder Tracking installeren → Serverlogboeken in plaats van de middleware.
• Bij een redirect sturen dezelfde drie collectors ook het doel mee: het pad voor een pagina op je eigen site, alleen het domein voor elke andere site.
• Bij crawlerbezoeken wordt ook de querystring meegestuurd (bijvoorbeeld ?page=2). De querystring van een menselijke bezoeker verlaat je site nooit.

Events gaan in ondertekende batches. Is Citlyze even onbereikbaar, dan proberen de Cloudflare Worker en de middleware voor eigen servers het één keer opnieuw, en bewaart de WordPress-plugin niet-afgeleverde events tot een dag in je WordPress-database en blijft hij het proberen. Een nieuwe poging wordt nooit dubbel geteld. Elke geïnstalleerde collector ververst ook minstens één keer per dag zijn lijst met bekende crawlers, zodat een nieuwe crawler herkend wordt zonder de snippet of plugin bij te werken. De pagina Websitetracking laat weten wanneer er een nieuwere versie van je snippet of plugin is.

De WordPress-plugin ziet elk verzoek dat WordPress bereikt, ook verzoeken die een andere plugin doorstuurt voordat de pagina wordt opgebouwd. Wat WordPress nooit bereikt, ziet hij niet: pagina's uit een full-page cache, redirects van je webserver of CDN, en verzoeken die een firewall blokkeert voordat WordPress laadt. De instellingenpagina van de plugin meldt het wanneer hij een paginacache detecteert. Gebruik voor sterk gecachete sites de Cloudflare Worker of upload je serverlogs. Draait WordPress achter een andere proxy of load balancer dan Cloudflare, vul dan in de plugininstellingen de client-IP-header en de adressen van de proxy in, zodat crawlers op hun echte adres geverifieerd worden.

Gebruik één collector per site. Melden een websitecollector en een serverlogbron hetzelfde domein, dan wordt elk bezoek dubbel geteld; de pagina Websitetracking waarschuwt je als dat gebeurt.

Eigen servers en andere talen

Het tabblad voor eigen servers levert een Node-middleware, maar elke stack kan rapporteren: stuur ondertekende HTTPS-POST-verzoeken naar https://app.citlyze.com/api/track met een JSON-body (maximaal 256 KB) en Content-Type: application/json. Elk verzoek bevat een batch van 1 tot 50 events.

Verplichte headers:

De handtekening berekenen:

1. Leid de ondertekeningssleutel af: de 64-tekens SHA-256 in hex met kleine letters van je ondertekeningsgeheim (de volledige string ctk_...). Gebruik de UTF-8-bytes van die hexstring als HMAC-sleutel; decodeer hem niet vanuit hex.
2. Bouw het bericht: "3\n" + timestamp + "\n" + nonce + "\n" + bodyDigest, waarbij bodyDigest de SHA-256 in hex met kleine letters is van precies de bodybytes die je verstuurt. Elke herserialisatie na het ondertekenen maakt de handtekening ongeldig.
3. x-aeo-signature is de HMAC-SHA256 in hex met kleine letters van dat bericht, met de sleutel uit stap 1.

Bewaar het signeergeheim in een omgevingsvariabele of in de geheimenopslag van je platform, nooit in de broncode.

Bodyvelden:

• collector: een korte naam voor je integratie, bijvoorbeeld my-app/1.0 (letters, cijfers, ., _, / en -, tot 64 tekens).
• events: de lijst met events. Elk event heeft deze velden (verplicht, tenzij anders vermeld):
  • occurredAt: wanneer het verzoek plaatsvond, in milliseconden sinds de Unix-epoch. Events ouder dan 48 uur worden genegeerd.
  • host: de hostnaam van het verzoek zonder poort, of een lege string. Events voor een host die niet het domein van je sitesleutel of een van de subdomeinen daarvan is, worden genegeerd.
  • userAgent: de User-Agent van de bezoeker, tot 1024 tekens.
  • path: het verzoekpad met een / vooraan, zonder querystring of fragment, tot 2048 tekens.
  • query (optioneel): de querystring zonder ?, alleen voor crawlerverzoeken.
  • visitorIp: het client-IP zoals je server het ziet. Achter een load balancer of reverse proxy haal je het uit de forwarding-header die je eigen proxy zet; dit veld controleert de identiteitsverificatie van crawlers.
  • referrer: een lege string, of een https://-referrer-URL zonder query en fragment. Alleen zinvol voor menselijke bezoeken vanuit AI-antwoorden.
  • utmSource (optioneel): de waarde van utm_source, wanneer een bezoek vanuit een AI-antwoord zonder referrer binnenkomt.
  • status: de driecijferige HTTP-status van het antwoord, of unknown als je rapporteert voordat het antwoord bestaat.
  • method: de HTTP-methode in hoofdletters.
  • redirectTarget (optioneel): bij een 3xx-antwoord de Location waar het naar verwees.

Rapporteer alleen verzoeken waarvan de user agent geautomatiseerd lijkt of waarvan de referrer een AI-antwoordmachine is, en verstuur batches na het antwoord, nooit terwijl een bezoeker wacht. Mislukt een batch met een netwerkfout, een 429 of een 5xx, verstuur hem dan opnieuw met dezelfde nonce en body en een nieuwe tijdstempel: een batch die al aankwam, wordt aan zijn nonce herkend en één keer geteld. Een 429 bevat een Retry-After-header. Elke andere 4xx betekent dat de batch zelf ongeldig is; probeer hem dan niet opnieuw.

Optioneel haal je één keer per dag de actuele lijst met bekende crawlerkenmerken en AI-referrerhosts op via GET https://app.citlyze.com/api/track/registry, met je sleutel-ID in de header x-aeo-key-id. De antwoordheader x-aeo-registry-signature is de HMAC-SHA256 in hex met kleine letters van "citlyze-registry-1\n" + bodyDigest, met de sleutel uit stap 1; negeer de lijst als die niet klopt.

Om je integratie te controleren, stuur je een batch met "test": true met één event waarvan de userAgent begint met citlyze-connection-test/ en waarvan het path /citlyze-test is. Een correct ondertekende test geeft HTTP 200 terug en slaat niets op; echte batches geven 204 terug, of de bezoeken nu in je rapporten belanden of niet.

Een sleutel vernieuwen of intrekken

Als een signeergeheim gelekt kan zijn (bijvoorbeeld gecommit in een repo of gedeeld in een screenshot), gebruik dan Vernieuwen naast de sleutel. Vernieuwen geeft een nieuw geheim uit voor dezelfde sleutel: de sleutel-ID, naam, het domein en de volledige geschiedenis blijven behouden, maar het oude geheim werkt direct niet meer, dus werk CITLYZE_SIGNING_SECRET (of de plugininstelling) meteen bij met het nieuwe geheim. Intrekken is iets anders: dat schakelt de sleutel permanent uit en stopt de tracking voor die site.

De analytics lezen

De pagina Diagnosticeren → AI-crawleractiviteit → Overzicht toont, voor het gekozen tijdvak:

• koptegels: totale crawlerhits, verschillende crawlers, topcrawler en trend
• crawlerbezoeken in de tijd (dagtotalen)
• wanneer crawlers langskomen: hits per uur van de dag
• crawlertrends in de tijd (één lijn per crawler)
• per crawler-uitsplitsing met organisatie, doel, hits en trend
• meest gecrawlde pagina's (top 10, met link naar de volledige lijst)
• niet-herkende bots: bot-achtige user agents die met geen enkele bekende AI-crawler matchen, gegroepeerd onder "Onbekende bot" zodat nieuwe crawlers vroeg opvallen

Dagen en uren volgen de tijdzone van je browser: een bezoek om 21.00 uur in New York telt voor die dag, niet de volgende. De tabel per pagina gebruikt UTC-dagen.

Trends vergelijken alleen volledige dagen. Zolang vandaag nog loopt, blijft die dag buiten de vergelijking, en elke volledige dag wordt vergeleken met dezelfde dag één tijdvak eerder. Een crawler zonder bezoeken in het vorige tijdvak toont Nieuw in plaats van een percentage, en als de tracking pas na het begin van het vorige tijdvak startte, wordt nog geen trend getoond.

Gebruik de voorinstellingen (7/30/90 dagen), het aangepaste datumbereik en het crawlerfilter om de weergave te verfijnen. Werkruimtes die meer dan één site volgen krijgen ook een sitefilter. Mensen die vanuit AI-antwoorden kwamen, vind je op AI-verkeer.

Hoe verificatie werkt

Elke client kan GPTBot in zijn user agent zetten. Een user agent is dus een bewering, geen bewijs, en Citlyze behandelt dat zo: de belangrijkste crawlercijfers tellen alleen verkeer dat we onafhankelijk konden bevestigen.

Elk bezoek krijgt een van drie betrouwbaarheidsniveaus:

• Geverifieerd: we bevestigden de netwerkidentiteit van de bezoeker tegen iets dat de operator publiceert. Alleen deze tellen mee in je totalen.
• Waarschijnlijk: ondersteunende aanwijzingen, zoals je CDN dat het verzoek markeert als bekende bot, maar geen onafhankelijke bevestiging.
• Niet geverifieerd: de user agent noemde een crawler en niets sprak dat tegen, maar we konden het niet bevestigen. Apart getoond, nooit bij je totalen opgeteld.

Verificatie gebruikt wat de operator ondersteunt:

Operators die niets controleerbaars publiceren kunnen alleen niet geverifieerd bereiken. Dat is een eigenschap van de crawler, geen probleem met je installatie, en daarom bestaan er aparte weergaven in plaats van één gemengd getal.

Twee dingen om te weten:

• Agentverkeer telt apart. Tools die mensen zelf aansturen, zoals ChatGPT Agent, verschijnen onder agentactiviteit in plaats van in de crawlertotalen: één persoon die klikt is niet hetzelfde signaal als een crawler die je indexeert.
• Soms kunnen we niet controleren: de IP-lijst van een operator kan tijdelijk onbereikbaar zijn. Die bezoeken blijven niet geverifieerd in plaats van meegeteld te worden, zodat je totalen nooit iets onbevestigds bevatten.

Gecrawlde pagina's

Diagnosticeren → AI-crawleractiviteit → Gecrawlde pagina's is de volledige detailweergave: elke pagina die AI-crawlers in het gekozen tijdvak ophaalden, met zoeken, sorteren en paginering. Elke rij toont hits, aandeel in al het crawlerverkeer, trend ten opzichte van het vorige tijdvak, fouten, redirects, de topcrawler en de datum van het laatste bezoek; klap een rij open voor de verdeling per crawler en de exacte statuscodes die crawlers kregen.

Waar relevant verschijnen inzichten boven de tabel:

• Gecrawld maar nooit geciteerd: pagina's die AI-engines ophalen maar nooit citeren in je gevolgde antwoorden; kandidaten voor duidelijkere, beter citeerbare content.
• Pagina's met fouten: pagina's die crawlers een 4xx/5xx gaven. Een kapotte pagina kan niet gelezen of geciteerd worden.
• Pagina's die doorsturen: oude URL's die crawlers blijven opvragen en vanwaar ze worden doorgestuurd. Laat je interne links en sitemap naar de uiteindelijke URL's wijzen.
• Voor het eerst opgehaalde pagina's: pagina's die sinds de start van de tracking vóór dit tijdvak door geen enkele AI-crawler waren opgehaald. Nieuwe content die hier verschijnt, is door crawlers gevonden.

Statuscodes en redirects vereisen een collector die ze meldt: de Cloudflare Worker, de middleware voor eigen servers, de WordPress-plugin of serverlogs.

De tabel is als CSV te downloaden bij abonnementen met data-export.

Crawllogboek

Diagnosticeren → AI-crawleractiviteit → Crawllogboek toont elk verzoek dat geverifieerde AI-crawlers en ondertekende agents aan je site deden, dag voor dag en op volgorde, gegroepeerd in crawlsessies (de verzoeken van één crawler zonder pauze van meer dan 30 minuten). Per verzoek zie je de tijd, de pagina en de querystring, de statuscode en bij redirects waar de redirect naartoe wees en of de crawler die in dezelfde sessie volgde. Pagina's die in één sessie meer dan eens werden opgehaald, zijn gemarkeerd.

Het crawllogboek bewaart alleen verzoeken van geverifieerde crawlers en ondertekende agents, nooit andere bezoekers, en slaat nooit een IP-adres of user agent op. Waarden van queryparameters die inloggegevens of persoonsgegevens kunnen bevatten (zoals token of email) worden vervangen door redacted. Hoeveel dagen je terug kunt kijken, hangt af van je abonnement; zie Abonnementen en limieten. Het logboek van een dag is als CSV te downloaden bij abonnementen met data-export.

Data via API en MCP

Crawlerbezoeken zijn programmatisch beschikbaar zodra tracking is geïnstalleerd:

• REST: GET /api/v1/crawler-events; zie de AI Crawler Events-resource.
• MCP: de tool list_crawler_events; zie de MCP-toolsreferentie.

Beide zijn read-only en beperkt tot je werkruimte. De REST-resource filtert op crawler_id, gevolgde site en exact path; menselijke bezoeken vanuit AI-antwoorden vind je op GET /api/v1/ai-referrals.