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

Node.js
Python

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.

Node.js
Python

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

Node.js
Python

npx tsx index.ts

python main.py

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.

HAR Recording

HAR (HTTP Archive) files capture detailed network activity during your browser sessions. You can record HAR files using Playwright’s tracing feature, which provides comprehensive network data that can be analyzed or replayed.

Recording HAR Files

To record network activity as HAR data, use Playwright’s tracing functionality:

Node.js
Python

Playwright

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

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

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

const session = await bb.sessions.create({
  projectId: PROJECT_ID,
});

console.log("Starting remote browser...");
const browser = await chromium.connectOverCDP(session.connectUrl);
const defaultContext = browser.contexts()[0];
const page = defaultContext.pages()[0];

// Start HAR recording using routeFromHAR
console.log("Starting HAR recording...");
const harFile = `recording-${Date.now()}.har`;
await defaultContext.routeFromHAR(harFile, {
  url: "**/*",
  update: true,
  updateContent: "embed",
  updateMode: "full"
});

// Also start tracing to capture network activity locally
await defaultContext.tracing.start({
  screenshots: true,
  snapshots: true,
  sources: true
});

await page.goto("https://news.ycombinator.com/", {
  waitUntil: "domcontentloaded",
});

// Navigate to additional pages to capture more network data
await page.click('a[href*="item"]');
await page.waitForLoadState("domcontentloaded");
await page.goBack();
await page.waitForLoadState("domcontentloaded");

// Stop tracing and save the trace file
const traceFile = `trace-${Date.now()}.zip`;
await defaultContext.tracing.stop({ path: traceFile });
console.log(`Trace file saved as: ${traceFile}`);

await page.close();
await browser.close();

console.log(`HAR file saved as: ${harFile}`);
console.log(`Session complete! View replay at https://browserbase.com/sessions/${session.id}`);

Playwright

from playwright.sync_api import sync_playwright
from browserbase import Browserbase
import os
import time

PROJECT_ID = os.environ["BROWSERBASE_PROJECT_ID"]
API_KEY = os.environ["BROWSERBASE_API_KEY"]

bb = Browserbase(api_key=API_KEY)

def record_har(playwright):
    session = bb.sessions.create(project_id=PROJECT_ID)
    
    print("Starting remote browser...")
    browser = playwright.chromium.connect_over_cdp(session.connect_url)
    default_context = browser.contexts[0]
    page = default_context.pages[0]
    
    # Start HAR recording using routeFromHAR
    print("Starting HAR recording...")
    har_file = f"recording-{int(time.time())}.har"
    default_context.route_from_har(har_file, url="**/*", update=True, 
                                   update_content="embed", update_mode="full")
    
    # Also start tracing to capture network activity locally
    default_context.tracing.start(screenshots=True, snapshots=True, sources=True)
    
    page.goto("https://news.ycombinator.com/", wait_until="domcontentloaded")
    
    # Navigate to additional pages to capture more network data
    page.click('a[href*="item"]')
    page.wait_for_load_state("domcontentloaded")
    page.go_back()
    page.wait_for_load_state("domcontentloaded")
    
    # Stop tracing and save the trace file
    trace_file = f"trace-{int(time.time())}.zip"
    default_context.tracing.stop(path=trace_file)
    print(f"Trace file saved as: {trace_file}")
    
    page.close()
    browser.close()
    
    print(f"HAR file saved as: {har_file}")
    print(f"Session complete! View replay at https://browserbase.com/sessions/{session.id}")

with sync_playwright() as playwright:
    record_har(playwright)

Analyzing HAR Files

The trace file contains network activity that can be viewed and analyzed:

View in Playwright Trace Viewer: Use npx playwright show-trace trace-file.zip to view the captured network activity
Extract Network Data: The trace file contains detailed network requests, responses, and timing information
Replay Network Activity: Use the HAR data to replay network interactions for testing and debugging

Understanding HAR Data

HAR files capture:

Network Requests: All HTTP requests made during the session
Response Data: Complete response bodies and headers
Timing Information: Detailed timing for each network operation
Performance Metrics: Network performance and loading times

When using Browserbase’s remote browsers, HAR files created with routeFromHAR are stored on the remote instance. Use tracing to capture network data locally for analysis.

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

# 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.

Node.js
Python

// 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 [email protected] 🅱️

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

HAR Recording

Recording HAR Files

Analyzing HAR Files

Understanding HAR Data

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

​HAR Recording

​Recording HAR Files

​Analyzing HAR Files

​Understanding HAR Data

​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

HAR Recording

Recording HAR Files

Analyzing HAR Files

Understanding HAR Data

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