Session Replay Setup

Record and replay user sessions to understand exactly what users see, click, and experience on your site.

What is Session Replay?#

Session Replay records your users' browser sessions so you can watch exactly what they experienced -- every page navigation, mouse movement, scroll, click, and form interaction. When a user encounters an error or drops off your funnel, you can replay their session to understand why.

JustAnalytics Session Replay captures:

DOM mutations -- every change to the page structure and content
Mouse movements -- cursor position tracked at up to 30fps
Scroll events -- vertical and horizontal scroll position over time
Click interactions -- where users click, including rage clicks and dead clicks
Input changes -- form field interactions (masked by default for privacy)
Network requests -- XHR/fetch requests with timing and status codes
Console output -- errors, warnings, and log messages
Page navigations -- full SPA route changes and hard navigations
Viewport resizes -- window dimension changes

Replays are stored as a compressed stream of incremental DOM snapshots, not video. This keeps the bandwidth overhead low -- typically 10-50 KB per minute of recording.

Session Replay is Enabled by Default#

Session replay is automatically enabled when you add the monitor.js script. No extra attributes are needed. The default configuration uses a 10% sample rate and mask-all privacy mode (all text masked, images replaced with placeholders).

<!-- Replay is ON by default (10% sample, mask-all privacy) -->
<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
></script>

To disable session replay, set data-replay="false":

<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-replay="false"
></script>

For production sites, you may want to customize the sample rate and privacy mode -- see sections below.

Full Configuration Example#

<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-sample-rate="0.1"
  data-privacy-mode="mask-user-input"
  data-capture-console="true"
  data-capture-network="true"
  data-capture-clicks="true"
  data-capture-dom="true"
  data-environment="production"
  data-release="2.4.1"
></script>

Configuration Options#

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | data-replay | boolean | true | Session replay recording (enabled by default, set to false to disable) | | data-sample-rate | number | 0.1 | Percentage of sessions to record (0.0 to 1.0) | | data-privacy-mode | string | mask-all | Privacy masking level: mask-all, mask-user-input, or allow-all | | data-capture-console | boolean | false | Include console output in replay | | data-capture-network | boolean | false | Include network request details in replay | | data-capture-clicks | boolean | false | Record click coordinates and targets | | data-capture-dom | boolean | false | Record DOM mutation details | | data-capture-events | boolean | false | Include custom events in replay timeline | | data-capture-storage | boolean | false | Record localStorage/sessionStorage changes | | data-max-duration | number | 3600 | Maximum recording duration in seconds (default: 1 hour) | | data-environment | string | production | Environment tag attached to replays | | data-release | string | - | Release version for filtering replays |

Sample Rate Configuration#

The default sample rate is 10% (0.1). For production sites with significant traffic, you can adjust this:

<!-- Default: 10% of sessions are recorded -->
<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
></script>

<!-- Record 50% of sessions -->
<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-sample-rate="0.5"
></script>

Error-Triggered Recording#

Even with a low sample rate, sessions that encounter JavaScript errors are always recorded. This means you can set a 5% sample rate for general browsing but still capture 100% of error sessions:

<!-- Record 5% of normal sessions, 100% of error sessions -->
<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-sample-rate="0.05"
></script>

The recorder maintains a rolling 30-second buffer. When an error occurs in an unsampled session, the buffer is flushed and recording continues for the remainder of that session.

Privacy Modes#

JustAnalytics provides three levels of privacy masking for session replay. Choose the mode that matches your compliance requirements.

`mask-all` (Default)#

All text content is replaced with asterisks. Images are replaced with gray placeholders. No user-visible content is recorded.

<!-- mask-all is the default privacy mode -->
<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-privacy-mode="mask-all"
></script>

This mode is the default and is recommended for sites handling sensitive data (healthcare, finance, legal). You can still see page structure, layout, click positions, and navigation flow.

`mask-user-input`#

Only form inputs, textareas, and contenteditable elements are masked. Static page content (headings, paragraphs, buttons) is visible in replays.

<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-privacy-mode="mask-user-input"
></script>

This mode provides a good balance between usability and privacy. Reviewers can see the page layout and content but cannot see what users typed.

`allow-all`#

No automatic masking is applied. All text, images, and input values are recorded as-is.

<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-privacy-mode="allow-all"
></script>

Warning: Only use allow-all if your site does not collect any personal or sensitive information, or if you have explicit user consent for full replay recording. You are responsible for compliance with GDPR, CCPA, and other privacy regulations.

Granular Masking Control#

Regardless of the global privacy mode, you can override masking on individual elements using data attributes.

`data-ja-mask` -- Force Mask an Element#

Force an element and all its children to be masked, even in allow-all mode:

