Session Replay

Replay a Session to inspect the actions performed and network requests

Overview

Session Replays are one of the most powerful features of Browserbase. It allows you to replay a Session to inspect the actions performed and network requests, page by page.

To learn more about how Session Replays works, we’ll walk through a quickstart guide to understand how Session Replays can be involved in your development workflow.

Let’s get started in viewing your first session replay immediately.

Install the Browserbase SDK

• Node.js
• Python

npm

npm install @browserbasehq/sdk tsx

Create your script to record a session and view the replay

Use your ideal framework to connect to a Browserbase session, navigate to the page you want to record, and then close the session.

• Node.js
• Python

Playwright

import { chromium } from "playwright-core";
import Browserbase from "@browserbasehq/sdk";

if (!process.env.BROWSERBASE_API_KEY || !process.env.BROWSERBASE_PROJECT_ID) {
  throw new Error("Missing required environment variables");
}

const BROWSERBASE_PROJECT_ID = process.env.BROWSERBASE_PROJECT_ID;
const BROWSERBASE_API_KEY = process.env.BROWSERBASE_API_KEY;

const bb = new Browserbase({
  apiKey: BROWSERBASE_API_KEY,
});

(async () => {
  // Create a new session
  const session = await bb.sessions.create({
    projectId: BROWSERBASE_PROJECT_ID,
  });

  // Connect to the session
  const browser = await chromium.connectOverCDP(session.connectUrl);

  // Getting the default context to ensure the sessions are recorded.
  const defaultContext = browser.contexts()[0];
  const page = defaultContext?.pages()[0];

  // Navigate to the Browserbase docs and wait for 10 seconds
  await page.goto("https://docs.browserbase.com/introduction");
  await page.waitForTimeout(10000);
  await page.close();
  await browser.close();

  // Log the session replay URL
  console.log(
    `Session complete! View replay at https://browserbase.com/sessions/${session.id}`,
  );
})().catch((error) => console.error(error.message));

Run the script

• Node.js
• Python

npx tsx index.ts

You should see this output in your terminal:

Session complete! View replay at https://browserbase.com/sessions/${session.id}

Session Replay and Metrics

A replay of each Session is featured in the Sessions page. This replay is a capture of the webpage, not a video, and can be inspected with your Chrome DevTools.

Here are some key takeaways:

• A high usage of memory or CPUs might result in longer runs and more billed minutes. Look at the logs or open a Live Session URL to pinpoint the root issue.
• In case of high proxy bandwidth usage, inspect the network requests using the Timeline described below.

Note that the replay length may not match the total session duration. This is because session timing starts when the browser begins running, while the replay recording only begins when the first page loads. The replay is a reconstruction of the DOM using rrweb events.

Timeline

The Timeline is simply a replay of the session that was ran. Like mentioned above, the replay is a reconstruction of the DOM using rrweb events.

DOM

The DOM tab shows a live representation of the webpage’s HTML structure during the session.

You can inspect the Document Object Model DOM to see the exact state of elements, their attributes, and how they’re nested within the page.

Console Logs

Logs emitted by the Web Console API (ex: console.log()), making debugging remote Sessions as easy as using your browser

Some example of console logs:

• browser-solving-started
• browser-solving-completed
• browserbase-keeping-connection-alive
• Starting recording

You’ll also be able to see other logs as expected from a browser, like [DOM] Updated style of [body] or [Network] Request finished loading: GET "https://example.com/style.css"

Network Events

Network events (Network), describing in detail any network requests and responses performed during Session

The Timeline also features logs emitted by the Web Console API (ex: console.log()), making debugging remote Sessions as easy as using your browser.

Logs can also be retrieved using the Sessions API for automated processing.

Session Logs

Session logs contain detailed information captured during a Browserbase session. This includes browser events, network requests, and other runtime data.

These logs provide insights into what occurred during the session’s execution.

To retrieve the logs of a session, you can use the Sessions API or the logs.list() method in the Browserbase SDK.

• Node.js
• Python

// Get the session logs for the given session id
const logs = await bb.sessions.logs.list(session.id);
console.log(logs);

These logs retrieved using the Browserbase SDK are the same as the ones featured in the Events tab of the Session Replay.

Session Recordings

Session recordings provide a representation of the session’s data, unique id, timestamp, and type of session.

You can learn more about session recordings with events in the rrweb documentation.

Retrieve Session Recordings

Let’s say you have a session ID and you want to retrieve the recordings for that session. You can do so by using the recording.retrieve() method in the Browserbase SDK.

• Node.js
• Python

// Get the session replay for the given session id
const replay = await bb.sessions.recording.retrieve(session.id);
console.log(replay);

Integrating the Recording Player

Often times, you’ll want to integrate a recording player in your application. This is a simple process that can be done in a few steps.

Since session recordings are a culmination of rrweb events captured during the session, you can integrate a recording player into your application to replay these events.

Using the rrweb Player Component

If using a frontend framework like Next.js, you can use the rrwebPlayer component for displaying the session replay in your application.

You can create a reusable component that accepts session recording events as props and renders the rrweb player:

import rrwebPlayer from "rrweb-player";
import "rrweb-player/dist/style.css";

// Initialize the player with your session recording
new rrwebPlayer({
  target: document.body,
  props: {
    events: recording.events,
    width: 1024,
    height: 576,
  },
});

Using an Iframe Container

For simpler integrations, you can embed the recording player in an iframe as well:

<iframe
  src="/replay/${sessionId}"
  width="100%"
  height="600px"
  frameborder="0"
  allow="fullscreen"
></iframe>

The iframe approach requires you to host a separate page that initializes the rrweb player. Make sure to handle proper session authentication and access control.

Working with Session Events

You can use the events prop to pass session recording events to the rrweb player:

import rrwebPlayer from "rrweb-player";
import "rrweb-player/dist/style.css";

new rrwebPlayer({
  target: document.body,
  props: {
    events: recording.events,
    width: 1024, // Player width in pixels
    height: 576, // Player height in pixels
    skipInactive: true, // Skip inactive time periods
    showController: true, // Show playback controls
    autoPlay: false, // Start playing automatically
  },
});

The player emits events you can listen to, including ‘play’, ‘pause’, and ‘finish’ events that help you track the playback state:

const player = new rrwebPlayer({
  target: document.body,
  props: { events: recording.events },
});

player.addEventListener("play", () => console.log("Started"));
player.addEventListener("pause", () => console.log("Paused"));
player.addEventListener("finish", () => console.log("Finished"));

// Control playback
player.goto(5000); // Jump to 5 seconds
const currentTime = player.getCurrentTime();

Always be sure to destroy the player when it is no longer needed:

player.destroy();