Wie die Messung funktioniert

Dokumentationsanalysen liegen gewöhnlich auf dieselben vier Arten: Crawler werden als Leser gezählt, im Hintergrund geöffnete Tabs als Lesevorgänge, die eigenen Besuche des Betreibers als Publikum und Prozentsätze werden auf Grundlage einer Handvoll Besuche angegeben. Auf dieser Seite wird der Mechanismus dargelegt, damit Sie jeden dieser Punkte selbst überprüfen können, bevor Sie aufgrund einer Zahl handeln.

Was Sie erhalten#

Jede Kennzahl im Docsbook-Analysebereich wird aus einem einzigen Ereignisstrom abgeleitet, unter einer einheitlichen Definition eines Besuchs und einer einheitlichen Definition eines Menschen – nicht aus einer Reihe unabhängiger Zähler, die sich widersprechen können. Wenn eine Zahl nicht ehrlich angegeben werden kann, erhalten Sie einen Gedankenstrich, die Kennzeichnung „nicht gemessen“ oder einen ausgeblendeten Prozentsatz, niemals ein selbstsicheres 0. Und in den Browsern Ihrer Leser wird nichts gespeichert, um irgendetwas davon zu erzeugen.

Was erfasst wird und was bewusst nicht#

Docsbook erfasst 36 benannte docs.*-Ereignisse auf Ihrer Dokumentationswebsite — Seitenaufrufe, Lesezeitsegmente, Überschriften, die in den sichtbaren Bereich gescrollt werden, Suchvorgänge, KI-Chat- Aktionen, Kopiervorgänge, Navigationsklicks, Klicks auf externe Links, Feedback-Abstimmungen und das Verlassen der Seite. Die vollständige Liste finden Sie in der Referenz der erfassten Ereignisse.

Jedes Ereignis enthält das zugehörige Projekt, den Seitenpfad und alle jeweils zutreffenden Informationen: Sekunden, Überschriftenanker, Referrer, Zielhost, Sprache, User-Agent sowie das Land/die Region/die Stadt/die Koordinaten, die der Edge aus der Anfrage ermittelt hat. Die IP-Adresse des Lesers wird serverseitig am Erfassungsendpunkt angehängt, niemals durch den Browser.

Wie ein Besucher und ein Besuch definiert werden#

Ein Besucher ist sha256(secret salt + project + IP), gekürzt auf 16 hexadezimale Zeichen. Das ist die gesamte Identität. Sie bleibt stabil – dieselbe Person erhält nächste Woche dieselbe Kennung – und ist abgegrenzt: Das Salt ist ein serverseitiges Geheimnis und der Projektname ist Teil der Eingabe, sodass die ID nicht mit dem Datenverkehr einer anderen Website verknüpft werden kann, auch nicht mit dem eines anderen Docsbook-Projekts.

Ein Besuch wird aus den Ereignissen rekonstruiert und nicht mit einem Sitzungs- Cookie verfolgt. Die Ereignisse eines Besuchers werden nach der Zeit sortiert und überall dort getrennt, wo eine Lücke von mehr als 30 Minuten besteht. Das ist absichtlich eine Inaktivitätslücke und kein festes Zeitfenster: Die Gruppierung in Zeitfenster würde einen Besuch, der eine Grenze überschreitet, aufteilen, sodass ein von 12:29 bis 12:31 aktiver Leser andernfalls als zwei Besuche erfasst würde.

Wie Bots und Crawler gefiltert werden#

Die Filterung erfolgt in zwei unabhängigen Ebenen, weil bekannt ist, dass jede einzelne für sich allein versagt.

1. User-Agent. Ein regulärer Ausdruck, der Crawler, Spider, Headless-Browser, skriptgesteuerte HTTP-Clients, SEO-Suiten und Fetcher für Linkvorschauen sowie jeden KI-Bot in der Tabelle des Klassifikators abdeckt. Zwei wörtliche UA-Strings sind fest verankert, weil beobachtet wurde, dass sie in großer Zahl crawlen und dabei vorgaben, gewöhnliche Telefone zu sein — ein Googlebot-Smartphone-Referenzgerät und ein veralteter iOS-Build.
2. Verhalten. Ein Besuch, der kein Ereignis erzeugt hat, das nur eine JavaScript-Laufzeit auslösen kann — kein Lesedauer-Segment, keine Überschriftenansicht, kein Verlassen, kein Klick — hat JavaScript nicht ausgeführt und ist unabhängig von seinem User-Agent ein Crawler.

