Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

Session replay docs

Blue Mousec2ecdb6ec024
diff --git a/docs/content/docs/add-script.mdx b/docs/content/docs/add-script.mdx
index 0d666b5b5..75cc7b77f 100644
--- a/docs/content/docs/add-script.mdx
+++ b/docs/content/docs/add-script.mdx
@@ -49,6 +49,8 @@ It's important to remember to replace `YOUR_PROJECT_ID` with your actual Project
Done. Now you can start using Swetrix on your website.
+To record session replays, start the recorder from your site code after initialising Swetrix. See [`startSessionReplay()`](/swetrix-js-reference#startsessionreplay) for setup and privacy options.
+
</TabsContent>
<TabsContent value="npm">
@@ -83,6 +85,8 @@ Swetrix.init("YOUR_PROJECT_ID");
Swetrix.trackViews();
```
+To record session replays, call `Swetrix.startSessionReplay()` after `Swetrix.init()`. See [`startSessionReplay()`](/swetrix-js-reference#startsessionreplay) for setup and privacy options.
+
</Step>
</Steps>
diff --git a/docs/content/docs/analytics-dashboard/error-tracking.mdx b/docs/content/docs/analytics-dashboard/error-tracking.mdx
index eb3448204..35225d1af 100644
--- a/docs/content/docs/analytics-dashboard/error-tracking.mdx
+++ b/docs/content/docs/analytics-dashboard/error-tracking.mdx
@@ -67,7 +67,9 @@ Clicking on any error in the list opens the **Error Details** view. This page pr
This section lists individual user sessions where this specific error occurred.
- You can see the user's country, browser, and operating system.
-- Clicking on a session redirects you to the specific **Session Replay** or session details, allowing you to see the user's journey leading up to the crash.
+- Clicking on a session opens the session details. If a replay was recorded, click **Watch replay** to see the user's journey leading up to the crash.
+
+Learn more about replay playback in the [Session Replays](/analytics-dashboard/session-replays) documentation.
### Segmentation & Breakdown
diff --git a/docs/content/docs/analytics-dashboard/meta.json b/docs/content/docs/analytics-dashboard/meta.json
index 6e613cbf2..771d45e25 100644
--- a/docs/content/docs/analytics-dashboard/meta.json
+++ b/docs/content/docs/analytics-dashboard/meta.json
@@ -8,6 +8,7 @@
"funnels",
"alerts",
"profiles-and-sessions",
+ "session-replays",
"error-tracking",
"goals",
"feature-flags",
diff --git a/docs/content/docs/analytics-dashboard/profiles-and-sessions.mdx b/docs/content/docs/analytics-dashboard/profiles-and-sessions.mdx
index 159bbadab..f79987f8f 100644
--- a/docs/content/docs/analytics-dashboard/profiles-and-sessions.mdx
+++ b/docs/content/docs/analytics-dashboard/profiles-and-sessions.mdx
@@ -61,6 +61,7 @@ For each session, you can see:
- **Duration**: How long the session lasted.
- **Entry & Exit Pages**: Where they started and ended their session.
- **Timeline**: A step-by-step log of every pageview and custom event within that session.
+- **Session Replay**: If a replay was recorded for the session, use **Watch replay** to open the replay player and review what the visitor saw and did.
This "User Journey" view is incredibly powerful for:
@@ -73,6 +74,8 @@ While the **Profiles** tab groups activity by user, the **Sessions** tab lists a
Use this view when you want to analyze global session trends or spot anomalies across the entire user base, rather than focusing on specific individuals.
+Sessions with an available replay show a replay indicator in the list. Open the session details and click **Watch replay** to view the recording, or use the dedicated [Session Replays](/analytics-dashboard/session-replays) tab to browse all recorded replays for the selected date range.
+
### Accessing Sessions from Charts
You can also quickly access a filtered list of sessions for a specific time period directly from the main Traffic chart. Simply click on any data point on the chart to pull up the sessions that occurred during that exact interval (e.g., a specific day or hour).
diff --git a/docs/content/docs/analytics-dashboard/session-replays.mdx b/docs/content/docs/analytics-dashboard/session-replays.mdx
new file mode 100644
index 000000000..d4794a9fa
--- /dev/null
+++ b/docs/content/docs/analytics-dashboard/session-replays.mdx
@@ -0,0 +1,92 @@
+---
+title: Session Replays
+slug: /analytics-dashboard/session-replays
+---
+
+<Callout type="info" title="Cloud Exclusive">
+ Session replays are exclusively available on **Swetrix Cloud**. They are not currently available
+ for self-hosted instances.
+</Callout>
+
+Session Replays let you watch recorded browser sessions alongside the analytics context Swetrix already collects. Use them to debug confusing journeys, reproduce issues, review funnel drop-offs, and understand what happened before an error or conversion.
+
+<Callout type="info">
+ Session replays are only recorded after your website calls
+ [`startSessionReplay()`](/swetrix-js-reference#startsessionreplay). A regular pageview or custom
+ event does not automatically create a replay.
+</Callout>
+
+## Recording replays
+
+To collect replays, install the Swetrix tracking script as usual, initialise it with your Project ID, and call `startSessionReplay()` when you want recording to begin.
+
+```javascript
+swetrix.init("YOUR_PROJECT_ID", {
+ sessionReplay: true,
+});
+
+await swetrix.startSessionReplay({
+ privacy: "normal",
+});
+```
+
+The optional `sessionReplay: true` setting preloads the replay recorder. Recording still begins only after `startSessionReplay()` is called.
+
+See the [tracking script reference](/swetrix-js-reference#startsessionreplay) for all privacy modes, recorder options, and code examples.
+
+## Replays list
+
+Open the **Replays** tab in your project dashboard to see recorded sessions for the selected date range.
+
+Each replay row shows:
+
+- The profile or anonymous visitor.
+- Country, operating system, and browser.
+- Replay event count, pageviews, custom events, revenue, and errors.
+- Replay start time and duration.
+- Expiry date, when retention metadata is available.
+
+Use dashboard filters to narrow the list by the same dimensions available elsewhere in analytics, such as country, browser, operating system, page, traffic source, campaign, or custom event.
+
+The row actions let you:
+
+- **Watch replay**: open the replay player.
+- **View session**: open the session details and full event/page timeline.
+- **Go to profile**: open the visitor profile when the replay is associated with a profile.
+
+## Replay player
+
+The replay player opens in a modal so you can review the recorded session without leaving the dashboard.
+
+Available controls include:
+
+- Play, pause, and scrub through the replay timeline.
+- Hover the timeline to preview a point in the replay.
+- Change playback speed.
+- Toggle the replay event timeline.
+- Capture the current frame as a PNG screenshot.
+- Export the replay as an MP4.
+- Enter fullscreen mode.
+
+If a replay has no events, has expired, or cannot be loaded, the player shows an empty or error state instead of the recording.
+
+## Session and error context
+
+Replays are connected to sessions. In the **Sessions** list, sessions with an available replay show a replay indicator with duration and expiry details. Opening that session shows a **Watch replay** button in the session detail panel.
+
+Error details can also point you toward the sessions that experienced a specific issue. When a replay exists for one of those sessions, use it to see what the visitor did before the error happened.
+
+## Privacy and retention
+
+Choose the privacy mode in code when you start the replay:
+
+- `total`: masks all text and inputs, and blocks media/canvas content.
+- `normal`: masks all inputs. This is the default.
+- `free-love`: only forces password inputs to stay masked unless you add your own recorder masking options.
+
+Configure replay retention in **Project Settings > Session replays**. Retention changes apply only to newly recorded replay chunks; existing replay chunks keep the expiry date they were recorded with.
+
+<Callout type="warn">
+ Review your privacy policy, consent flow, and masking settings before recording replays on pages
+ that may contain personal, financial, health, authentication, or other sensitive data.
+</Callout>
diff --git a/docs/content/docs/script-reference.mdx b/docs/content/docs/script-reference.mdx
index d14773305..fda3a9bf3 100644
--- a/docs/content/docs/script-reference.mdx
+++ b/docs/content/docs/script-reference.mdx
@@ -25,16 +25,18 @@ swetrix.init("YOUR_PROJECT_ID", {
respectDNT: false,
apiURL: "https://api.swetrix.com/log",
profileId: "user-123",
+ sessionReplay: true,
});
```
-| Name | Description | Default value |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
-| devMode | When set to `true`, localhost events will be sent to server. | `false` |
-| disabled | When set to true, the tracking library won't send any data to server.<br />Useful for development purposes when this value is set based on '.env' var. | `false` |
-| respectDNT | By setting this flag to true, we will not collect ANY kind of data about the user with the DNT setting. <br />This setting is not true by default because our service anonymises all incoming data and does not pass it on to any third parties under any circumstances. | `false` |
-| apiURL | If you use Swetrix Cloud, you don't need to change this parameter. If you're self-hosting Swetrix CE, you should put the URL of your API instance here, like `[BASE_URL]/backend/v1/log`. | `'https://api.swetrix.com/log'` |
-| profileId | Optional profile ID for long-term user tracking (MAU/DAU). If set, it will be used for all pageviews and events unless overridden per-call. This allows you to track users across sessions and devices. | `undefined` |
+| Name | Description | Default value |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
+| devMode | When set to `true`, localhost events will be sent to server. | `false` |
+| disabled | When set to true, the tracking library won't send any data to server.<br />Useful for development purposes when this value is set based on '.env' var. | `false` |
+| respectDNT | By setting this flag to true, we will not collect ANY kind of data about the user with the DNT setting. <br />This setting is not true by default because our service anonymises all incoming data and does not pass it on to any third parties under any circumstances. | `false` |
+| apiURL | If you use Swetrix Cloud, you don't need to change this parameter. If you're self-hosting Swetrix CE, you should put the URL of your API instance here, like `[BASE_URL]/backend/v1/log`. | `'https://api.swetrix.com/log'` |
+| profileId | Optional profile ID for long-term user tracking (MAU/DAU). If set, it will be used for all pageviews and events unless overridden per-call. This allows you to track users across sessions and devices. | `undefined` |
+| sessionReplay | Set to `true` to preload the session replay recorder after `init()`, or pass `{ rrwebUrl: "https://example.com/rrweb.min.js" }` to load it from a custom URL. Recording only starts after you call `startSessionReplay()`. | `undefined` |
## track()
@@ -233,6 +235,68 @@ swetrix.trackError({
});
```
+## startSessionReplay()
+
+This function starts recording the current browser session so you can watch it later in the [Session Replays](/analytics-dashboard/session-replays) tab.
+
+<Callout type="warn">
+ Session replays may capture page content, user interactions, and non-password input values
+ depending on the privacy mode you choose. Do not record sensitive pages unless you have reviewed
+ your masking settings, consent requirements, and legal basis for collecting this data.
+</Callout>
+
+Call `startSessionReplay()` after `init()`. If you set `sessionReplay: true` in `init()`, Swetrix preloads the recorder first so starting a replay is faster. If you do not preload it, `startSessionReplay()` loads the recorder when it is called.
+
+```javascript
+swetrix.init("YOUR_PROJECT_ID", {
+ sessionReplay: true,
+});
+
+const replay = await swetrix.startSessionReplay({
+ privacy: "normal",
+});
+
+await replay.stop();
+```
+
+When using the npm package:
+
+```javascript
+import { init, startSessionReplay } from "swetrix";
+
+init("YOUR_PROJECT_ID", {
+ sessionReplay: true,
+});
+
+const replay = await startSessionReplay({
+ privacy: "normal",
+});
+```
+
+| Name | Description | Default value |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| privacy | Controls how much page content is masked. Use `total` to mask all text and inputs and block media/canvas content, `normal` to mask all inputs, or `free-love` to only force password inputs to stay masked unless you add your own `rrweb` masking options. | `normal` |
+| rrweb | Advanced recorder options passed to `rrweb.record()`. If you provide an `emit` callback, Swetrix will call it and still upload replay events. | `undefined` |
+| flushIntervalMs | How often replay events are uploaded while recording. | `5000` |
+| maxEventsPerChunk | The maximum number of replay events to batch before Swetrix uploads a chunk immediately. | `100` |
+
+The function returns a `Promise` with controls for the active replay:
+
+```javascript
+{
+ flush() {},
+ stop() {},
+}
+```
+
+`flush()` uploads any queued replay events immediately. `stop()` stops recording, flushes pending events, and ends the local recorder for this page.
+
+<Callout type="info">
+ Session replay tracking follows the same `disabled`, `respectDNT`, localhost, and
+ automated-browser checks as regular analytics. On Swetrix Cloud, the project must also have
+ session replays available on its plan and quota.
+</Callout>
+
## getFeatureFlags()
Fetches all feature flags for the project. Results are cached for 5 minutes by default. This cache is shared with experiment assignments.
diff --git a/docs/content/docs/sitesettings/project-configuration.mdx b/docs/content/docs/sitesettings/project-configuration.mdx
index 25fbe8d35..5d9e5efc9 100644
--- a/docs/content/docs/sitesettings/project-configuration.mdx
+++ b/docs/content/docs/sitesettings/project-configuration.mdx
@@ -51,6 +51,14 @@ Swetrix has built-in bot detection. You can choose how aggressively bot and auto
Below the dropdown you'll find a per-project **Blocked traffic** report showing how many requests were filtered out, broken down by classification and country. See the dedicated [Bot Protection](/bot-protection) page for the full list of detection methods, privacy notes, and FAQ.
+## Session Replays
+
+The **Session replays** tab controls how long newly recorded replay chunks are retained for the project.
+
+Available retention periods depend on your plan. When you change the retention period, the new value applies only to replay chunks recorded after the change. Existing replay chunks keep the expiry date they were recorded with.
+
+See [Session Replays](/analytics-dashboard/session-replays) for setup, privacy modes, and playback details.
+
## Access Control
The **Access** tab manages who can see your dashboard and which organisation the project belongs to.