Browser Extensions

Augment your browser sessions with your own Chrome extensions.

For applications requiring enhanced functional capabilities, providing your own Chrome extension is a great option. With Browserbase, using extensions is easy.

Upload an extension

First, for the simplest example, refer to Upload an Extension API and execute the curl command. You should receive a response containing the extension’s id. Make sure to save that extensionId as you’ll need it to use when creating your session.

A more complete example is below:

Create and upload a custom extension

This Python script zips up a very simple Chrome extension, uploads it, and then stores the resulting extensionId in a text file for subsequent use in your session.

For this example, your Chrome extension will be a ZIP archive containing these two files, manifest.json and content-script.js:

You must upload a valid Chrome extension in a .zip file format containing a manifest.json at the root.

The file path to the extension should point to the zipped file. Do not unpack it. This file must be smaller than 4.5 MB.

In this script, the extension files are compressed into an in-memory ZIP archive. This is then uploaded to the Extensions API endpoint.

The extension’s new id is printed out and also stored in a text file, which can then be used to enable the extension on a per-session basis.

Python

import os
import zipfile
from io import BytesIO

import requests

API_KEY = os.environ["BROWSERBASE_API_KEY"]
EXTENSION_ID_FILE = "extension_id.txt"

# Location of the browser extension files. Must include a manifest.json
PATH_TO_FILES = "my_browser_extension"


def make_zip_buffer(path: str, save_local=False) -> BytesIO:
    """
    Create an in-memory zip file from the contents of the given folder.
    Mark save_local=True to save the zip file to a local file.
    """
    # Ensure we're looking at an extension
    assert "manifest.json" in os.listdir(
        path
    ), "No manifest.json found in the extension folder."

    # Create a BytesIO object to hold the zip file in memory
    memory_zip = BytesIO()

    # Create a ZipFile object
    with zipfile.ZipFile(memory_zip, "w", zipfile.ZIP_DEFLATED) as zf:
        # Recursively walk through the directory
        for root, dirs, files in os.walk(path):
            for file in files:
                # Create the full file path
                file_path = os.path.join(root, file)
                # Calculate the archive name (path relative to the root directory)
                archive_name = os.path.relpath(file_path, path)
                # Add the file to the zip
                zf.write(file_path, archive_name)

    if save_local:
        with open(f"{path}.zip", "wb") as f:
            f.write(memory_zip.getvalue())

    return memory_zip


def upload_extension(data: bytes) -> str:
    """
    Upload an extension contained within the given data.

    :returns: ID of the new extension, to be used in a Browserbase session.
    """
    extensions_url = "https://api.browserbase.com/v1/extensions"
    headers = {"X-BB-API-Key": API_KEY}

    files = {"file": ("extension.zip", data)}

    response = requests.post(extensions_url, files=files, headers=headers)

    # Raise an exception if there wasn't a good response from the endpoint
    response.raise_for_status()

    result: dict[str, str] = response.json()
    # Show what we got
    print("--- Response data from API:")
    print(*[f"{key:<15} = {value}" for key, value in result.items()], sep="\n")
    print("---")

    return result["id"]


if __name__ == "__main__":
    buffer = make_zip_buffer(PATH_TO_FILES)
    extension_id = upload_extension(buffer.getvalue())
    print(f"{extension_id=}")

    with open(EXTENSION_ID_FILE, "w") as id_file:
        id_file.write(extension_id)
        print(f'Wrote the extension ID to "{EXTENSION_ID_FILE}"')

Create a session using the extension

Once you’re ready to use your uploaded Chrome extension, create a new session and load the extension into the browser.

Create a new session using the Sessions API endpoint. To enable the extension, make sure to include your projectId and extensionId parameters in the request payload.

Starting a new session with an extension can increase the session creation time. The browser must be restarted to load the extension, which itself has nonzero load time.

Verify the extension is loaded and working

Then, verify that the extension is working correctly. This is done by checking for a specific change or behavior that your extension introduces. In this example, the page title should have been modified by the test extension.

• Python