Darüber hinaus wird das eigene Team aus jeder Leserkennzahl ausgeschlossen. Ein Besucher, von dessen IP-Adresse innerhalb der letzten 30 Tage auch ein Beacon einer Admin-Sitzung für dieses Projekt gesendet wurde, wird als Eigentümer markiert und aus den Leserkennzahlen entfernt — getrennt von der Bot-Markierung, weil es sich um einen echten Menschen handelt, nur nicht um Ihre Zielgruppe. Optional entfernt eine serverseitige IP-Allowlist internen Datenverkehr, bevor er überhaupt geschrieben wird.

Bot- und Eigentümerbesuche werden beibehalten und gekennzeichnet, nicht gelöscht, sodass das Panel Ihnen die Aufteilung anzeigen kann, anstatt Ihre Zahlen stillschweigend zu reduzieren.

Wie die Lesezeit tatsächlich berechnet wird#

Der Tracker startet die Zeitmessung, wenn eine Seite geladen wird, und liest sie aus, wenn der Leser die Seite verlässt — bei pagehide, bei visibilitychange → hidden unter iOS (wo pagehide unzuverlässig ist) und bei der Navigation innerhalb der Website. Jeder Lesevorgang erzeugt ein docs.read_time Segment und setzt die Zeitmessung zurück, sodass eine erneut aufgerufene Seite zwei Segmente statt eines doppelt gezählten Zeitraums erzeugt. Segmente, die kürzer als 3 Sekunden sind, werden überhaupt nicht ausgegeben.

Die Übermittlung erfolgt per navigator.sendBeacon an einen Endpunkt desselben Ursprungs und wird in Stapeln von bis zu 100 Ereignissen pro Beacon durchgeführt. Der gewöhnliche Logging-Transport verzögert über fetch zwei Sekunden, was das Schließen eines Tabs nicht übersteht — Lesezeit, Überschriftenaufrufe und das Verlassen der Seite sind die Ereignisse, die dies überstehen müssen, daher nehmen sie stattdessen den Beacon-Pfad.

Anschließend wird jedes Segment auf 300 Sekunden begrenzt, bevor irgendetwas addiert wird. Dies ist die mit Abstand wichtigste Zahl auf dieser Seite. Der Emitter zählt weiter, während ein Desktop-Tab im Hintergrund geöffnet ist, und bei einer Auswertung von 11.176 echten Sitzungen in 7 Arbeitsbereichen überschritten 40 einzelne Segmente zwei Stunden, das 99. Perzentil lag bei 81.342 Sekunden, und die Summierung der Rohsegmente erhöhte die gesamte Lesezeit ungefähr um das Dreißigfache — 1.268.422 Sekunden gegenüber 42.160 nach der Begrenzung. Dieselbe Begrenzung wird von jeder Oberfläche angewendet, die eine Zeitangabe ausgibt, sodass das Panel, die Spalte pro Seite, die Zielebene und die MCP-Tools nicht voneinander abweichen können.

Die durchschnittliche Lesezeit pro Seite teilt die begrenzte Gesamtdauer durch die Anzahl der Segmente, nicht durch die Anzahl der Besuche: Ein Leser, der zu einem anderen Tab wechselt und zurückkehrt, trägt zwei Segmente zu einem Besuch bei, und eine Mittelung nach Besuchen würde diesen Besuch doppelt anrechnen.

Wie sich der Traffic von KI-Assistenten von menschlichem Traffic unterscheiden lässt#

Anfragen werden in drei Gruppen eingeteilt, die niemals zusammengeführt werden:

Ein nicht erkannter Name eines KI-Bots wird als Training behandelt – die Einstufung, die Ihnen am wenigsten verspricht. Die Klassifizierung erfolgt anhand des User-Agents in der Reihenfolge „Der erste Treffer gewinnt“, sodass Applebot-Extended niemals von Applebot verschluckt wird.

