Session Recording with the Flowsery script

Session recording lets you replay what real visitors did on your site, mouse movement, clicks, form input, page transitions, by dropping a small script into your HTML. The recorder is a separate JS bundle from the main analytics tracker, so it only loads when you opt in.

The recorder is built on rrweb and ships its DOM mutation events to Flowsery as gzip-compressed chunks. The first chunk is a full snapshot; subsequent chunks are incremental.

Prerequisites

• Recording must be enabled on the website in your Flowsery dashboard (Website → Settings → Recording). The server rejects recording_start requests when this is off.
• You're already running the main analytics tracker (/js/main.js). Recording uses the same data-fl-website-id, the same visitor and session cookies, and the same /events endpoint as the main tracker.

Quick start (CDN)

Drop the script tag right after your main 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>

The recorder runs the same gates as the main tracker (bot detection, localhost, iframe, file://, self-exclude) and bails out cleanly when any apply.

Prefer a single tag? Add the data-recording attribute to your main tracker and Flowsery injects the recorder for you, no second <script> needed:

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

Enable via npm SDK

If you initialize Flowsery through the npm SDK, turn recording on with a single flag instead of a script tag:

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

The SDK lazy-loads the recorder bundle from Flowsery's CDN on first init, so rrweb never ships in your application bundle. Tracking events still flow through your apiBase when set. Para gravar apenas uma parcela das sessões, adicione recordingSampleRate, e para analisar por IA apenas uma parcela dessas, adicione aiSampleRate (ambos 0–100, padrão 100): consulte Amostragem. Everything below, the dashboard prerequisite, privacy modes, gates, and browser support, applies the same way.

Reverse-proxied setup (recommended for production)

Adblockers and tracking-protection extensions block third-party scripts and analytics.flowsery.com directly. Routing both the script and the events endpoint through your own domain works around that, visitor IPs and accuracy stay intact.

The recorder auto-derives the API base from its own <script src>, the same way the main tracker does. As long as the recording bundle is served under /js/recording.js on your domain, no extra configuration is needed.

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>

Other proxies

The same shape works for any reverse proxy. Map all three paths:

For framework-specific proxy guides (Astro, Caddy, Express, FastAPI, Nginx, PHP, Vue, etc.), see the proxy support guides.

Configuration

The recorder reads its configuration from the same <script> tag attributes as the main tracker. Most options are inherited automatically; the ones below are recording-specific.

data-rrweb-src (optional)

Override the URL the recorder uses to load rrweb. Defaults to 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>

Useful when your CSP forbids cdn.jsdelivr.net, or when you want to self-host rrweb to avoid third-party requests.

data-recording-sample (opcional)

Grave apenas uma porcentagem das sessões. Aceita um número inteiro de 0–100.

• Padrão: 100: grava todas as sessões. Omita o atributo para gravação completa.
• Exemplo: data-recording-sample="30" grava ~30% das sessões.

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

A decisão é determinística por sessão: um visitante é gravado ou ignorado de forma consistente durante toda a sessão, entre recarregamentos e navegações de página, então você nunca obtém visitas gravadas pela metade. Sessões fora da amostra não baixam o gravador por completo. Consulte Amostragem para saber como isso se combina com a amostragem da análise de IA.

data-ai-sample (opcional)

Das sessões que você grava, envie apenas uma porcentagem para a análise de sessão por IA. Aceita um número inteiro de 0–100.

• Padrão: 100: analisa todas as sessões gravadas.
• Exemplo: data-ai-sample="50" envia ~50% das sessões gravadas para a análise de IA.

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

O gravador envia essa taxa ao Flowsery no handshake recording_start; o servidor a armazena na gravação e a aplica quando a análise é enfileirada (o navegador já foi embora nesse momento). Consulte Amostragem.

Privacy levels

The privacy mode is decided server-side per website (visible in the dashboard) and pushed to the recorder in the recording_start response. Available modes:

• balanced (default), Masks password, email, and tel inputs. Other inputs and text are recorded as-is.
• strict: Masks all inputs, masks all text content, blocks <video>, <audio>, and <canvas>, disables canvas recording.
• relaxed: No masking. Only use for internal apps where you control the input.

To override the dashboard setting per page, you'd need to post-process recordings server-side; the script honors whatever the server returns.

Amostragem

Em sites de alto tráfego você raramente precisa gravar todas as visitas. O Flowsery faz amostragem em dois estágios independentes, ambos configurados no script (ou no SDK npm): não há nada para definir no painel:

1. Taxa de amostragem de gravação: a parcela de sessões que chega a ser gravada. Defina com data-recording-sample (ou a opção recordingSampleRate do SDK), 0–100, padrão 100. O navegador decide, então sessões fora da amostra nunca baixam o gravador.
2. Taxa de amostragem da análise de IA: a parcela das sessões já gravadas que são enviadas para a análise de sessão por IA. Defina com data-ai-sample (ou a opção aiSampleRate do SDK), 0–100, padrão 100. O gravador envia isso ao Flowsery no handshake recording_start e o servidor a aplica por gravação, já que a análise de IA roda depois que a página é fechada.

As duas se multiplicam. Com uma taxa de gravação de 30% e uma taxa de IA de 50%, ~30% das sessões são gravadas e ~15% (30% × 50%) recebem um veredito de IA: o restante continua totalmente reproduzível, apenas sem análise de IA.

A amostragem é determinística, não aleatória: a decisão de gravação é baseada na sessão, então um visitante é gravado (ou não) de forma consistente durante toda a sessão e entre recarregamentos. Os padrões de 100 mantêm o comportamento original, gravar e analisar tudo, então nada muda até você reduzir uma taxa.

How it works

1. The script reads data-fl-website-id from its own tag and resolves the visitor and session UIDs from the cookies set by the main tracker (_fs_vid, _fs_sid).
2. It POSTs recording_start to /events. If the server rejects (recording disabled, quota exceeded, etc.) the script stops.
3. On accept, it loads rrweb and starts capturing events into an in-memory buffer.
4. Every 15 seconds (or sooner if the buffer fills past 500 events / 256 KB), the buffer is JSON-Lined → gzipped → base64-encoded → POSTed as a recording_chunk. The server stores chunks in R2 and rolls up metrics (event counts, click/input/error/rage-click flags, duration) on the recording row.
5. No pagehide / beforeunload, um chunk final é enviado com finalize: true por um transporte à prova de descarregamento, navigator.sendBeacon para configurações com proxy de mesma origem, ou uma requisição fetch com keepalive para configurações diretas (de origem cruzada): para que o último chunk sobreviva ao encerramento da página. The server flips the recording status to ready so it shows up in the dashboard's recordings list.

Browser support

• Chrome/Edge 80+, Firefox 113+, Safari 16.4+: fully supported, gzip compression via CompressionStream.
• Older Safari / Firefox: the recorder falls back to non-gzipped chunks. They're stored, but playback in the dashboard requires the gzip encoding, so older-browser recordings won't replay until decoder support catches up.
• Safari Private Mode: sessionStorage is per-tab; a new recording UID is generated on every tab open. Otherwise works.
• Cookieless mode (data-cookieless on the main tracker): recording is disabled because there's no visitor or session UID to attach.

Cost and performance

• Network: typical session is 50–500 KB compressed; far less than a video. Chunks are sent every 15s on a keepalive connection or via Beacon API on unload.
• CPU: rrweb runs an idle MutationObserver: measurable but well under 1% CPU on typical pages. Offload via requestIdleCallback is built into rrweb 2.x.
• Privacy: the recorder respects Do Not Track only when data-respect-dnt="true" is set. Otherwise it records all visitors who hit recording_start. Configure in your dashboard.

Disable recording

Three options:

• Globally: turn off recording in the website settings. The server will reject recording_start and the script will stop.
• Per page: don't include the <script src="/js/recording.js"> tag.
• Per visitor: set localStorage.setItem('flowsery_ignore', 'true'): same opt-out used by the main tracker.

Troubleshooting

Recordings tab is empty

• Confirm recording is enabled on the website.
• Open DevTools → Network. You should see a successful recording_start POST followed by periodic recording_chunk POSTs.
• Check the response of recording_start: if accepted: false, the script stops; the response also tells you why (quota exceeded, recording disabled).

"This recording is too short to replay"

The recording exists but has fewer than 2 events. Common causes:

• The visitor closed the tab before the first chunk could ship.
• An adblocker blocked rrweb from loading. Check the Console for CSP or network errors.
• CompressionStream was missing and the fallback encoding stored a chunk that the dashboard's player can't decode yet.

Recording loads but my reverse proxy bypass doesn't kick in

Make sure the script is served from /js/recording.js exactly. The auto-derive regex matches script.js, main.js, and recording.js (with optional .hash.js suffix); other paths fall through to the hardcoded analytics host. If you must serve from a different path, set data-api="https://yourdomain.com/api" explicitly.