Session Replay

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

npm install @browserbasehq/sdk tsx

npm install @browserbasehq/sdk tsx

Be sure to create a virtual environment, activate it, and install the dependencies in it.

python -m venv venv
source venv/bin/activate
pip install browserbase playwright

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.

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));

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));

from playwright.sync_api import Playwright, sync_playwright
from browserbase import Browserbase
import os

BROWSERBASE_API_KEY = os.getenv("BROWSERBASE_API_KEY")
BROWSERBASE_PROJECT_ID = os.getenv("BROWSERBASE_PROJECT_ID")

bb = Browserbase(api_key=BROWSERBASE_API_KEY)

def run(playwright: Playwright) -> None: # Create a session on Browserbase
    session = bb.sessions.create(project_id=BROWSERBASE_PROJECT_ID)

    # Connect to the remote session
    chromium = playwright.chromium
    browser = chromium.connect_over_cdp(session.connect_url)
    context = browser.contexts[0]
    page = context.pages[0]

    try:
        # Navigate to the Browserbase docs and wait for 10 seconds
        page.goto("https://docs.browserbase.com/")
        page.wait_for_timeout(10000)
    finally:
        page.close()
        browser.close()

    print(f"Session complete! View replay at https://browserbase.com/sessions/{session.id}")

if __name__ == "__main__":
    with sync_playwright() as playwright:
        run(playwright)

Run the script

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.

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

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

# Get the session logs for the given session id
logs = bb.sessions.logs.list(session.id)
print(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.

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

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

# Get the session replay for the given session id
replay = bb.sessions.recording.retrieve(session.id)
print(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();

Multitab Workflows

Our browser recording feature is only designed for single tab workflows. In multi-tab environments, replays are unreliable as recording events can collide.

For multi-tab recordings, we recommend capturing screenshots as you go, and stitching them together as a video or gif. Alternatively, we support multiple tab workflows with our Live View.

Debugging Replays

rrweb vs video

Session Replays aren’t video files. Rather, we use a history of the DOM to rebuild your session - like hydrating a session at replay-time.

This lightweight approach is how we’re able to offer session replays for free. However, this live rebuild has caveats:

Some dynamic or obfuscated content (like iframes) might look different in the replay than during the session
Skipping around the replay timeline might introduce glitches (we have playback speed controls to help)
If the replay checks the geolocation, it will show the current IP address, not the IP address used during the session
Multiple tabs aren’t supported

Debugging Options

If the session did not record properly, two options are:

Run the session again
Use our Live View for real-time debugging

Other helpful points to keep in mind while debugging:

Recordings are available about 30 seconds after session close
Recordings are disabled on a few sites, like Opentable and the Salesforce family of sites

Questions or stuck? Contact us anytime at support@browserbase.com 🅱️

Introduction

Fundamentals

Features

Use Cases

Guides

Integrations

Overview

Install the Browserbase SDK

Create your script to record a session and view the replay

Run the script

Session Replay and Metrics

Timeline

DOM

Console Logs

Network Events

Session Logs

Session Recordings

Retrieve Session Recordings

Integrating the Recording Player

Using the rrweb Player Component

Using an Iframe Container

Working with Session Events

Multitab Workflows

Debugging Replays

rrweb vs video

Debugging Options

Introduction

Fundamentals

Features

Use Cases

Guides

Integrations

​Overview

​Install the Browserbase SDK

​Create your script to record a session and view the replay

​Run the script

​Session Replay and Metrics

​Timeline

​DOM

​Console Logs

​Network Events

​Session Logs

​Session Recordings

​Retrieve Session Recordings

​Integrating the Recording Player

​Using the rrweb Player Component

​Using an Iframe Container

​Working with Session Events

​Multitab Workflows

​Debugging Replays

​rrweb vs video

​Debugging Options

Overview

Install the Browserbase SDK

Create your script to record a session and view the replay

Run the script

Session Replay and Metrics

Timeline

DOM

Console Logs

Network Events

Session Logs

Session Recordings

Retrieve Session Recordings

Integrating the Recording Player

Using the rrweb Player Component

Using an Iframe Container

Working with Session Events

Multitab Workflows

Debugging Replays

rrweb vs video

Debugging Options