Session replay with consent first
Record session replays under GDPR by setting require_consent: true on your project and calling vibiz('replay', 'start') once visitors opt in.
On this page 8 sections
To run session replay under GDPR with consent first, set require_consent: true on your replay configuration and invoke vibiz('replay', 'start') only after a visitor accepts your privacy banner. By default, the recording engine masks emails, phone numbers, and payment details in the browser before any data leaves the visitor's device. You can pair this opt-in flow with zero-storage analytics tags so that your site complies with European privacy laws without losing insight into broken user experiences.
This guide walks you through configuring consent-first replay, managing browser storage, and confirming that sensitive user data never reaches your dashboard.
When do you need consent for session replay?
In jurisdictions governed by the GDPR, the UK Data Protection Act, or similar privacy frameworks, capturing how a visitor interacts with a page often falls under data processing rules that require explicit consent. While aggregate pageview tracking can operate under legitimate interest when no personal data is stored, session replay records mouse movements, clicks, layout shifts, and DOM changes.
Even with automatic masking, a session recording can reveal browsing patterns tied to specific visitors. When you run a site in the EU or UK—or serve visitors there—you should:
- Prevent the replay script from recording automatically on page load.
- Present a clear choice to your visitor asking for their permission.
- Start the recording recorder only after they click accept.
- Document the recording mechanism clearly in your site's privacy policy.
Beyond replay recordings, you must also evaluate how your site handles browser storage. You can read more about broad traffic tracking in our guide to adding analytics to any site with one tag.
How to enable consent mode for replay
By default, adding the replay resource to a project causes every session to record automatically with no prompt. To require consent before recording begins, update your project's replay configuration via the API.
Send a PATCH request to the project resource endpoint setting require_consent to true:
curl -X PATCH "https://thelastapi.dev/v1/projects/prj_123/resources/replay" \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"config": {
"require_consent": true,
"sample_rate": 1,
"retention_days": 30
}
}'Once require_consent: true is saved, the tag still loads on the page to register analytics, but the replay recorder stays dormant. It will not capture DOM snapshots, queue interaction events, or send 1 MB chunks to the server until your client code explicitly tells it to begin.
You can configure other replay properties in that same config object:
sample_rate: A fraction from 0 to 1 (default is 1).retention_days: How long session recordings stay stored, from 1 to 90 days (default is 30).trigger_events: Specific events that trigger recording uploads when below a full sample rate.unmask_pages: Pages where you wish to loosen default DOM masking.record_css_rules: Boolean flag for CSS capture.
How to start and stop replay when a visitor agrees
Once consent mode is active, your frontend application controls the recording lifecycle using two global JavaScript calls: vibiz('replay', 'start') and vibiz('replay', 'stop').
Step 1: Place the analytics and replay script tag
Embed the tag before the closing </head> tag on every page where you want tracking. On our hosting, your environment variables supply NEXT_PUBLIC_VIBIZ_ANALYTICS_KEY:
<script defer src="https://thelastapi.dev/v1/script.js" data-key="vz_pk_123"></script>If your legal compliance requires you to avoid setting identifiers in localStorage entirely before consent, append the data-no-storage attribute to the script tag:
<script defer src="https://thelastapi.dev/v1/script.js" data-key="vz_pk_123" data-no-storage></script>When data-no-storage is present, the script drops the random browser ID. The analytics server calculates visitor uniqueness with a daily-salted IP hash instead. Returning visitors count anew each day, and no identifier persists across sessions in browser storage.
Step 2: Trigger recording on banner acceptance
When a visitor clicks "Accept" on your banner, trigger the recorder:
function onConsentGranted() {
// Save user preference in your app state or cookie
localStorage.setItem('user_consent', 'granted');
// Start the replay recorder for this tab
if (typeof window.vibiz === 'function') {
window.vibiz('replay', 'start');
}
}
function onConsentRevoked() {
// Save user opt-out
localStorage.setItem('user_consent', 'denied');
// Stop recording and prevent future auto-starts in this browser
if (typeof window.vibiz === 'function') {
window.vibiz('replay', 'stop');
}
}If a visitor previously agreed and returns to your site, check their stored choice on subsequent page loads and call vibiz('replay', 'start') when initializing your application. If they ever revoke permission, vibiz('replay', 'stop') halts the recorder immediately.
If the visitor signs into an account, you can tie their cross-device sessions together using vibiz('identify', user.id). When they sign out, call vibiz('identify', null).
What gets masked before data leaves the browser
Consent does not remove your obligation to protect sensitive personal data. Recording passwords or card information is a serious compliance violation.
The replay client sanitizes content directly inside the visitor's browser before data ever travels over the network:
- Passwords and credit card fields: Input elements marked for passwords, cards, or one-time codes are never recorded under any circumstances.
- Card numbers and IBANs: Any credit card number or IBAN typed anywhere on the page—even outside designated payment fields—is masked.
- Personal identifiers: Any page text matching the pattern of an email address, phone number, card number, or IBAN is automatically replaced with masking characters.
- URLs: Page URLs are recorded with their query strings stripped, keeping tokens and search queries out of session metadata.
Custom masking rules in your HTML
To mask custom elements or proprietary data that regex patterns might miss, use data attributes in your markup:
<!-- Masks an entire section: replaced by masked characters or striped blocks -->
<div data-vibiz-mask>
<h3>Account Balance</h3>
<p>$14,250.00</p>
</div>
<!-- Completely blocks an input field from recording its value -->
<input type="text" name="tax_id" data-vibiz-sensitive />When reviewing recordings, masked text appears as asterisks or bullets, and blocked regions show up as striped boxes. You can read more about how this works in our breakdown of session replay for a small site.
Replay configuration and privacy settings
The table below summarizes your configuration options for managing replay and visitor privacy:
| Setting | Location | Default | Effect |
|---|---|---|---|
require_consent | Replay API config | false | When true, waits for vibiz('replay', 'start') |
data-no-storage | <script> attribute | Absent | Disables localStorage random ID; uses daily-salted IP hash |
retention_days | Replay API config | 30 | Stores recordings for 1 to 90 days before deletion |
sample_rate | Replay API config | 1 | Fraction of sessions to capture (below 1, errors still upload) |
data-vibiz-mask | HTML attribute | None | Masks matching text inside the browser |
data-vibiz-sensitive | HTML attribute | None | Blocks an input field from capturing typed entries |
Analytics events and replay sessions are recorded at $0. Replay storage costs $0.023 per GB-month, billed with our standard margin (+20% today).
Inspecting compliant sessions and error signals
Once consent-gated replays are active, you can monitor issues using the command line or check your account dashboard.
Find sessions where visitors encountered problems:
# List sessions with JavaScript errors over the last 7 days
vibiz replays --errors --period 7d
# Watch a specific session by ID
vibiz replay rpl_123You can also pull visual frames of critical moments—such as rage clicks, dead clicks, or broken forms—using vibiz replays frames:
vibiz replays frames rpl_123 --moments error,rage_click --out ./debug-framesEach frame reconstructs the page as a static document photographed at the visitor's viewport. All masked regions stay masked in the exported PNGs. For more details on inspecting visuals, see our guide on replay frames as screenshots.
Session health also surfaces directly inside the automated checks of Mission Control and health checks. The Experience step flags a warning if it detects 3 or more sessions with errors, 5 with rage clicks, or 10 with dead clicks over a 24-hour window, helping you triage bugs without violating visitor privacy.
Next steps
To start collecting compliant replays, update your replay configuration with require_consent: true and connect vibiz('replay', 'start') to your consent banner. Full technical details on endpoints and event schemas are available in the Analytics and replay docs.
Frequently asked questions
Does setting require_consent disable pageview analytics?
No. Pageview tracking, country lookups, and custom events continue to record normally unless you remove the script tag. The consent flag only pauses the session replay recorder until you call `vibiz('replay', 'start')`.
What happens when I add the data-no-storage attribute to the script tag?
The script stops setting a random identifier in browser `localStorage`. Instead, the server uses a daily-salted IP hash to measure returning visitors, resetting uniqueness counts each day without saving the IP.
Can credit card numbers or passwords ever appear in a replay?
No. Password, card, and one-time-code fields are never recorded, and any text resembling an email, phone number, card number, or IBAN is masked directly in the browser before upload.
How long are consent-approved session replays stored?
Replays are stored for 30 days by default. You can adjust this window between 1 and 90 days by updating `retention_days` on the replay resource configuration.