analyticsOS-Tracking

Was macht analyticsOS-Tracking?

analyticsOS zeichnet Seitenaufrufe, Klicks, Scrolls, Formulare, Fehler, Geschwindigkeit und angemeldete Benutzer über ein Skript pro App auf. Die Installation erfolgt mit zwei Tags im <head> der Seite; die meiste Arbeit besteht darin, sie an der richtigen Stelle für den Stack zu platzieren und personenbezogene Daten fernzuhalten.

Was Sie von der Person benötigen

Die analyticsOS-Setupseite gibt ihnen einen Prompt mit drei Werten. Fragen Sie nach fehlenden Werten; raten Sie niemals.

• Host: Wo ihre analyticsOS-Instanz läuft, z. B. https://analytics.example.com.
• Key: Der öffentliche Schlüssel der App, prj_…. Es ist kein Geheimnis: Er landet in jeder Seite, die das Skript lädt.
• Modus: Identifiziert (Apps mit Logins, Einwilligung in ihrer Vereinbarung) oder Anonym (öffentliche Websites, nichts wird auf dem Gerät gespeichert).

Installation

1. Finden Sie den Stack und lesen Sie seine Referenz, bevor Sie etwas ändern:

   • Next.js (App Router oder Pages Router): references/nextjs.md
   • Flask oder eine andere Jinja-App: references/flask.md
   • Webflow: references/webflow.md
   • Alles andere (reines HTML, Vite, Astro, SvelteKit, Rails, Django, PHP, WordPress…): references/any-site.md

2. Umgebungsvariablen, keine hartcodierten Werte: ANALYTICS_HOST und ANALYTICS_KEY, mit dem Präfix, das der Build benötigt, um sie der Seite zur Verfügung zu stellen (NEXT_PUBLIC_ für Next.js, VITE_ für Vite). Fügen Sie sie in die lokale .env ein, fügen Sie die Namen mit leeren Werten zu .env.example hinzu und teilen Sie der Person mit, dass sie sie in den Einstellungen ihres Hosts (Railway → Variablen, Vercel → Umgebungsvariablen…) für jede Umgebung setzen muss, in der Tracking laufen soll.

3. Die beiden Tags im <head> auf jeder Seite, nur wenn der Schlüssel gesetzt ist. Ohne Schlüssel darf nichts geladen werden: das ist der Ausschalter für lokale Entwicklung und Vorschauen.

   <script>
     window.aos =
       window.aos ||
       function () {
         ;(window.aos.q = window.aos.q || []).push(arguments)
       }
   </script>
   <script defer src="{ANALYTICS_HOST}/s/{ANALYTICS_KEY}.js"></script>
   

   Das erste Tag stellt Aufrufe in die Warteschlange, die vor dem Laden des Skripts getätigt werden; das zweite lädt das Skript mit den Einstellungen der App.

4. Angemeldete Benutzer (nur im Modus Identifiziert): siehe references/events.md. Im anonymen Modus fügen Sie keine Identify-Aufrufe hinzu und speichern nichts über den Besucher.

5. Benennen Sie die Hauptabschnitte wichtiger Seiten mit data-section="Preise" (Hero, Preise, Anmeldeformular…), damit Berichte sie benennen können, und setzen Sie data-private auf jedes Element, dessen Text niemals gelesen werden darf: Kundennamen, Beträge, Adressen, alles Persönliche.

6. Content-Security-Policy: Wenn das Projekt eine setzt, erlauben Sie den Host in script-src und connect-src.

7. Sonst nichts: Fügen Sie keine anderen Analysetools, Cookies oder Consent-Banner hinzu. analyticsOS benötigt keines davon.

8. Abschluss: Führen Sie den Build und Linter des Projekts aus, listen Sie die geänderten Dateien auf und teilen Sie der Person mit, dass sie die App in einem Browser öffnen soll. Die Setupseite in analyticsOS hakt den ersten Seitenaufruf innerhalb von Sekunden ab.

Was das Skript bereits erfasst

Schreiben Sie für keine dieser Funktionen Code; sie sind im Skript enthalten:

• Seitenaufrufe, einschließlich clientseitiger Navigationen in Single-Page-Apps;
• Klicks auf Links, Buttons und alles mit data-aos-event, sowie ausgehende Links, Downloads, Rage Clicks und Dead Clicks;
• Scrolltiefe und Verweildauer auf der Seite;
• Gestartete, abgeschickte und abgebrochene Formulare (niemals, was eingegeben wurde);
• Core Web Vitals (LCP, INP, CLS, FCP, TTFB), JavaScript-Fehler und fehlgeschlagene Same-Origin-Anfragen.

Benutzerdefinierte Ereignisse, benannte Klicks und Identify befinden sich in references/events.md.

Datenschutzregeln

Diese gelten in jedem Projekt, egal was die Person verlangt:

• Senden Sie niemals eine E-Mail-Adresse, einen Namen, eine Telefonnummer oder etwas, das eine Person eingegeben hat: nicht in identify-Traits, nicht in track-Props, nicht in data-aos-event-Namen.
• Identifizieren Sie mit der internen Benutzer-ID der App, niemals mit der E-Mail.
• Markieren Sie Elemente, die personenbezogene Daten anzeigen, mit data-private. Das Skript liest niemals Inputs, Textareas oder contenteditable.
• Browser, die „Do Not Track“ oder „Global Privacy Control“ senden, werden überhaupt nicht getrackt, und aos()-Aufrufe werden verworfen. Umgehen Sie dies nicht.

Wenn nichts ankommt

Öffnen Sie die App mit dem Netzwerk-Tab des Browsers:

• /s/{key}.js sollte geladen werden (200), dann sollten Anfragen an {host}/api/e mit 204 antworten.
• 403 von /api/e: Die Domain der Seite ist nicht in den erlaubten Domains der App (analyticsOS → Einstellungen der App). Fügen Sie sie hinzu, oder lassen Sie die Liste während des Tests leer.
• 404: Der Schlüssel ist falsch oder wurde vor mehr als 24 Stunden rotiert.
• Überhaupt keine Anfragen: Die Schlüsselvariable ist in dieser Umgebung nicht gesetzt, eine Content-Security-Policy blockiert den Host, oder der Browser sendet „Do Not Track“ / „Global Privacy Control“.
• Next.js, Ereignisse stoppen nach der ersten Seite: Die Tags wurden als einfache <script>-Elemente in einem verschachtelten Layout hinzugefügt. Verwenden Sie next/script im Root-Layout (siehe references/nextjs.md).