AI-crawlertracking installeren

Deze pagina loopt elk installatiepad klik voor klik door. Wat crawlertracking meet en hoe verificatie werkt, lees je in AI-crawlers. Dezelfde installatie rapporteert ook menselijke bezoeken vanuit AI-antwoorden, dus als je deze afrondt voed je meteen AI-verkeer; browser-only opties voor die pagina staan in AI-verkeertracking installeren.

Kies de gids die past bij waar je site draait:

Voordat je begint: genereer een sitesleutel

Elke installatie heeft een sitesleutel nodig, welk platform je ook gebruikt:

1. Ga in de app naar Instellingen → Koppelingen → Websitetracking.
2. Klik op Sitesleutel genereren. Geef de sleutel een naam en, het liefst, het domein waarvoor hij gaat rapporteren; dat domein versterkt ook de verificatie van gesigneerde crawlers voor die site.
3. Kopieer beide waarden uit de bevestigingsdialoog: de sleutel-ID en het signeergeheim (het begint met ctk_). Het geheim wordt één keer getoond; raak je het kwijt, gebruik dan Vernieuwen bij de sleutel om een vervangend geheim te genereren.

Houd het signeergeheim privé: iedereen die het heeft kan vervalste verkeersmeldingen voor je site indienen. De snippets voor Cloudflare, Vercel en eigen servers lezen het uit de omgevingsvariabele CITLYZE_SIGNING_SECRET, zodat het nooit in je code staat; de WordPress-plugin bewaart het in zijn instellingen. Commit het nooit naar een repository en plak het nooit in client-side code.

Cloudflare Worker

Gebruik deze route wanneer je DNS bij Cloudflare staat en de site via de proxy loopt (de orange-cloud-schakelaar). Het is de meest complete optie: hij ziet elk verzoek aan de edge, rapporteert echte HTTP-statuscodes en werkt ongeacht wat er achter Cloudflare draait.

