citlyze docs
Citlyze gebruiken

AI-crawlertracking installeren

Stapsgewijze installatiegidsen voor Cloudflare, Vercel, WordPress, eigen Node-servers, Webflow en Shopify.

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 die afrondt, vul je meteen ook AI-verkeer; opties voor die pagina die alleen in de browser werken, staan in AI-verkeertracking installeren.

Kies de gids die past bij waar je site draait:

Jouw situatieGebruik deze gids
Site zit achter Cloudflare (orange-cloud-proxy)Cloudflare Worker
Next.js-app op Vercel (of zelf gehost Next.js)Vercel / Next.js-middleware
WordPress-siteWordPress-plugin
Zelfgebouwde site op eigen servers (AWS, GCP, Azure, VPS, containers)Eigen server / Node
Webflow-siteWebflow
Shopify-winkelShopify

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 ondertekende crawlers voor die site.
  3. Kopieer beide waarden uit de bevestigingsdialoog: de sleutel-ID en het ondertekeningsgeheim (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 ondertekeningsgeheim 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 ondertekeningsgeheim 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 ondertekeningsgeheim toe: open in de worker Settings → Variables and Secrets → Add, kies het type Secret, noem het CITLYZE_SIGNING_SECRET, plak je ondertekeningsgeheim 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 meldt relevante 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 ondertekeningsgeheim hoort niet in het bestand.
  4. Open in je Vercel-project Settings → Environment Variables en voeg CITLYZE_SIGNING_SECRET toe met je ondertekeningsgeheim 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 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 verzenden (“Send test event”). Je ziet dan een bevestiging "connected"; daarmee weet je dat je gegevens kloppen en dat de verbinding van begin tot eind werkt.

  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 ondertekeningsgeheim: 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 pas nadat elk antwoord is afgerond, vertraagt je site dus niet en stuurt echte HTTP-statuscodes mee.

Geen Express? De handler die je terugkrijgt, werkt met gewone (req, res, next)-argumenten en is aan te passen voor Fastify, Koa of de http-server van Node. Voor heel andere talen (Python, Go, PHP, Ruby, ...) implementeer je het protocol met ondertekende beacons; 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:
  3. Controleer je installatie zoals hieronder beschreven.

Met Webflow Cloud-apps kun je niet de hele site volgen: ze verwerken alleen verzoeken onder hun eigen pad en zien dus nooit crawlerbezoeken aan je gewone pagina's.

Shopify

Standaard Shopify-winkels kunnen deze tracker niet draaien: Shopify laat winkeliers 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 ondertekeningsgeheim prijsgeven.

Wat je wel kunt doen:

  • Headless storefronts gebouwd op Hydrogen en gehost op Oxygen (of elke zelf gehoste setup) draaien server-side code; verwerk de logica van het snippet voor Eigen server / Node in de handler die de serververzoeken van je storefront afhandelt.
  • Voor standaardwinkels werken je andere metingen in Citlyze (prompttracking, bronvermeldingen, 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 klikken vanuit AI-antwoorden tellen allebei mee.
  • WordPress-gebruikers kunnen de aflevering meteen bevestigen met Testgebeurtenis verzenden (testevents controleren je gegevens en de 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 ondertekeningsgeheim 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.

Op deze pagina