<!-- Always mask this section -->
<div data-ja-mask>
  <p>Patient Name: John Doe</p>
  <p>SSN: 123-45-6789</p>
</div>

`data-ja-unmask` -- Force Unmask an Element#

Allow an element to be visible, even in mask-all mode. Useful for page titles, navigation, or marketing copy:

<!-- Show this heading in replays even with mask-all -->
<h1 data-ja-unmask>Product Catalog</h1>

<!-- Show navigation labels -->
<nav data-ja-unmask>
  <a href="/products">Products</a>
  <a href="/pricing">Pricing</a>
  <a href="/docs">Documentation</a>
</nav>

CSS Selector Masking#

For more complex masking rules, use the JavaScript API:

window.__JA_REPLAY_CONFIG = {
  maskSelectors: [
    '.credit-card-form',
    '#ssn-input',
    '[data-sensitive]',
  ],
  unmaskSelectors: [
    '.page-title',
    'nav.main-nav',
    '.product-name',
  ],
};

Place this configuration before the monitor.js script tag.

Viewing Replays in the Dashboard#

Accessing the Replay Player#

Navigate to Monitoring > Session Replay in your dashboard
Use filters to find specific sessions:
- Date range
- User actions (clicks, page views, errors)
- Pages visited
- Browser, OS, device type
- Frustration signals (rage clicks, dead clicks)
- Custom events
Click a session to open the replay player

Replay Player Controls#

The replay player provides:

Play/Pause -- standard playback controls
Speed control -- 1x, 2x, 4x, 8x playback speed
Timeline scrubber -- jump to any point in the session
Event markers -- colored dots on the timeline for clicks, errors, page navigations
Skip inactivity -- automatically skip periods with no user interaction
Console panel -- view console output alongside the replay
Network panel -- see network requests with timing
DOM inspector -- inspect element details at any point in the replay

Linking Replays to Errors#

When viewing an error in the Error Tracking dashboard, click View Session Replay to jump directly to the replay at the moment the error occurred. The replay includes 30 seconds of context before the error.

Performance Impact#

Session replay is designed to have minimal impact on your application's performance:

| Metric | Impact | |--------|--------| | JavaScript bundle | +12 KB gzipped (loaded async) | | CPU overhead | < 2% (mutation observer based, not polling) | | Memory usage | ~5-15 MB per session (compressed buffer) | | Network bandwidth | 10-50 KB/min uploaded (compressed, batched) | | First paint impact | None (script is deferred and async) |

Bandwidth Optimization#

Replay data is:

Compressed -- DOM snapshots are diffed and gzip-compressed before sending
Batched -- data is sent in batches every 5 seconds, not on every event
Incremental -- only changes since the last snapshot are recorded
Lazy -- static assets (images, CSS) are referenced by URL, not inlined

For very long sessions (over 30 minutes), the recorder automatically segments the replay into chapters to prevent memory buildup.

Framework-Specific Setup#

Next.js#

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        {/* Replay is on by default (10% sample, mask-all privacy) */}
        <Script
          src="https://justanalytics.app/monitor.js"
          data-site-id={process.env.NEXT_PUBLIC_JA_SITE_ID}
          data-privacy-mode="mask-user-input"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

React (Vite / CRA)#

<!-- public/index.html -->
<!-- Replay is on by default (10% sample, mask-all privacy) -->
<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-privacy-mode="mask-user-input"
></script>

Vue.js#

<!-- public/index.html or in your main layout -->
<!-- Replay is on by default (10% sample, mask-all privacy) -->
<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
></script>

WordPress#

Add to your theme's header.php or use a plugin like "Insert Headers and Footers":

<!-- Replay is on by default with mask-all privacy -->
<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
></script>

Troubleshooting#

Replays Not Appearing#

Verify data-replay is not set to "false" on the monitor.js script tag (replay is on by default)
Check that data-sample-rate is not set to 0
Open browser DevTools and look for requests to /api/ingest/replay -- they should return 200
Ensure your site ID is correct and matches your dashboard

Replays Look Blank or Broken#

If using mask-all mode, this is expected -- all text is masked
Check for Content Security Policy (CSP) headers blocking the recorder
Verify the page does not use Shadow DOM extensively (partial support)

High Bandwidth Usage#

Lower the sample rate: data-sample-rate="0.05" (5%)
Set a shorter max duration: data-max-duration="1800" (30 minutes)
Disable network body capture if not needed

Next Steps#

Privacy Controls -- detailed privacy configuration and compliance
Frustration Detection -- identify rage clicks, dead clicks, and error clicks
Heatmaps -- aggregate click and scroll data into visual heatmaps
Error Tracking -- correlate errors with session replays