getting-started

Sitzungsaufzeichnung mit dem Flowsery-Skript

Mit der Sitzungsaufzeichnung spielen Sie ab, was echte Besucher auf Ihrer Website getan haben, Mausbewegungen, Klicks, Formulareingaben, Seitenwechsel, indem Sie ein kleines Skript in Ihr HTML einfügen. Der Recorder ist ein eigenes JS-Bundle, getrennt vom Haupt-Tracker, und wird daher nur geladen, wenn Sie ihn aktivieren.

Der Recorder basiert auf rrweb und sendet seine DOM-Mutation-Events als gzip-komprimierte Chunks an Flowsery. Der erste Chunk ist ein vollständiger Snapshot, die folgenden Chunks sind inkrementell.

Voraussetzungen

  • Die Aufzeichnung muss für die Website in Ihrem Flowsery-Dashboard aktiviert sein (Website-Einstellungen → Allgemein → Sitzungsaufzeichnung). Ist sie deaktiviert, lehnt der Server recording_start-Anfragen ab.
  • Der Haupt-Tracker (/js/main.js) läuft bereits auf Ihrer Website. Die Aufzeichnung nutzt dieselbe data-fl-website-id, dieselben Besucher- und Sitzungs-Cookies und denselben /events-Endpunkt wie der Haupt-Tracker.

Schnellstart (CDN)

Fügen Sie das Script-Tag direkt nach Ihrem Haupt-Tracker ein:

<script defer data-fl-website-id="flid_******" src="https://cdn.flowsery.com/main.js"></script>
<script defer data-fl-website-id="flid_******" src="https://cdn.flowsery.com/recording.js"></script>