Sampling, Obergrenzen und Aufbewahrung#

Es gibt keine Stichproben. Keine Zahl im Dashboard wird aus einer Teilmenge des Datenverkehrs hochgerechnet. Stattdessen gibt es eine feste Obergrenze: Die Sitzungsrekonstruktion liest pro Zeitraum höchstens 50.000 Ereignisse, und wenn sie diese Obergrenze erreicht, enthält das Ergebnis ein truncated-Flag, das von den Konsumenten angezeigt werden muss, da aus einem gekürzten Zeitraum berechnete Raten falsch sind. Eine Abfrage, die fehlschlägt, wird ebenfalls als fehlgeschlagen und nicht als null gemeldet — ein leeres Dashboard und ein fehlerhafter Lesevorgang sind unterschiedliche Ergebnisse.

Leserereignisse werden bei jedem Tarif 30 Tage lang aufbewahrt. Nach dreißig Tagen enden die Daten, nicht bei einer Tarifstufe: Dies ist die Aufbewahrungsdauer des Ereignisspeichers. Jeder Zeitraumfilter im Produkt liest dieselbe Konstante, sodass kein Steuerelement einen Zeitraum anbieten kann, den die Daten nicht abdecken. Das KI-Nutzungsprotokoll ist ein separater Speicher und wird länger aufbewahrt — 90 Tage, täglich bereinigt —, damit eine strittige Rechnung auch dann noch rekonstruiert werden kann, wenn sie in den Berichten nicht mehr angezeigt wird; dennoch bietet kein Bericht mehr als 30 Tage davon an.

Wo die Daten gespeichert sind#

Die im Panel angezeigten Search-Console-Zahlen werden von Google über die von Ihnen autorisierte Verbindung abgerufen und sind Daten von Google, nicht von Docsbook.

Datenschutz und DSGVO — was ist eine technische Tatsache und was ist Ihre Entscheidung#

Technische Fakten, die sich am Verhalten der Website überprüfen lassen:

• Die Analytics-Funktion der Docsbook-Dokumentationsseite schreibt nichts auf das Gerät des Lesers und liest nichts davon. Es gibt kein Analytics-Cookie und keine im Browser gespeicherte ID.
• Die Identität des Lesers wird serverseitig aus der IP-Adresse durch einen Schlüssel-Hash abgeleitet und ist auf Ihr Projekt beschränkt. Der Hash ist eine Einwegfunktion; die rohe IP-Adresse wird in keinem Bericht, Export oder MCP-Tool offengelegt.
• Kein Identifikator wird projektübergreifend geteilt, verkauft, syndiziert oder zum Erstellen eines websiteübergreifenden Profils verwendet.
• Die Aufbewahrungsdauer beträgt 30 Tage und wird vom Speicher durchgesetzt, nicht durch einen Berichtsfilter.

Was wir nicht behaupten. Docsbook behauptet nicht, dass der Betrieb die Einwilligungsfreiheit Ihrer Website, die DSGVO-Konformität oder die Befreiung von einer nationalen Regelung bewirkt. Zwei Dinge muss Ihr eigener Rechtsberater entscheiden:

1. Ob die Einwilligungspflicht der ePrivacy-Regelung greift. Artikel 5 Absatz 3 der Richtlinie 2002/58/EG (in der geänderten Fassung) macht „das Speichern von Informationen oder den Zugriff auf bereits im Endgerät gespeicherte Informationen“ von einer Einwilligung abhängig. Docsbook speichert und liest nichts auf dem Gerät, was genau der Auslöser ist, den diese Bestimmung nennt — die Leitlinien 2/2023 des EDSA zum technischen Anwendungsbereich von Art. 5 Absatz 3 widmen jedoch einen Abschnitt ausdrücklich dem „Tracking ausschließlich auf Grundlage der IP-Adresse“. Betrachten Sie daher „kein Cookie, also keine Einwilligung“ als Argument, nicht als abschließende Antwort.
2. Ob Sie nach der DSGVO weiterhin eine Rechtsgrundlage benötigen. Eine IP-Adresse, die einen Leser identifiziert, ist unabhängig von der Cookie-Frage personenbezogene Daten, daher liegen Ihre Datenschutzerklärung, Ihre Rechtsgrundlage und Ihre Auftragsverarbeitungsverträge mit den oben genannten Anbietern in Ihrer Verantwortung. Die eigenen Ausnahmekriterien der CNIL für Reichweitenmessung sind hier eine nützliche Checkliste, und Docsbook erfüllt mehrere davon (ein einzelner Herausgeber, keine websiteübergreifende Verknüpfung, Zweck auf Reichweitenmessung beschränkt) und nicht alle — insbesondere wird das letzte Byte der IP-Adresse vor der Speicherung nicht gekürzt.

