getting-started

Sessie-opname met het Flowsery-script

Met sessie-opname speel je opnieuw af wat echte bezoekers op je site deden (muisbewegingen, klikken, formulierinvoer, paginawissels) door een klein script aan je HTML toe te voegen. De recorder is een aparte JS-bundel, los van de gewone analytics-tracker, dus hij laadt alleen als je ervoor kiest.

De recorder is gebouwd op rrweb en stuurt zijn DOM-mutatie-events als met gzip gecomprimeerde chunks naar Flowsery. De eerste chunk is een volledige snapshot; de volgende chunks zijn incrementeel.

Vereisten

  • Opname moet voor de website aanstaan in je Flowsery-dashboard (Website settings → General → Session recording). Staat dit uit, dan weigert de server verzoeken voor recording_start.
  • De gewone analytics-tracker (/js/main.js) draait al. Opname gebruikt dezelfde data-fl-website-id, dezelfde bezoekers- en sessiecookies en hetzelfde endpoint /events als de gewone tracker.

Snel aan de slag (CDN)

Zet de scripttag direct na je gewone analytics-tracker:

<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>

De recorder doet dezelfde controles als de gewone tracker (botdetectie, localhost, iframe, file://, zelfuitsluiting) en stopt netjes als een daarvan van toepassing is.

Liever één tag? Voeg het attribuut data-recording toe aan je gewone tracker en Flowsery voegt de recorder voor je in, zonder tweede <script>:

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

Inschakelen via de npm SDK

Initialiseer je Flowsery via de npm SDK, zet opname dan aan met één vlag in plaats van een scripttag:

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

De SDK laadt de recorderbundel bij de eerste initialisatie pas vanaf het CDN van Flowsery, dus rrweb komt nooit in je eigen applicatiebundel terecht. Trackingevents lopen nog steeds via je apiBase als die is ingesteld. Wil je maar een deel van de sessies opnemen, voeg dan recordingSampleRate toe, en wil je daarvan maar een deel door AI laten analyseren, voeg dan aiSampleRate toe (allebei 0–100, standaard 100): zie Steekproeven. Alles hieronder, de vereiste in het dashboard, privacymodi, controles en browserondersteuning, geldt op dezelfde manier.

Opstelling met reverse proxy (aanbevolen voor productie)

Adblockers en extensies tegen tracking blokkeren scripts van derden en analytics.flowsery.com rechtstreeks. Leid je zowel het script als het eventsendpoint via je eigen domein, dan omzeil je dat en blijven bezoekers-IP's en nauwkeurigheid intact.

De recorder leidt de API-basis automatisch af uit zijn eigen <script src>, net als de gewone tracker. Zolang de opnamebundel op je domein onder /js/recording.js wordt geserveerd, is er geen extra configuratie nodig.

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 proxy's

Dezelfde opzet werkt voor elke reverse proxy. Koppel alle drie de paden:

Openbaar padOrigin
/js/main.jshttps://cdn.flowsery.com/main.js
/js/recording.jshttps://cdn.flowsery.com/recording.js
/api/trackhttps://analytics.flowsery.com/analytics/events

Voor proxygidsen per framework (Astro, Caddy, Express, FastAPI, Nginx, PHP, Vue, enz.), zie de supportgidsen voor proxy's.

Configuratie

De recorder leest zijn configuratie uit dezelfde attributen van de <script>-tag als de gewone tracker. De meeste opties worden automatisch overgenomen; de opties hieronder gelden alleen voor opname.

data-rrweb-src (optioneel)

Overschrijf de URL waarmee de recorder rrweb laadt. Standaard is dat 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>

Handig als je CSP cdn.jsdelivr.net niet toestaat, of als je rrweb zelf wilt hosten om verzoeken naar derden te voorkomen.

data-recording-sample (optioneel)

Neem maar een percentage van de sessies op. Accepteert een heel getal van 0 tot 100.

  • Standaard: 100: elke sessie opnemen. Laat het attribuut weg om alles op te nemen.
  • Voorbeeld: data-recording-sample="30" neemt ~30% van de sessies op.
<script defer data-fl-website-id="flid_******" data-recording-sample="30" src="https://cdn.flowsery.com/recording.js"></script>

De beslissing ligt per sessie vast: een bezoeker wordt de hele sessie consequent opgenomen of overgeslagen, ook bij herladen en navigeren tussen pagina's, dus je krijgt nooit half opgenomen bezoeken. Sessies buiten de steekproef downloaden de recorder helemaal niet. Zie Steekproeven voor hoe dit samenwerkt met de steekproef voor AI-analyse.

data-ai-sample (optioneel)

Stuur van de sessies die je opneemt maar een percentage naar de AI-sessieanalyse. Accepteert een heel getal van 0 tot 100.

  • Standaard: 100: elke opgenomen sessie analyseren.
  • Voorbeeld: data-ai-sample="50" stuurt ~50% van de opgenomen sessies naar de AI-analyse.
<script defer data-fl-website-id="flid_******" data-recording-sample="30" data-ai-sample="50" src="https://cdn.flowsery.com/recording.js"></script>

De recorder stuurt dit percentage in de handshake van recording_start naar Flowsery; de server slaat het op bij de opname en past het toe zodra de analyse in de wachtrij komt (de browser is dan allang weg). Zie Steekproeven.

Privacyniveaus

De privacymodus wordt op de server bepaald en in de respons op recording_start naar de recorder gestuurd. Elke website krijgt op dit moment balanced, en het dashboard heeft daar geen instelling voor. Beschikbare modi:

  • balanced (standaard): maskeert invoervelden voor wachtwoord, e-mail en telefoon. Andere invoer en tekst worden ongewijzigd opgenomen.
  • strict: maskeert alle invoer en alle tekst, blokkeert <video>, <audio> en <canvas> en schakelt canvasopname uit.
  • relaxed: geen maskering. Gebruik dit alleen voor interne apps waarin je de invoer zelf in de hand hebt.

Wil je op een pagina een andere modus, dan moet je de opnames op de server nabewerken; het script volgt wat de server teruggeeft.

Steekproeven

Op sites met veel verkeer hoef je zelden elk bezoek op te nemen. Flowsery neemt steekproeven in twee onafhankelijke stappen, die je allebei in het script (of de npm SDK) instelt: in het dashboard hoef je niets in te stellen:

  1. Steekproefpercentage voor opname: het deel van de sessies dat überhaupt wordt opgenomen. In te stellen met data-recording-sample (of de SDK-optie recordingSampleRate), 0–100, standaard 100. De browser beslist, dus sessies buiten de steekproef downloaden de recorder nooit.
  2. Steekproefpercentage voor AI-analyse: het deel van de al opgenomen sessies dat naar de AI-sessieanalyse gaat. In te stellen met data-ai-sample (of de SDK-optie aiSampleRate), 0–100, standaard 100. De recorder stuurt dit in de handshake van recording_start naar Flowsery en de server past het per opname toe, omdat de AI-analyse pas draait nadat de pagina is gesloten.

De twee worden met elkaar vermenigvuldigd. Bij een opnamepercentage van 30% en een AI-percentage van 50% wordt ~30% van de sessies opgenomen en krijgt ~15% (30% × 50%) een AI-oordeel; de rest blijft volledig af te spelen, alleen zonder AI-analyse.

Steekproeven zijn deterministisch, niet willekeurig: de opnamebeslissing hangt aan de sessie, dus een bezoeker wordt de hele sessie en ook na herladen consequent wel (of niet) opgenomen. Met de standaardwaarden van 100 blijft het oorspronkelijke gedrag behouden, alles opnemen en analyseren, dus er verandert niets totdat je een percentage verlaagt.

Hoe het werkt

  1. Het script leest data-fl-website-id uit zijn eigen tag en haalt de bezoekers- en sessie-UID's uit de cookies die de gewone tracker heeft gezet (_fs_vid, _fs_sid).
  2. Het stuurt een POST met recording_start naar /events. Weigert de server (opname uitgeschakeld, quotum overschreden, enz.), dan stopt het script.
  3. Na acceptatie laadt het rrweb en begint het events vast te leggen in een buffer in het geheugen.
  4. Elke 15 seconden (of eerder als de buffer boven de 500 events / 256 KB komt) wordt de buffer omgezet naar JSON Lines → met gzip gecomprimeerd → in base64 gecodeerd → als recording_chunk gePOST. De server slaat chunks op in R2 en werkt de statistieken (aantallen events, vlaggen voor klikken/invoer/fouten/rage clicks, duur) bij op de rij van de opname.
  5. Bij pagehide / beforeunload wordt een laatste chunk met finalize: true verstuurd via een transport dat het sluiten van de pagina overleeft: navigator.sendBeacon bij geproxyde opstellingen op dezelfde origin, of een fetch-verzoek met keepalive bij directe (cross-origin) opstellingen, zodat de laatste chunk het afbreken van de pagina overleeft. De server zet de status van de opname op ready, zodat hij in de lijst met opnames in het dashboard verschijnt.

Browserondersteuning

  • Chrome/Edge 80+, Firefox 113+, Safari 16.4+: volledig ondersteund, gzip-compressie via CompressionStream.
  • Oudere Safari / Firefox: de recorder valt terug op chunks zonder gzip. Die worden opgeslagen, maar afspelen in het dashboard vereist gzip-codering, dus opnames uit oudere browsers zijn pas af te spelen als de decoder ze ondersteunt.
  • Privémodus van Safari: sessionStorage geldt per tabblad; bij elk nieuw tabblad wordt een nieuwe opname-UID gemaakt. Verder werkt het gewoon.
  • Cookieloze modus (data-cookieless op de gewone tracker): opname staat uit, omdat er geen bezoekers- of sessie-UID is om aan te koppelen.

Kosten en prestaties

  • Netwerk: een gemiddelde sessie is gecomprimeerd 50–500 KB, veel minder dan een video. Chunks gaan elke 15 s via een keepalive-verbinding of bij het sluiten via de Beacon API.
  • CPU: rrweb draait een MutationObserver die vooral stilzit: meetbaar, maar ruim onder 1% CPU op gewone pagina's. Uitbesteden via requestIdleCallback zit ingebouwd in rrweb 2.x.
  • Privacy: de recorder respecteert Do Not Track alleen als data-respect-dnt="true" is ingesteld. Anders neemt hij alle bezoekers op die recording_start bereiken.

Opname uitschakelen

Drie mogelijkheden:

  • Overal: zet opname uit in de website-instellingen. De server weigert dan recording_start en het script stopt.
  • Per pagina: laat de tag <script src="/js/recording.js"> weg.
  • Per bezoeker: stel localStorage.setItem('flowsery_ignore', 'true') in: dezelfde opt-out die de gewone tracker gebruikt.

Problemen oplossen

Het tabblad met opnames is leeg

  • Controleer of opname voor de website aanstaat.
  • Open DevTools → Network. Je zou een geslaagde POST van recording_start moeten zien, gevolgd door periodieke POST's van recording_chunk.
  • Bekijk de respons op recording_start: bij accepted: false stopt het script; de respons vertelt ook waarom (quotum overschreden, opname uitgeschakeld).

"Deze opname is te kort om af te spelen"

De opname bestaat, maar heeft minder dan 2 events. Veelvoorkomende oorzaken:

  • De bezoeker sloot het tabblad voordat de eerste chunk verstuurd kon worden.
  • Een adblocker hield rrweb tegen. Kijk in de Console naar CSP- of netwerkfouten.
  • CompressionStream ontbrak en de fallbackcodering sloeg een chunk op die de speler in het dashboard nog niet kan decoderen.

De opname laadt, maar het omzeilen via mijn reverse proxy werkt niet

Zorg dat het script precies vanaf /js/recording.js wordt geserveerd. De regex voor automatisch afleiden matcht script.js, main.js en recording.js (met optioneel achtervoegsel .hash.js); andere paden vallen terug op de vaste analytics-host. Moet je echt vanaf een ander pad serveren, stel dan expliciet data-api="https://yourdomain.com/api" in.