How to add session replay to your website

This guide shows you how to turn on session replay in Pieowl. When you finish, you'll record real user sessions and play them back in the dashboard.

Session replay records clicks, scrolls and page changes as data, not as video. Privacy controls are built in. The replay code loads on its own, after the main script, so it doesn't slow down your analytics.

Prerequisites

• A Pieowl account
• Your Client ID from the Pieowl dashboard
• Either the @pieowl/web npm package, or a way to add a script tag to your site

Install Pieowl

If you're starting fresh, add the Pieowl script tag to your page. If Pieowl is already installed, skip to the next step.

<script src="https://pieowl.com/pieowl.js" data-client-id="YOUR_CLIENT_ID" defer></script>

Or with npm:

npm install @pieowl/web

See the Web SDK docs or the Script tag docs for the full install guide.

Enable session replay

Session replay is off by default. You turn it on per site in the dashboard, with no code to edit:

1. Open Settings → Site → What Pieowl counts.
2. Turn on Session replay.
3. Choose Visits recorded: every visit, 50%, 25% or 10% of visits. On busy sites, fewer recordings keep the list short.

The script loads these settings on every page, so a change reaches your site within about a minute. The one-line script tag is enough. The replay script (pieowl-replay.js) is loaded for you from the same place as pieowl.js. It loads async, so it doesn't affect page load time or the size of the main script.

With the npm package, your bundler loads the replay code as a separate chunk. If replay is off, that chunk is never loaded.

Hide parts of the page

Session replay records real user behavior, so privacy is built in.

Text and form fields are always hidden

All text on the page and every form field value are hidden. In the replay, letters show as *, while the layout stays visible. The replay shows that a user typed something, but not what they typed. You don't need to mark password or card fields. This can't be turned off, in the dashboard or in code.

Images still show. To hide them, block them.

Block sensitive elements

Elements with data-pieowl-replay-block show as an empty placeholder in the replay. The element and everything inside it are left out of the recording.

<!-- This section shows as a placeholder in replays -->
<div data-pieowl-replay-block>
  <img src="user-avatar.jpg" alt="Profile photo" />
  <p>Private user content</p>
</div>

You can also block by CSS selector or class, so you don't have to add an attribute to every element. Setting blockSelector replaces the default selector, so keep [data-pieowl-replay-block] in the list. These options go in sessionReplay, in the init form or in new Pieowl({...}):

sessionReplay: {
  blockSelector: '[data-pieowl-replay-block], .payment-form, .user-profile-card',
  blockClass: 'no-replay',
}

Ignore interactions

Use ignoreSelector to stop recording input on certain elements. The element still shows in the replay, but what users type into it is not recorded.

sessionReplay: {
  ignoreSelector: '.internal-debug-toolbar',
}

View replays in the dashboard

Open the Pieowl dashboard and go to People → Visitors → Visits. Visits with a recording have a Replay chip. Open one and click Watch replay to play it back from the start.

The timeline shows the session's events next to the recording, so you can jump straight to a click, a form submit or a page change.

Performance considerations

The recorder keeps events in the browser and sends them to Pieowl in chunks every 10 seconds. You can change this with flushIntervalMs. When the tab is hidden or closed, it sends what's left right away.

The default chunk limits are:

• 200 events per chunk (maxEventsPerChunk)
• 1 MB per chunk (maxPayloadBytes)

These defaults work for most sites. If your pages change a lot, lower maxEventsPerChunk to send smaller chunks more often:

sessionReplay: {
  flushIntervalMs: 5000,
  maxEventsPerChunk: 100,
}

Next steps

• Read the session replay docs for every option in code
• Learn about session tracking to see what session data you get without replay
• See how funnels and session replay work together to explain drop-offs