Browserbase provides Session Live URLs to easily:


Getting a Session Live URL

Request a Session Live URL using the Session Live URLs endpoint or SDKs:

1

Start a Session

Use the Session API to create a new session.

2

Request a Session Live URL

Then, use the Session API Live URLs endpoint to get the debuggerFullscreenUrl.


Debug a running Session

Once a Session Live URL is retrieved (ex: debuggerFullscreenUrl), open it with Chrome to start taking action.

Closing the tab will terminate the Session.

Give control over the Session to your end user

While Browserbase helps deal with common scraping problems (anti-bot mechanism, captchas, reliably download files), some scenarios remain hard to automate for technical or data-privacy reasons:

  • Dealing with iframes can be challenging as the loaded content might be external and could change without notice, adding another fold of scraping complexity. Interacting with iframes can be delegated to the end user by forwarding the remote control URL.

  • Dealing with user credentials is another complex scenario as the end-user might prefer to fill out their credentials directly on the website instead of storing them elsewhere.

Example

The below code sample showcases how to use a Session Live URL to hand the Session’s control to a user:

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

(async () => {
  const browserbase = new Browserbase();
  const { id } = await browserbase.createSession();

  const browser = await chromium.connectOverCDP(browserbase.connectUrl({ id }));

  // perform actions ...

  const { debuggerFullscreenUrl } =
    await browserbase.getDebugConnectionURLs(sessionId);

  // forward the `debuggerFullscreenUrl` to the user
})();

Integrate a live Session iframe within your application

The Session Live URLs can be used to integrate a live view of ongoing automation within your application.

For example, an application enabling users to configure advanced health checks based on pages’ content can benefit from allowing the users to see the health check recording in case of false positives.

Example

1

Store the Session ID of each automation run

Store the Session ID of each running Session by creating a Session using the Browserbase SDK to store it and pass it to the connect URL as follows:

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

(async () => {
  const browserbase = new Browserbase();
  const { id } = await browserbase.createSession();

  // TODO:  store the Session `id` to database

  const browser = await chromium.connectOverCDP(browserbase.connectUrl({ id }));

  // ...
})();
2

Request a debug connection URL by using the Session ID

If a user tries to access the live view of a running automation, retrieve the Session Live URLs as follows:


import { Browserbase } from "@browserbasehq/sdk";

const browserbase = new Browserbase();

// retrieve `sessionId` from the database

const { debuggerFullscreenUrl: debugConnectionURL } = await browserbase.getDebugConnectionURLs(sessionId)

// forward `debugConnectionURL` to the front-end

Let’s forward the debugConnectionURL to the front end to create the final live view with an iframe.

3

Integrate an iframe within your front-end

The front end will display a live running Session by loading the debugConnectionURL in a read-only iframe:

<iframe
  src="{debugConnectionURL}"
  sandbox="allow-same-origin allow-scripts"
  allow="clipboard-read; clipboard-write"
  style="pointer-events: none;"
/>
To enable your end users to interact with the live Session, remove the style='pointer-events: none;' line.

Handling disconnections

If the Session Live View loses it’s connection to the browser, the iFrame will post a message to the window for you to handle the new state.

window.addEventListener("message", function (event) {
  if (event.data === "browserbase-disconnected") {
    console.log("Message received from iFrame:", event.data);
    // Handle the disconnection logic here
  }
});