Bright Data Best Practices

# Browser API (Scraping Browser) Reference

## Table of Contents

- [Overview](#overview)
- [Authentication](#authentication)
- [Connection Strings](#connection-strings)
- [Supported Frameworks](#supported-frameworks)
- [Session Rules](#session-rules)
- [Quick Start Examples](#quick-start-examples)
- [Custom CDP Functions](#custom-cdp-functions)
- [Geolocation Targeting](#geolocation-targeting)
- [Bandwidth Optimization](#bandwidth-optimization)
- [CAPTCHA Handling](#captcha-handling)
- [Debugging](#debugging)
- [Premium Domains](#premium-domains)
- [Error Codes](#error-codes)
- [Billing Model](#billing-model)
- [Best Practices](#best-practices)
- [Anti-Patterns](#anti-patterns)

---

## Overview

Bright Data Browser API (also called Scraping Browser) is a managed cloud browser service. It handles proxy management, fingerprinting, CAPTCHA solving, and bot detection bypass automatically. Use it when you need full browser automation: clicking, scrolling, form filling, JavaScript execution, or working with SPAs.

**When to use Browser API vs other APIs:**

| Need | Use |
|------|-----|
| Simple HTTP scraping, no interaction | Web Unlocker |
| Google/Bing search results | SERP API |
| Structured data from known platforms | Web Scraper API |
| Click, scroll, fill forms, run JS | **Browser API** |
| Intercept XHR/fetch calls from a page | **Browser API** |
| Handle complex anti-bot that requires browser | **Browser API** |
| Puppeteer/Playwright/Selenium automation | **Browser API** |

---

## Authentication

Get credentials from your Browser API zone's **Overview tab** in the Control Panel.

- **Username:** `brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}`
- **Password:** Your zone password

```bash
export BROWSER_AUTH="brd-customer-CUSTOMER_ID-zone-ZONE_NAME:PASSWORD"
```

---

## Connection Strings

| Framework | Connection Type | Endpoint |
|-----------|----------------|----------|
| Playwright | WebSocket | `wss://${AUTH}@brd.superproxy.io:9222` |
| Puppeteer | WebSocket | `wss://${AUTH}@brd.superproxy.io:9222` |
| Selenium | HTTPS | `https://${AUTH}@brd.superproxy.io:9515` |

Replace `${AUTH}` with `username:password`.

**Critical:** Wrong port = 407 error. Playwright/Puppeteer = port `9222`. Selenium = port `9515`.

---

## Supported Frameworks

- **Node.js:** Puppeteer, Playwright, Selenium WebDriver
- **Python:** Playwright, Selenium
- **C# (.NET):** PuppeteerSharp, Playwright, Selenium
- **Other languages:** Any language with CDP or WebDriver support (Ruby, Go, Java, etc.)

---

## Session Rules

- **One initial navigation per session.** After `page.goto(url)`, you can interact (click, scroll, evaluate) within the same page, but cannot navigate to a different URL in the same session. Start a new session for a new target.
- **Idle timeout:** Sessions inactive for **5+ minutes** automatically close.
- **Maximum duration:** Sessions cannot exceed **30 minutes**.
- **Password entry:** Disabled by default to protect non-public data. Contact Bright Data to enable.

---

## Quick Start Examples

### Playwright (Node.js)

```javascript
const { chromium } = require("playwright-core");

const AUTH = process.env.BROWSER_AUTH || "brd-customer-CUSTOMER_ID-zone-ZONE_NAME:PASSWORD";
const TARGET_URL = "https://example.com";

(async () => {
  const browser = await chromium.connectOverCDP(
    `wss://${AUTH}@brd.superproxy.io:9222`
  );
  const page = await browser.newPage();

  // Set navigation timeout to 2 minutes (recommended for complex unlocking)
  page.setDefaultNavigationTimeout(120000);

  await page.goto(TARGET_URL, { waitUntil: "domcontentloaded" });
  const html = await page.content();
  console.log(html);

  await browser.close();
})();
```

### Playwright (Python)

```python
import asyncio
from playwright.async_api import async_playwright

AUTH = "brd-customer-CUSTOMER_ID-zone-ZONE_NAME:PASSWORD"
TARGET_URL = "https://example.com"

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connec