Privacy-First Session Replay: The Honest Retention Ladder

Session Replay Has a Hoarding Problem

Session replay is the most privacy-sensitive artifact a web analytics tool produces. A replay is not a counter or a score — it is a reconstruction of a person using your site: where their cursor hesitated, which form field they abandoned, which paragraph they read three times. That is exactly what makes replay invaluable for debugging and conversion work, and exactly why the default posture of the replay industry — record everything, keep it as long as possible — deserves more scrutiny than it gets.

Most replay tools treat retention as a storage quota. Pay more, keep more; deletion happens when the quota fills or the invoice lapses. Retention becomes an accident of pricing rather than a decision about data, and the result is an archive of recordings of real people that mostly nobody will ever watch — pure liability, zero insight.

ClickStream takes the opposite position. Privacy-first session replay means retention is a deliberate ladder: a defined window per plan, enforced in the codebase on both the write path and the read path, topping out at 90 days for every self-serve plan. Keeping less is the feature.

The Session Replay Retention Ladder

Two packages, one launched capability set — with package limits published on the pricing page:

Explore is $0 with 5,000 human pageviews + 25,000 Signals Coverage units/month; Pro is $99/month with 25,000 human pageviews + 250,000 Signals Coverage units included. Automatic overage rates are published on the pricing page.

Free includes the launched replay capability within its published allowances; Paid includes it with automatic usage billing. Both retain the same capability set.

Enforced on Write and Read

A retention claim is worth very little if it is implemented as a dashboard filter over data that still exists. ClickStream enforces the ladder twice, at storage and at query:

• On write: the collector's live-session store — the Durable Object that holds replay frames at the edge — applies the published package limit to stored sessions.
• On read: the dashboard's replay endpoints clamp every query to the published package limit before touching storage.

The read-side clamp keeps package limits enforceable immediately — the read routes apply the current published limit before the storage layer's cleanup cycle has run. It is the same fail-safe posture ClickStream applies throughout the product: the page keeps rendering when context is unavailable.

What a ClickStream Replay Actually Shows

A replay reconstructs the session on top of the actual page, rendered at the visitor's recorded viewport size, from a stream of interaction frames: mouse movement, scrolling, clicks and touches, viewport resizes, input focus and edits, navigations, and tab-visibility changes — plus error, console, and network frames, so an engineer can line a JavaScript exception up with the exact moment of visible confusion that follows it. A timeline of session events runs alongside playback so you can jump straight to the interesting part instead of scrubbing.

One honesty detail worth calling out: every historical replay is labeled with its provenance. When full interaction frames were captured, playback is marked recorded. When they were not — replay disabled at the time, or an older session — the dashboard can synthesize approximate playback from the event timeline, and it labels that synthesized rather than passing reconstructed motion off as a recording.

What Never Leaves the Browser

Masking decisions are computed inside the visitor's browser, before a frame is ever queued for upload. The rules run in a strict precedence order:

• Passwords and hidden inputs are never captured — no value, not even a mask.
• Payment fields — matched by field name, cc-* autocomplete tokens, or a CVV-shaped value — are never serialized at all, not even as bullets, so a replay cannot leak the length or typing cadence of card data.
• Card-number-shaped values, including 12-plus-digit runs mid-typing, are dropped entirely regardless of what the field is called.
• SSN-shaped values are fully masked to bullets.
• Email values are partially masked: the first two characters, then the domain.
• Fields with sensitive names get a length-preserving bullet mask, so playback keeps the visible shape of the interaction without the content.

The value-based rules run regardless of field name — a card number typed into a field called notes still never serializes. And replay capture as a whole is opt-in at install time: the pixel records no replay frames unless you enable it (code below).

Bot-Filtered Replays

A meaningful share of any site's raw sessions is not human, and there is no worse use of a bounded retention window — or of your team's attention — than storing and scrubbing through a recording of a crawler paginating your catalog. Every ClickStream session carries a real-time bot verdict from the same detection engine that powers Signals — 11 bot categories, 158 named bots, and 38 AI agents. The Signals API exposes it as a four-way behavioral class — human, suspicious, likely bot, or bot — and the live view triages each session in plain language: real person, needs a check, or automated.

The live workspace ships a one-click Humans only filter that hides bot sessions from the replay list and shows a count of what it hid. The published usage meter will define how classified traffic affects billing. And when detection gets a real person wrong, there is an explicit correction path — the mark-it-human override — instead of a silently vanished session. For the full taxonomy of what gets caught, see the Bot Evasion Atlas.

Retention as a Privacy Feature

GDPR's storage-limitation principle says personal data should be kept no longer than necessary for its purpose. For session replay, the purpose is concrete: reproduce a bug, diagnose friction, verify a fix. That work has a useful life measured in days and weeks, not years. A recording from eleven months and forty releases ago is not evidence of anything about your current site — it is only risk.

A bounded window turns "we delete replay data" from a policy promise into a system property. It is a retention schedule you can state in a privacy policy or a data-processing agreement and back with code: both packages follow the published retention limit, and the replay of any session is unreadable and evicted on schedule. It is the same philosophy behind ClickStream's approach to compliance as scheduled jobs: an obligation you can read in the source outranks an obligation in a PDF.

What the Ladder Means Operationally

Each rung maps to a working rhythm rather than an arbitrary quota:

• Free — start learning. Full access to launched capabilities, with strict usage limits and no charges.
• Paid — keep learning as usage grows. Automatic usage-based billing applies across the launched capability set.

The operational habit the ladder encourages: file the finding, not the footage. A replay is evidence for a decision — a bug ticket, a form redesign, a copy change. Extract the decision while the window is open. Your aggregates — scores, funnels, journeys — do not expire with the frames; only the pixel-level reconstruction does.

Turning Replay On

Replay capture is an opt-in flag on the pixel install. With the stable @clickstreamhq/sdk package (1.4.0):

npm install @clickstreamhq/sdk

import { installClickstreamPixel } from '@clickstreamhq/sdk';

installClickstreamPixel({
  apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  endpoint: 'https://t.example.com', // your verified first-party tracking domain
  replay: true, // replay capture is opt-in
});

Script-tag installs get the same behavior with a data-replay="true" attribute on the pixel tag — the install guides cover tag managers and site builders. Either way, the pixel itself stays light: a 344-byte loader that pulls a ~56.5 KB gzipped bundle from your own subdomain.

The Bottom Line

• Retention is a product decision: both packages follow the published usage and retention limits.
• It is enforced twice: per-plan TTLs where frames are stored, and window clamps on every dashboard read route — so downgrades take effect immediately.
• Sensitive input never leaves the browser: passwords and hidden fields are never captured; card and CVV data is never serialized even masked; SSNs and sensitive fields are bullet-masked; emails are partially masked.
• Bot traffic is labeled and filterable: a detection engine covering 11 bot categories, 158 named bots, and 38 AI agents flags automated sessions, and one click hides them from the live replay list.
• Bounded retention is a commitment you can verify, not a storage quota you outgrow.

A replay you no longer need is not an asset. The honest thing to do with it is exactly what the ladder does: delete it — on schedule, in code.