pieowlDocs
pieowl.comSign inStart free trial
Session Replay

Session Replay

Record and replay user sessions in Pieowl to see exactly what users did. Text and form fields are always hidden, and the recorder loads only when you turn it on.

View as Markdown

Session replay records what users do on your website. You can replay any session to see what they clicked, how they filled in forms, and where they got stuck, without guessing.

Session replay is off by default. You turn it on per site in the dashboard, with no code to edit. When it's off, the replay script is never downloaded, so your analytics script stays small.

How it works

Pieowl session replay is built on rrweb, a widely used library for recording and replaying web sessions. It captures page changes, mouse movements, scroll positions and clicks as structured data, not video.

The recorder loads asynchronously as a separate script (pieowl-replay.js). This means:

  • The main tracking script (pieowl.js) stays small, with or without replay
  • The recorder is only downloaded for sessions that are actually recorded
  • Page load speed isn't affected when replay is off

Retention

Replays are kept for 30 days, then deleted automatically.

Setup

  1. Install Pieowl. The one-line script tag or the @pieowl/web package is enough.
  2. In the dashboard, open Settings → Site → What Pieowl counts and turn on Session replay.
  3. Keep Record only after visitors agree on (it's on by default), and call allowReplay when a visitor accepts in your consent banner. See Consent.
  4. Choose Visits recorded: every visit, 50%, 25% or 10% of visits. Fewer recordings keep the list short on busy sites.

The script loads these settings on every page. A change reaches your site within about a minute. When replay is off for a site, Pieowl drops any recordings sent for it.

With the npm package, your bundler splits the recorder into its own chunk. It's never part of your main bundle, and it's only loaded when session replay is on.

Watching replays

Go to People → Visitors → Visits. Visits with a recording have a Replay chip. Open a visit and click Watch replay.

Options in code

Most sites need none of these. To use them, add sessionReplay to the init form or to new Pieowl({...}). They don't turn replay on; that's done in the dashboard.

OptionTypeDefaultDescription
blockSelectorstring[data-pieowl-replay-block]CSS selector for elements to replace with a placeholder
blockClassstring—Class name that blocks elements from being recorded
ignoreSelectorstring—CSS selector for elements whose interactions aren't recorded
flushIntervalMsnumber10000How often (ms) recorded data is sent to the server
maxEventsPerChunknumber200Maximum number of recorded events per chunk
maxPayloadBytesnumber1048576Maximum chunk size in bytes (1 MB)
scriptUrlstring—Custom URL for the replay script (script tag only)

Privacy controls

All text and form fields are always hidden. Each character is replaced with * in the browser, before anything is sent. Page text, labels and input values show up as *** in replays, while the layout stays visible. This can't be turned off, in the dashboard or in code.

So replays can't capture names, emails or other personal data shown as text on the page. Images still show. To hide one, such as a photo of a face, block it.

Blocking elements

Elements that match blockSelector or blockClass show up as a grey placeholder of the same size. The element and everything inside it are never recorded.

html
<div data-pieowl-replay-block>
  This section won't appear in replays at all
</div>

Or use your own selector:

ts
sessionReplay: {
  blockSelector: '.payment-form, .user-avatar',
  blockClass: 'no-replay',
}

Setting blockSelector replaces the default, so add [data-pieowl-replay-block] to your selector if you still want the attribute to work.

Ignoring interactions

Use ignoreSelector to skip interactions on some elements. The element still shows in the replay, but clicks and typing on it aren't recorded.

ts
sessionReplay: {
  ignoreSelector: '.debug-panel',
}

Recording visits needs your visitors' consent. Ask for it in your own consent banner, and name Pieowl session replay in your privacy policy.

With Record only after visitors agree on, Pieowl records nothing until your site calls allowReplay after the visitor accepts:

js
// Script tag
window.pieowl('allowReplay');

// npm package
pieowl.allowReplay();

Pieowl stores nothing in the browser, so call it on every page where the visitor has agreed. If they decline, don't call it. See Consent management and Do you need a cookie banner?.

Custom script URL

The script tag loads the recorder from next to pieowl.js: it swaps .js for -replay.js in the script URL. If you serve pieowl.js from your own domain, put pieowl-replay.js next to it. You can also set the URL yourself:

ts
sessionReplay: {
  scriptUrl: 'https://your-cdn.example.com/pieowl-replay.js',
}