246 lines
8.3 KiB
Plaintext
246 lines
8.3 KiB
Plaintext
---
|
|
title: "How to add session replay to your website"
|
|
description: "Add privacy-first session replay to any site in minutes using OpenPanel. See exactly what users do without recording sensitive data."
|
|
difficulty: beginner
|
|
timeToComplete: 10
|
|
date: 2026-02-27
|
|
updated: 2026-02-27
|
|
cover: /content/cover-default.jpg
|
|
team: OpenPanel Team
|
|
steps:
|
|
- name: "Install OpenPanel"
|
|
anchor: "install"
|
|
- name: "Enable session replay"
|
|
anchor: "enable"
|
|
- name: "Configure privacy controls"
|
|
anchor: "privacy"
|
|
- name: "View replays in the dashboard"
|
|
anchor: "view"
|
|
---
|
|
|
|
# How to add session replay to your website
|
|
|
|
This guide walks you through enabling [session replay](/features/session-replay) with OpenPanel. By the end, you'll be recording real user sessions you can play back in the dashboard to understand exactly what your users did.
|
|
|
|
Session replay captures clicks, scrolls, and interactions as structured data—not video. Privacy controls are built in, and the replay module loads asynchronously so it never slows down your main analytics.
|
|
|
|
## Prerequisites
|
|
|
|
- An OpenPanel account
|
|
- Your Client ID from the [OpenPanel dashboard](https://dashboard.openpanel.dev/onboarding)
|
|
- Either the `@openpanel/web` npm package installed, or access to add a script tag to your site
|
|
|
|
## Install OpenPanel [#install]
|
|
|
|
If you're starting fresh, add the OpenPanel script tag to your page. If you already have OpenPanel installed, skip to the next step.
|
|
|
|
```html title="index.html"
|
|
<script>
|
|
window.op=window.op||function(){var n=[];return new Proxy(function(){arguments.length&&n.push([].slice.call(arguments))},{get:function(t,r){return"q"===r?n:function(){n.push([r].concat([].slice.call(arguments)))}} ,has:function(t,r){return"q"===r}}) }();
|
|
window.op('init', {
|
|
clientId: 'YOUR_CLIENT_ID',
|
|
trackScreenViews: true,
|
|
});
|
|
</script>
|
|
<script src="https://openpanel.dev/op1.js" defer async></script>
|
|
```
|
|
|
|
Or with npm:
|
|
|
|
```bash
|
|
npm install @openpanel/web
|
|
```
|
|
|
|
See the [Web SDK docs](/docs/sdks/web) or [Script tag docs](/docs/sdks/script) for a full install guide.
|
|
|
|
## Enable session replay [#enable]
|
|
|
|
Session replay is **off by default**. Enable it by adding `sessionReplay: { enabled: true }` to your init config.
|
|
|
|
### Script tag
|
|
|
|
```html title="index.html"
|
|
<script>
|
|
window.op=window.op||function(){var n=[];return new Proxy(function(){arguments.length&&n.push([].slice.call(arguments))},{get:function(t,r){return"q"===r?n:function(){n.push([r].concat([].slice.call(arguments)))}} ,has:function(t,r){return"q"===r}}) }();
|
|
window.op('init', {
|
|
clientId: 'YOUR_CLIENT_ID',
|
|
trackScreenViews: true,
|
|
trackOutgoingLinks: true,
|
|
sessionReplay: {
|
|
enabled: true,
|
|
},
|
|
});
|
|
</script>
|
|
<script src="https://openpanel.dev/op1.js" defer async></script>
|
|
```
|
|
|
|
The replay script (`op1-replay.js`) is fetched automatically alongside the main script. Because it loads asynchronously, it doesn't affect page load time or the size of your main analytics bundle.
|
|
|
|
### NPM package
|
|
|
|
```ts title="op.ts"
|
|
import { OpenPanel } from '@openpanel/web';
|
|
|
|
const op = new OpenPanel({
|
|
clientId: 'YOUR_CLIENT_ID',
|
|
trackScreenViews: true,
|
|
trackOutgoingLinks: true,
|
|
sessionReplay: {
|
|
enabled: true,
|
|
},
|
|
});
|
|
```
|
|
|
|
With the npm package, the replay module is a dynamic import resolved by your bundler. It is automatically code-split from your main bundle—if you don't enable replay, the module is never included.
|
|
|
|
### Next.js
|
|
|
|
For Next.js, enable replay in your `OpenPanelComponent`:
|
|
|
|
```tsx title="app/layout.tsx"
|
|
import { OpenPanelComponent } from '@openpanel/nextjs';
|
|
|
|
export default function RootLayout({ children }) {
|
|
return (
|
|
<html lang="en">
|
|
<body>
|
|
<OpenPanelComponent
|
|
clientId="YOUR_CLIENT_ID"
|
|
trackScreenViews={true}
|
|
sessionReplay={{
|
|
enabled: true,
|
|
}}
|
|
/>
|
|
{children}
|
|
</body>
|
|
</html>
|
|
);
|
|
}
|
|
```
|
|
|
|
## Configure privacy controls [#privacy]
|
|
|
|
Session replay captures real user behavior, so it's important to control what gets recorded. OpenPanel gives you several layers of control.
|
|
|
|
### Input masking (enabled by default)
|
|
|
|
All form input values are masked by default. The recorder sees that a user typed something, but not what they typed. You never need to add special attributes to password or credit card fields—they're masked automatically.
|
|
|
|
If you need to disable masking for a specific use case:
|
|
|
|
```ts
|
|
sessionReplay: {
|
|
enabled: true,
|
|
maskAllInputs: false,
|
|
}
|
|
```
|
|
|
|
### Block sensitive elements
|
|
|
|
Elements with `data-openpanel-replay-block` are replaced with a grey placeholder in the replay. The element and all its children are completely excluded from recording.
|
|
|
|
```html
|
|
<!-- This section will appear as a placeholder in replays -->
|
|
<div data-openpanel-replay-block>
|
|
<img src="user-avatar.jpg" alt="Profile photo" />
|
|
<p>Private user content</p>
|
|
</div>
|
|
```
|
|
|
|
You can also configure a CSS selector or class to block without adding data attributes to every element:
|
|
|
|
```ts
|
|
sessionReplay: {
|
|
enabled: true,
|
|
blockSelector: '.payment-form, .user-profile-card',
|
|
blockClass: 'no-replay',
|
|
}
|
|
```
|
|
|
|
### Mask specific text
|
|
|
|
To mask text within an element without blocking its layout from the replay, use `data-openpanel-replay-mask`:
|
|
|
|
```html
|
|
<p>
|
|
Account balance:
|
|
<span data-openpanel-replay-mask>$1,234.56</span>
|
|
</p>
|
|
```
|
|
|
|
The span's text appears as `***` in the replay while the surrounding layout remains visible.
|
|
|
|
Configure a custom selector to avoid adding attributes to every element:
|
|
|
|
```ts
|
|
sessionReplay: {
|
|
enabled: true,
|
|
maskTextSelector: '.balance, .account-number, [data-pii]',
|
|
}
|
|
```
|
|
|
|
### Ignore interactions
|
|
|
|
Use `ignoreSelector` to prevent interactions with specific elements from being captured. The element is still visible in the replay, but clicks and input events on it are not recorded.
|
|
|
|
```ts
|
|
sessionReplay: {
|
|
enabled: true,
|
|
ignoreSelector: '.internal-debug-toolbar',
|
|
}
|
|
```
|
|
|
|
## View replays in the dashboard [#view]
|
|
|
|
Navigate to your [OpenPanel dashboard](https://dashboard.openpanel.dev) and open the Sessions view. Any recorded session will show a replay button. Click it to play back the session from the beginning.
|
|
|
|
The replay timeline shows all events alongside the recording, so you can jump directly to a click, form submission, or page navigation.
|
|
|
|
Replays are also accessible from user profiles. Open any user's profile, find a session in their history, and click through to the replay.
|
|
|
|
## Performance considerations
|
|
|
|
The replay recorder buffers events locally and sends them to OpenPanel in chunks every 10 seconds (configurable via `flushIntervalMs`). On tab close or page hide, any remaining buffered events are flushed immediately.
|
|
|
|
The default chunk size limits are:
|
|
- **200 events per chunk** (`maxEventsPerChunk`)
|
|
- **1 MB per payload** (`maxPayloadBytes`)
|
|
|
|
These defaults work well for most sites. If you have pages with heavy DOM activity, you can lower `maxEventsPerChunk` to send smaller, more frequent chunks:
|
|
|
|
```ts
|
|
sessionReplay: {
|
|
enabled: true,
|
|
flushIntervalMs: 5000,
|
|
maxEventsPerChunk: 100,
|
|
}
|
|
```
|
|
|
|
## Next steps
|
|
|
|
- Read the [session replay docs](/docs/session-replay) for a full option reference
|
|
- Learn about [session tracking](/features/session-tracking) to understand what session data is available without replay
|
|
- See how [funnels](/features/funnels) and session replay work together to diagnose drop-offs
|
|
|
|
<Faqs>
|
|
<FaqItem question="Does session replay affect my page load speed?">
|
|
No. The replay module (`op1-replay.js`) loads as a separate async script after the page and the main analytics script. It does not block rendering or inflate your main bundle.
|
|
</FaqItem>
|
|
|
|
<FaqItem question="Is session replay enabled for all users?">
|
|
Yes, when enabled, all sessions are recorded by default. You can use the `sampleRate` option to record only a percentage of sessions if needed.
|
|
</FaqItem>
|
|
|
|
<FaqItem question="Are passwords and credit card numbers recorded?">
|
|
No. All input field values are masked by default (`maskAllInputs: true`). The recorder captures that a user typed something, but not the actual characters. Disable this only with a specific reason.
|
|
</FaqItem>
|
|
|
|
<FaqItem question="How long are replays kept?">
|
|
Replays are retained for 30 days. There is no limit on the number of sessions recorded.
|
|
</FaqItem>
|
|
|
|
<FaqItem question="Can I use session replay with self-hosted OpenPanel?">
|
|
Yes. The replay script is served from your self-hosted instance automatically. You can also use the `scriptUrl` option to load it from a custom CDN.
|
|
</FaqItem>
|
|
</Faqs>
|