Warum dies der richtige Weg ist#

Grenzen und offene Fragen#

• Jede Besucherzahl ist eine Schätzung, und das Produkt sagt dies in seinen eigenen Antworten auch so. Eine gehashte IP-Adresse führt alle Personen hinter einem Corporate-NAT zu einem einzigen Leser zusammen und teilt einen Pendler auf mehrere auf. Lesen Sie Besucherzahlen als Trend; zitieren Sie sie niemals als Anzahl der Personen.
• Die Lesezeit wird gekappt, nicht an Sichtbarkeit gebunden. Auf dem Desktop sammelt ein im Hintergrund geöffneter Tab weiterhin Sekunden, bis die Kappung bei 300 Sekunden greift. Das ist hinsichtlich der Richtung des Fehlers — die Lesezeit ist nach oben verzerrt und begrenzt — eine ehrliche Darstellung, aber es ist nicht dieselbe Messung wie die fokusbasierte Interaktionszeit von GA4, und diese Dokumentation erhebt auch nicht den Anspruch, dass dies der Fall ist.
• Die Bot-Filter sind Heuristiken ohne Verifizierungsschritt. Docsbook führt keine Reverse-DNS- oder Prüfung veröffentlichter IP-Bereiche für die behauptete Identität eines Crawlers durch, daher wird ein gefälschter User-Agent nach seinem bloßen Erscheinen klassifiziert. Die Verhaltensebene erfasst den häufigen Fall, den eine UA-Regex nicht erkennt; keine der beiden Ebenen ist eine Sicherheitskontrolle.
• Der Ausschluss von Eigentümern hängt von einem einzigen Beacon ab. Ein Teammitglied, das die Dokumentation liest, aber in den letzten 30 Tagen noch nie das Admin-Panel von dieser IP-Adresse aus geöffnet hat, wird als Leser gezählt.
• Geo-IP ermittelt das Netzwerk, nicht die Person. Ein Unternehmens-VPN ordnet einen Leser der Stadt zu, in der der Tunnel endet; ein Mobilfunknetz kann hundert Kilometer danebenliegen.
• Offene Frage: „Kein Cookie“ ist nicht dasselbe wie „Keine Einwilligung erforderlich“. Verifizierbar ist, dass die Analytics-Funktion der Docsbook-Dokumentationswebsite nichts im Browser speichert oder ausliest und dass die Leseridentität ein gesalzener serverseitiger Hash ist. Nicht geklärt ist die rechtliche Folge: Der EDPB hat die Frage des IP-basierten Trackings nach Art. 5(3) ausdrücklich aufgeworfen, und keine öffentliche Quelle klärt sie für einen gehashten, first-party-basierten Fall mit 30 Tagen. Betrachten Sie die Compliance-Schlussfolgerung als eine, die Ihre Rechtsberatung ziehen muss.
• Dreißig Tage sind eine harte Obergrenze. Jahresvergleiche, saisonale Auswertungen und Kohorten von mehr als vier Wochen sind mit diesen Daten überhaupt nicht möglich.

Verwandte Inhalte#

• Referenz zu erfassten Ereignissen — die 36 Ereignisse, die auf dieser Seite beschrieben werden
• Analytics-Übersicht — das Panel, das diese Definitionen erzeugen
• Lesezeit — der Clip, angewendet auf einen Bericht
• Ziele und Trichter — was bei einem Besuch als erreicht gilt
• Länder — geografische Auflösung und ihre praktischen Grenzen