Using Session Recordings
Incorporate browser session replay and leverage session events.
The Sessions API exposes multiple endpoints to retrieve session data, including downloads, logs, and recordings. This guide shows how a recording can be used to integrate session replay into your app. You can also use it to process specific events from the session.
Retrieve recordings using the Browserbase SDK
A session recording is a series of rrweb events that may include user interactions such as mouse clicks or typing into a text box, DOM mutations, or CSS transitions. These events are ordered chronologically and comprise the core data structure that rrweb uses for session recording and replay.
Recordings can be retrieved via the Sessions API or by using the SDK as shown here:
Install the SDK
Import and initialize the SDK
Before using the SDK, be sure to set your BROWSERBASE_API_KEY
and BROWSERBASE_PROJECT_ID
environment variables. To get your API key and project ID, refer to the Settings page in
your Dashboard as described in the Start your first Session Quickstart.
import { Browserbase } from "@browserbasehq/sdk";
// Provide the sessionId for the session recording of interest
const sessionId = 'fef4db93-9995-4147-be1c-27ebb0228ea6';
(async function main() {
const browserbase = new Browserbase()
const session = await browserbase.getSession(sessionId)
console.log(session.status) // -> 'COMPLETED'
})();
Retrieve the session recording data
import { Browserbase } from "@browserbasehq/sdk";
const sessionId = 'fef4db93-9995-4147-be1c-27ebb0228ea6';
(async function main() {
const browserbase = new Browserbase()
const data = await browserbase.getSessionRecording(sessionId)
})();
Session recordings are retained through the data retention period before being scheduled for automatic deletion. The duration is based on the plan you’ve chosen: * Hobby Plan: 7 days * Startup Plan: 30 days * Scale Plan: 90+ days, with the option to set a custom retention window.
Integrate a recording player in your app
rrweb provides a player used to replay session recordings, as shown here:
The rrweb player as it appears in action, replaying a browser session performing a Google search.
Install the rrweb-player package
rrweb also provides an rrweb
React package
allowing you to control the player from React components.
Instantiate the recording player
The rrweb player directly consumes session recording events. Here’s how to implement the player:
import rrwebPlayer from "rrweb-player";
import { Browserbase } from "@browserbasehq/sdk";
import "rrweb-player/dist/style.css";
const browserbase = new Browserbase();
// Provide the sessionId for the session recording of interest
const events = await browserbase.getSessionRecording(sessionId);
new rrwebPlayer({
target: document.body, // customizable root element
props: {
events,
},
});
The complete list of available options for rrwebPlayer()
can be found
here.
Working with session events
You can use session records to filter and process specific events. Each session recording event has the following format:
{
"id": "4b9e95fb-86d8-45ad-9143-c04f35eb9334",
"type": 0,
"timestamp": 1716989439884,
"data": {},
"sessionId": "fef4db93-9995-4147-be1c-27ebb0228ea6"
}
The type
property is an integer matching the following categories of events:
Type Value | Event Name |
---|---|
0 | DomContentLoaded |
1 | Load |
2 | FullSnapshot |
3 | IncrementalSnapshot |
4 | Meta |
5 | Custom |
6 | Plugin |
The IncrementalSnapshot
event describe an incremental page update. The specific kind of
IncrementalSnapshot
update can be found in its data.source
property (e.g. data.source: 5
indicates an input event).
Retrieving recording events
This example script retrieves a recording to collect user interactions during a hybrid web automation session—one that combines programmatic actions with live user actions—for subsequent processing:
import { Browserbase, SessionRecording } from "@browserbasehq/sdk";
import { EventType, IncrementalSource } from "@rrweb/types";
(async function main() {
const browserbase = new Browserbase();
// Provide the sessionId for the session recording of interest
const recordings = await browserbase.getSessionRecording(sessionId);
const userActions: SessionRecording[] = [];
for (let event of recordings) {
if (
event.type &&
event.type === EventType.IncrementalSnapshot &&
event.data
) {
// we want to keep track of any mouse or input events performed on the page
if (
[
IncrementalSource.Input,
IncrementalSource.MouseInteraction,
IncrementalSource.MouseMove,
].includes(event.data.source)
) {
userActions.push(event);
}
}
}
// ... store `userActions` for later use
})();
The complete list of IncrementalSnapshot
event types can be found
here.
Was this page helpful?