1. Open op Instellingen → Koppelingen → Websitetracking → Snippet installeren het tabblad Cloudflare en kopieer het snippet.
2. Vervang SITE_KEY_ID in het snippet door je sleutel-ID. Het signeergeheim hoort niet in de code; dat voeg je in stap 5 toe als Worker-geheim.
3. Ga in het Cloudflare-dashboard naar Workers & Pages → Create → Create Worker. Geef hem een naam (bijvoorbeeld ai-crawler-tracker) en klik op Deploy om de lege worker aan te maken.
4. Klik op Edit code, vervang het gegenereerde voorbeeld door je snippet en klik opnieuw op Deploy.
5. Voeg het signeergeheim toe: open in de worker Settings → Variables and Secrets → Add, kies het type Secret, noem het CITLYZE_SIGNING_SECRET, plak je signeergeheim en klik op Deploy. Cloudflare bewaart het versleuteld en het verschijnt nooit in de code van de worker.
6. Koppel de worker aan je site: open bij de worker Settings → Domains & Routes → Add → Route, kies je zone en voeg de route example.com/* toe. Wordt je site ook geserveerd op www.example.com, voeg dan een tweede route toe voor www.example.com/*.
7. Klaar: geen codewijzigingen aan je site. De worker geeft elk verzoek ongewijzigd door aan je origin en rapporteert passende bezoeken op de achtergrond.

Twee dingen om te controleren:

• De route moet alle paden dekken (/*), anders blijven crawlerbezoeken aan niet-geroutete pagina's onzichtbaar.
• Draait er al een worker op die routes, dan voert Cloudflare maar één worker per route uit; voeg de logica van het snippet samen met je bestaande worker in plaats van een tweede toe te voegen.

Vercel / Next.js-middleware

Gebruik dit voor een Next.js-app op Vercel. Hetzelfde bestand werkt ook op zelf gehost Next.js.

1. Open op Instellingen → Koppelingen → Websitetracking → Snippet installeren het tabblad Vercel / Proxy en kopieer het snippet.
2. Maak in je Next.js-repository middleware.ts aan in de projectroot (of in src/ als je app daar staat) en plak het snippet erin.
3. Vervang SITE_KEY_ID door je sleutel-ID. Het signeergeheim hoort niet in het bestand.
4. Open in je Vercel-project Settings → Environment Variables en voeg CITLYZE_SIGNING_SECRET toe met je signeergeheim voor elke omgeving die je wilt volgen. Markeer de variabele als Sensitive. Host je Next.js zelf? Zet dan dezelfde variabele in de omgeving van je server.
5. Heb je al een middleware.ts, voeg dan geen tweede bestand toe; Next.js voert er maar één uit. Kopieer het helperblok van het snippet naar je bestaande bestand, roep de rapportagelogica ervan aan aan het begin van je middlewarefunctie en zorg dat je matcher-configuratie nog steeds alle paden dekt.
6. Commit en deploy.

Let op:

• Middleware draait voordat het antwoord bestaat, dus events melden hun HTTP-status als unknown. Dat is zo bedoeld. Gebruik voor statuscodes de Vercel log drain in plaats van deze middleware (beide samen tellen elk bezoek dubbel), of de installatie via Cloudflare of een eigen server, die ook redirects melden.
• Op Vercel komt het bezoekers-IP uit een door het platform gezette header en is het betrouwbaar. Host je Next.js zelf achter je eigen proxy, zorg er dan voor dat de forwarded-IP-header die het snippet leest door jouw proxy wordt gezet en niet vanaf de client wordt doorgegeven.

WordPress-plugin

Gebruik dit voor elke WordPress-site waarop je plugins kunt installeren.

Dezelfde plugin controleert ook, gratis, welke AI-crawlers je robots.txt doorlaat en wat de rest blokkeert; zie WordPress-plugin.

1. Ga in WordPress-admin naar Plugins → Nieuwe toevoegen, zoek naar AI Crawler Control by Citlyze en klik op Nu installeren en daarna op Activeren. De plugin staat in de officiële WordPress.org-directory, dus een zip uploaden is niet nodig.

2. Liever handmatig installeren? Open op Instellingen → Koppelingen → Websitetracking → Snippet installeren het tabblad WordPress, klik op WordPress-plugin downloaden en upload de zip via Plugins → Nieuwe toevoegen → Plugin uploaden.

3. Ga naar Citlyze → Connect Citlyze en vul alle drie de velden in:

   • Tracker base URL: https://app.citlyze.com
   • Key ID: je sleutel-ID
   • Signing secret: je ctk_...-geheim De plugin rapporteert niets zolang de basis-URL leeg is.

4. Klik op Testgebeurtenis versturen (“Send test event”). Je hoort een "connected"-bevestiging te zien; dat bewijst je gegevens en de verbinding end-to-end.

5. Achter een andere proxy of load balancer dan Cloudflare? Kies onder Visitor IP behind a proxy de header die je proxy zet en vul de adressen van de proxy in, zodat crawlers op hun echte IP geverifieerd worden. Achter Cloudflare is niets nodig.

De plugin rapporteert nadat elke pagina is geserveerd, met de exacte statuscode, ook bij verzoeken die een andere plugin doorstuurt voordat de pagina wordt opgebouwd. Events wachten in je WordPress-database en worden in batches verstuurd; het scherm Connect Citlyze toont hoeveel er wachten en wanneer er voor het laatst is afgeleverd.

Let op: pagina's uit een full-page cache, redirects van je webserver of CDN en verzoeken die een firewall blokkeert voordat WordPress laadt, bereiken de plugin nooit. Het scherm Connect Citlyze meldt het wanneer het een paginacache detecteert. Is je site sterk gecachet, kies dan liever de installatie via de Cloudflare Worker of upload je serverlogs.

Eigen server / Node

Gebruik dit voor zelfgebouwde sites die je zelf host: AWS, Google Cloud, Azure, een VPS of containers. Het snippet is een Express-achtige middleware voor Node 20 of nieuwer (hij draait ook op Bun en Deno).

1. Open op Instellingen → Koppelingen → Websitetracking → Snippet installeren het tabblad Eigen server / Node en kopieer het snippet.
2. Sla het op als aeo-tracker.mjs naast het entrypoint van je server.
3. Vervang SITE_KEY_ID door je sleutel-ID en zet op de server de omgevingsvariabele CITLYZE_SIGNING_SECRET op je signeergeheim: in de geheimeninstellingen van je host, of in een .env-bestand dat nooit wordt gecommit. Het geheim hoort nooit in het bestand zelf.
4. Registreer de middleware vóór je routes:

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

5. Staat je server achter een load balancer of reverse proxy (nginx, ALB), configureer Express dan om die te vertrouwen (bijvoorbeeld app.set("trust proxy", 1)), zodat de middleware het echte client-IP rapporteert in plaats van dat van de proxy. De verificatie van de crawleridentiteit controleert dat IP.
6. Deploy. De middleware rapporteert nadat elk antwoord is afgerond, voegt dus geen latency toe en levert echte HTTP-statuscodes mee.

Geen Express? De teruggegeven handler neemt gewone (req, res, next) argumenten en past zich aan Fastify, Koa of de http-server van Node aan. Voor heel andere talen (Python, Go, PHP, Ruby, ...) implementeer je het ondertekende beaconprotocol; elke ondertekende HTTPS-POST bevat een batch van maximaal 50 passende verzoeken.

Webflow

Webflows eigen hosting kan geen server-side code draaien, en browser-side scripts zien AI-trainingscrawlers niet; tracking wordt daarom geïnstalleerd op een proxylaag vóór Webflow:

1. Webflow ondersteunt zelfbeheerde reverse proxy's op Enterprise-abonnementen; regel dit met je Webflow-contactpersoon en leid je domein via je proxy (Cloudflare, CloudFront, Fastly of je eigen nginx).
2. Installeer de tracker op die proxylaag:
   • Proxy op Cloudflare → volg de gids Cloudflare Worker.
   • Je eigen Node-proxy → volg de gids Eigen server / Node.
   • Al het andere → implementeer het signed-beacon-protocol in je proxy.
3. Controleer je installatie zoals hieronder beschreven.

Webflow Cloud-apps zijn geen route naar tracking voor de hele site: ze bedienen alleen verzoeken onder hun mount-pad en zien dus nooit crawlerbezoeken aan je gewone pagina's.

Shopify

Standaard Shopify-winkels kunnen deze tracker niet draaien: Shopify laat merchants geen server-side code uitvoeren op storefront-verzoeken en ondersteunt niet dat je een proxy (zoals Cloudflare) voor een winkel zet. Browser-side scripts zijn geen uitweg: AI-trainingscrawlers voeren nooit JavaScript uit, en een browserscript zou je signeergeheim blootstellen.

Wat je wel kunt doen:

• Headless storefronts gebouwd op Hydrogen en gehost op Oxygen (of elke zelf gehoste setup) draaien server-side code; sluit de logica van het snippet voor Eigen server / Node aan in de server-request-handler van je storefront.
• Voor standaardwinkels werken je andere Citlyze-metingen (prompttracking, citaties, GEO-audits) gewoon, waar de winkel ook wordt gehost.

Je installatie controleren

• Op Instellingen → Koppelingen → Websitetracking heeft de sitesleuteltabel een kolom Laatste gebeurtenis. Die wordt bijgewerkt zodra je installatie de eerste geaccepteerde melding aflevert; crawlerbezoeken en AI-referral-kliks tellen allebei.
• WordPress-gebruikers kunnen de aflevering meteen bevestigen met Testgebeurtenis versturen (testevents verifiëren gegevens en verbinding, maar werken Laatste gebeurtenis niet bij).
• Geef het even de tijd: op sites met weinig verkeer kan het eerste echte crawlerbezoek uren of een paar dagen duren. Zodra events binnenkomen, vult Diagnosticeren → AI-crawleractiviteit → Overzicht zich.
• Komt er na een paar dagen niets binnen, controleer dan opnieuw of de sleutel-ID in je snippet (of in de plugininstellingen) bij een actieve, niet-ingetrokken sleutel hoort, of CITLYZE_SIGNING_SECRET het huidige signeergeheim van die sleutel bevat, en of je route of middleware alle paden dekt. Zonder geldig geheim meldt het snippet niets en logt het één keer "Citlyze crawler tracking is off".
• De tabel met sitesleutels toont ook welke collectorversie met elke sleutel rapporteert, en meldt wanneer er een nieuwere snippet- of pluginversie is, of wanneer de WordPress-plugin een paginacache heeft gedetecteerd.