Session Recording

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.

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.

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.

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. On pagehide / beforeunload, a final chunk is sent with finalize: true via navigator.sendBeacon. 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.