Traffic-Daten über die Server API senden

Mit der Server API meldet Ihr Webserver jeden Seitenaufruf per HTTP POST an KI Score. Daraus erkennt Traffic Overview, welche KI-Crawler Ihre Website abrufen und welche Besuche aus KI-Quellen wie ChatGPT kommen. Dieser Artikel zeigt, was Sie senden und wie Sie prüfen, ob die Daten ankommen.

Voraussetzungen

• Ihre Website ist in KI Score angelegt.
• Sie oder Ihr Entwicklungsteam können serverseitigen Code ändern, etwa über eine Middleware oder einen Request-Hook. Die Integrationsseite nennt als Beispiele WordPress, Next.js, Laravel, Symfony und individuelle Systeme. Für WordPress und Next.js 16 gibt es dort eigene Anleitungen mit kopierbarem Code. Für alle anderen Systeme programmieren Sie die Anbindung selbst.
• Die Meldung muss vom Server kommen. Ein JavaScript-Snippet für den Browser bietet KI Score nicht an.

Endpoint und Tracking-Schlüssel kopieren

1. Wählen Sie in der Sidebar die gewünschte Website aus.
2. Öffnen Sie Einstellungen → Traffic-Tracking.
3. Klicken Sie unter Verfügbare Integrationen auf die Karte Server API. Die Anleitung öffnet sich als Fenster.
4. Kopieren Sie Dein Tracking-Endpoint mit Kopieren.
5. Kopieren Sie das Universelles cURL-Beispiel mit Kopieren. Es enthält bereits Ihren Tracking-Schlüssel.

Übernehmen Sie den Endpoint immer von dieser Seite, statt eine URL fest in Ihren Code zu schreiben. Er endet mit der Site-ID Ihrer Website, einer Kennung aus 32 Hex-Zeichen.

Jede Meldung muss den Tracking-Schlüssel im Header X-Kiscore-Tracking-Secret mitsenden. Fehlt er oder ist er falsch, antwortet KI Score mit dem Status 401. Der Schlüssel wird aus der Site-ID abgeleitet und lässt sich im Dashboard nicht neu erzeugen. Behandeln Sie ihn deshalb wie ein Passwort und verwenden Sie ihn nur in serverseitigem Code. Falls er doch öffentlich geworden ist, wenden Sie sich an support@kiscore.ai.

Hinweis: Die Integrationsseite zeigt auch Karten für Nuxt, TYPO3, WordPress und Next.js. Was dazu gilt, lesen Sie im Artikel Gibt es Plugins für Nuxt und TYPO3?.

Welche Daten Sie senden

Senden Sie für jeden Seitenaufruf einen JSON-Body mit den Werten des echten Requests Ihres Besuchers:

POST <Dein Tracking-Endpoint>
Content-Type: application/json
X-Kiscore-Tracking-Secret: <Ihr Tracking-Schlüssel>

{
  "user_agent": "<User-Agent des Requests>",
  "referer": "<Referrer des Requests>",
  "url": "<vollständige URL samt Query-String>",
  "ip": "<IP-Adresse des Requests>",
  "title": "<Seitentitel>"
}

• user_agent, referer, url und ip stammen aus dem eingehenden Request.
• url muss vollständig sein, einschließlich Query-String. Sonst fehlt die Zuordnung über Parameter wie utm_source=chatgpt.com.
• title ist optional.
• Ebenfalls optional sind session_id sowie utm_source, utm_medium, utm_campaign, utm_term und utm_content. Senden Sie keine eigenen UTM-Felder, liest KI Score die UTM-Parameter aus der URL.

Ist ein Feld zu lang, lehnt KI Score die Meldung mit dem Status 413 ab. Die Grenzen liegen bei 1.024 Byte für user_agent, 2.048 Byte für referer und url, 64 Byte für ip, 512 Byte für title und 255 Byte für session_id und jedes UTM-Feld.

KI Score speichert nur erkannte KI-Crawler und Besuche, die über eine KI-Quelle kommen. Von Besuchern speichert KI Score keine IP-Adresse. Als Betreiber der Website informieren Sie Ihre Besucher selbst über dieses Tracking. Unter Umständen brauchen Sie dafür eine Vereinbarung zur Auftragsverarbeitung.

Asynchron senden, ohne Ihre Seite zu bremsen

Senden Sie die Meldung so, dass die Antwort Ihrer Website nicht auf KI Score wartet, zum Beispiel über einen Hintergrund-Job oder eine Warteschlange. Setzen Sie ein kurzes Timeout und lassen Sie Ihre Seite auch dann normal ausliefern, wenn die Meldung fehlschlägt.

Für Meldungen gelten zwei Limits: 120 Anfragen pro Minute je absendender IP-Adresse und 600 Anfragen pro Minute je Website. Da alle Meldungen von Ihrem Server kommen, zählt das IP-Limit für Ihren Server insgesamt. Wird ein Limit überschritten, antwortet KI Score mit dem Status 429.

Prüfen, ob Daten ankommen

Eine angenommene Meldung beantwortet KI Score mit {"status": "ok", "tracked": …}. tracked ist true, wenn KI Score in diesem Aufruf einen KI-Crawler erkannt hat. Bei einem gewöhnlichen Seitenaufruf steht dort false, auch wenn der Besuch als KI-Verweis gezählt wird. Das ist kein Fehler.

1. Öffnen Sie in der Sidebar KI-Traffic → Traffic Overview.
2. Öffnen Sie den Tab KI-Crawler. Nach dem nächsten Abruf durch einen KI-Crawler erscheint er hier.
3. Öffnen Sie den Tab KI-Verweise. Hier erscheinen Besuche aus ChatGPT, Perplexity und anderen KI-Quellen.

Solange noch nie ein Ereignis gespeichert wurde, zeigt Traffic Overview stattdessen den Hinweis „Noch keine Traffic-Daten eingegangen“. Bleiben beide Tabs leer, prüfen Sie den gewählten Zeitraum und die Statuscodes Ihrer Meldungen.