Der Recorder durchläuft dieselben Prüfungen wie der Haupt-Tracker (Bot-Erkennung, localhost, iframe, file://, Selbstausschluss) und beendet sich sauber, wenn eine davon greift.

Lieber nur ein Tag? Fügen Sie Ihrem Haupt-Tracker das Attribut data-recording hinzu, dann lädt Flowsery den Recorder für Sie, ein zweites <script> ist nicht nötig:

<script defer data-fl-website-id="flid_******" data-recording src="https://cdn.flowsery.com/main.js"></script>

Über das npm-SDK aktivieren

Wenn Sie Flowsery über das npm-SDK initialisieren, schalten Sie die Aufzeichnung mit einem einzigen Flag statt mit einem Script-Tag ein:

import { initFlowsery } from 'flowsery';
 
await initFlowsery({
  websiteId: 'flid_******',
  recording: true,
});

Das SDK lädt das Recorder-Bundle bei der ersten Initialisierung per Lazy Loading vom CDN von Flowsery, rrweb landet also nie in Ihrem Anwendungs-Bundle. Tracking-Events laufen weiterhin über Ihre apiBase, sofern gesetzt. Um nur einen Teil der Sitzungen aufzuzeichnen, fügen Sie recordingSampleRate hinzu, und um nur einen Teil davon per KI zu analysieren, fügen Sie aiSampleRate hinzu (beide 0–100, Standard 100): siehe Sampling. Alles Folgende, die Voraussetzung im Dashboard, Datenschutzmodi, Prüfungen und Browser-Unterstützung, gilt genauso.

Setup mit Reverse Proxy (für die Produktion empfohlen)

Adblocker und Tracking-Schutz-Erweiterungen blockieren Skripte von Drittanbietern und analytics.flowsery.com direkt. Wenn Sie sowohl das Skript als auch den Events-Endpunkt über Ihre eigene Domain leiten, umgehen Sie das, und Besucher-IPs sowie Genauigkeit bleiben erhalten.

Der Recorder leitet die API-Basis automatisch aus seinem eigenen <script src> ab, genau wie der Haupt-Tracker. Solange das Recording-Bundle auf Ihrer Domain unter /js/recording.js ausgeliefert wird, ist keine zusätzliche Konfiguration nötig.

Next.js

// next.config.js
async rewrites() {
  return [
    { source: '/js/main.js', destination: 'https://cdn.flowsery.com/main.js' },
    { source: '/js/recording.js', destination: 'https://cdn.flowsery.com/recording.js' },
    { source: '/api/track', destination: 'https://analytics.flowsery.com/analytics/events' },
  ];
}
<script defer data-fl-website-id="flid_******" src="/js/main.js"></script>
<script defer data-fl-website-id="flid_******" src="/js/recording.js"></script>

Andere Proxys

Dasselbe Schema funktioniert mit jedem Reverse Proxy. Bilden Sie alle drei Pfade ab:

Öffentlicher PfadUrsprung
/js/main.jshttps://cdn.flowsery.com/main.js
/js/recording.jshttps://cdn.flowsery.com/recording.js
/api/trackhttps://analytics.flowsery.com/analytics/events

Proxy-Anleitungen für einzelne Frameworks (Astro, Caddy, Express, FastAPI, Nginx, PHP, Vue usw.) finden Sie in den Proxy-Anleitungen im Support.

Konfiguration

Der Recorder liest seine Konfiguration aus denselben Attributen des <script>-Tags wie der Haupt-Tracker. Die meisten Optionen werden automatisch übernommen, die folgenden gelten nur für die Aufzeichnung.

data-rrweb-src (optional)

Überschreibt die URL, von der der Recorder rrweb lädt. Standard ist https://cdn.jsdelivr.net/npm/rrweb@2/dist/rrweb.min.js.

<script defer data-fl-website-id="flid_******" data-rrweb-src="/js/rrweb.min.js" src="/js/recording.js"></script>

Nützlich, wenn Ihre CSP cdn.jsdelivr.net verbietet oder wenn Sie rrweb selbst hosten möchten, um Anfragen an Drittanbieter zu vermeiden.

data-recording-sample (optional)

Zeichnet nur einen Prozentsatz der Sitzungen auf. Akzeptiert eine ganze Zahl 0–100.

  • Standard: 100: jede Sitzung aufzeichnen. Lassen Sie das Attribut weg, um alles aufzuzeichnen.
  • Beispiel: data-recording-sample="30" zeichnet ~30 % der Sitzungen auf.
<script defer data-fl-website-id="flid_******" data-recording-sample="30" src="https://cdn.flowsery.com/recording.js"></script>

Die Entscheidung ist pro Sitzung deterministisch: Ein Besucher wird während seiner gesamten Sitzung, über Neuladen und Seitenwechsel hinweg, konsistent aufgezeichnet oder übersprungen, sodass Sie nie halb aufgezeichnete Besuche erhalten. Nicht ausgewählte Sitzungen laden den Recorder gar nicht erst herunter. Unter Sampling erfahren Sie, wie sich dies mit dem KI-Analyse-Sampling kombiniert.

data-ai-sample (optional)

Von den Sitzungen, die Sie aufzeichnen, wird nur ein Prozentsatz an die KI-Sitzungsanalyse gesendet. Akzeptiert eine ganze Zahl 0–100.

  • Standard: 100: jede aufgezeichnete Sitzung analysieren.
  • Beispiel: data-ai-sample="50" sendet ~50 % der aufgezeichneten Sitzungen an die KI-Analyse.
<script defer data-fl-website-id="flid_******" data-recording-sample="30" data-ai-sample="50" src="https://cdn.flowsery.com/recording.js"></script>

Der Recorder sendet diese Rate im recording_start-Handshake an Flowsery; der Server speichert sie auf der Aufzeichnung und wendet sie an, wenn die Analyse in die Warteschlange gestellt wird (der Browser ist zu diesem Zeitpunkt längst weg). Siehe Sampling.

Datenschutzstufen

Der Datenschutzmodus wird serverseitig festgelegt und dem Recorder in der Antwort auf recording_start mitgeteilt. Derzeit erhält jede Website balanced, und im Dashboard gibt es dafür keine Einstellung. Verfügbare Modi:

  • balanced (Standard): Maskiert Passwort-, E-Mail- und Telefonfelder. Andere Eingaben und Texte werden unverändert aufgezeichnet.
  • strict: Maskiert alle Eingaben und alle Textinhalte, blockiert <video>, <audio> und <canvas> und deaktiviert die Canvas-Aufzeichnung.
  • relaxed: Keine Maskierung. Nur für interne Anwendungen verwenden, bei denen Sie die Eingaben kontrollieren.

Für einen anderen Modus auf einer Seite müssten Sie die Aufzeichnungen serverseitig nachbearbeiten; das Skript übernimmt, was der Server zurückgibt.

Sampling

Auf Websites mit hohem Traffic müssen Sie selten jeden Besuch aufzeichnen. Flowsery samplet in zwei unabhängigen Stufen, die beide auf dem Skript (oder über das npm-SDK) festgelegt werden, im Dashboard ist nichts einzustellen:

  1. Aufzeichnungs-Sampling-Rate: der Anteil der Sitzungen, die überhaupt aufgezeichnet werden. Festgelegt mit data-recording-sample (oder der SDK-Option recordingSampleRate), 0–100, Standard 100. Der Browser entscheidet, sodass nicht ausgewählte Sitzungen den Recorder nie herunterladen.
  2. KI-Analyse-Sampling-Rate: der Anteil der bereits aufgezeichneten Sitzungen, die an die KI-Sitzungsanalyse gesendet werden. Festgelegt mit data-ai-sample (oder der SDK-Option aiSampleRate), 0–100, Standard 100. Der Recorder sendet diese Rate im recording_start-Handshake an Flowsery, und der Server wendet sie pro Aufzeichnung an, da die KI-Analyse läuft, nachdem die Seite geschlossen wurde.

Beide werden multipliziert. Bei einer Aufzeichnungsrate von 30 % und einer KI-Rate von 50 % werden ~30 % der Sitzungen aufgezeichnet und ~15 % (30 % × 50 %) erhalten ein KI-Urteil, der Rest bleibt vollständig abspielbar, wird nur nicht per KI analysiert.

Das Sampling ist deterministisch, nicht zufällig: Die Aufzeichnungsentscheidung basiert auf der Sitzung, sodass ein Besucher während seiner gesamten Sitzung und über Neuladen hinweg konsistent aufgezeichnet wird (oder nicht). Die Standardwerte von 100 behalten das ursprüngliche Verhalten bei, alles aufzeichnen und analysieren, sodass sich nichts ändert, bis Sie eine Rate senken.

So funktioniert es

  1. Das Skript liest data-fl-website-id aus seinem eigenen Tag und ermittelt die Besucher- und Sitzungs-UIDs aus den Cookies, die der Haupt-Tracker setzt (_fs_vid, _fs_sid).
  2. Es sendet recording_start per POST an /events. Lehnt der Server ab (Aufzeichnung deaktiviert, Kontingent überschritten usw.), stoppt das Skript.
  3. Bei Annahme lädt es rrweb und beginnt, Events in einem Puffer im Arbeitsspeicher zu erfassen.
  4. Alle 15 Sekunden (oder früher, wenn der Puffer mehr als 500 Events / 256 KB enthält) wird der Puffer als JSON Lines serialisiert → gzip-komprimiert → base64-kodiert → als recording_chunk per POST gesendet. Der Server speichert die Chunks in R2 und fasst Kennzahlen (Event-Anzahl, Flags für Klicks, Eingaben, Fehler und Rage-Klicks, Dauer) in der Zeile der Aufzeichnung zusammen.
  5. Bei pagehide / beforeunload wird ein letzter Chunk mit finalize: true über einen entlade-sicheren Transport gesendet, navigator.sendBeacon für per Proxy geleitete Setups mit gleichem Origin, oder eine fetch-Anfrage mit keepalive für direkte (Cross-Origin-)Setups, sodass der letzte Chunk den Seitenabbau übersteht. Der Server setzt den Status der Aufzeichnung auf ready, damit sie in der Aufzeichnungsliste des Dashboards erscheint.

Browser-Unterstützung

  • Chrome/Edge 80+, Firefox 113+, Safari 16.4+: voll unterstützt, gzip-Komprimierung über CompressionStream.
  • Ältere Versionen von Safari / Firefox: Der Recorder weicht auf nicht komprimierte Chunks aus. Sie werden gespeichert, aber die Wiedergabe im Dashboard setzt die gzip-Kodierung voraus, daher lassen sich Aufzeichnungen aus älteren Browsern erst abspielen, wenn die Decoder-Unterstützung nachzieht.
  • Privater Modus in Safari: sessionStorage gilt pro Tab; bei jedem neu geöffneten Tab wird eine neue Aufzeichnungs-UID erzeugt. Ansonsten funktioniert alles.
  • Cookieless-Modus (data-cookieless auf dem Haupt-Tracker): Die Aufzeichnung ist deaktiviert, weil es keine Besucher- oder Sitzungs-UID gibt, an die sie angehängt werden kann.

Kosten und Performance

  • Netzwerk: Eine typische Sitzung umfasst komprimiert 50–500 KB, weit weniger als ein Video. Chunks werden alle 15 s über eine keepalive-Verbindung oder beim Entladen über die Beacon API gesendet.
  • CPU: rrweb betreibt einen MutationObserver im Leerlauf: messbar, aber auf typischen Seiten deutlich unter 1 % CPU. Die Auslagerung über requestIdleCallback ist in rrweb 2.x integriert.
  • Datenschutz: Der Recorder berücksichtigt Do Not Track nur, wenn data-respect-dnt="true" gesetzt ist. Andernfalls zeichnet er alle Besucher auf, die recording_start erreichen.

Aufzeichnung deaktivieren

Drei Möglichkeiten:

  • Global: Schalten Sie die Aufzeichnung in den Website-Einstellungen aus. Der Server lehnt dann recording_start ab und das Skript stoppt.
  • Pro Seite: Binden Sie das Tag <script src="/js/recording.js"> nicht ein.
  • Pro Besucher: Setzen Sie localStorage.setItem('flowsery_ignore', 'true'): derselbe Opt-out, den auch der Haupt-Tracker nutzt.

Fehlerbehebung

Der Tab "Aufzeichnungen" ist leer

  • Prüfen Sie, ob die Aufzeichnung für die Website aktiviert ist.
  • Öffnen Sie DevTools → Network. Sie sollten einen erfolgreichen POST recording_start sehen, gefolgt von regelmäßigen POSTs recording_chunk.
  • Prüfen Sie die Antwort auf recording_start: Bei accepted: false stoppt das Skript; die Antwort nennt auch den Grund (Kontingent überschritten, Aufzeichnung deaktiviert).

"Diese Aufzeichnung ist zu kurz für die Wiedergabe"

Die Aufzeichnung existiert, hat aber weniger als 2 Events. Häufige Ursachen:

  • Der Besucher hat den Tab geschlossen, bevor der erste Chunk gesendet werden konnte.
  • Ein Adblocker hat das Laden von rrweb verhindert. Prüfen Sie die Konsole auf CSP- oder Netzwerkfehler.
  • CompressionStream fehlte, und die Ausweichkodierung hat einen Chunk gespeichert, den der Player im Dashboard noch nicht dekodieren kann.

Die Aufzeichnung lädt, aber die Umgehung über meinen Reverse Proxy greift nicht

Stellen Sie sicher, dass das Skript genau unter /js/recording.js ausgeliefert wird. Der reguläre Ausdruck für die automatische Ableitung erkennt script.js, main.js und recording.js (mit optionalem Suffix .hash.js); andere Pfade fallen auf den fest eingetragenen Analytics-Host zurück. Wenn Sie einen anderen Pfad nutzen müssen, setzen Sie data-api="https://yourdomain.com/api" ausdrücklich.