> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/headless-browser.md).

# Headless Browser

Headless Browser permite executar e controlar instâncias remotas para automação, testes e raspagem web baseados em navegador, sem gerenciá-las localmente. Ele oferece segurança adaptativa integrada, tratamento automático de CAPTCHA, geolocalização direcionada, proxies residenciais integrados, gravação de sessão, sessões persistentes e perfis persistentes.

## Bibliotecas compatíveis

Headless Browser funciona com qualquer biblioteca que suporte o **Chrome DevTools Protocol (CDP)**, incluindo:

* [Playwright](https://playwright.dev/) (Python e Node.js)
* [Puppeteer](https://pptr.dev/) (Node.js)
* Outros frameworks de automação compatíveis com CDP

## Detalhes da conexão

<table data-header-hidden><thead><tr><th width="160.5">Campo</th><th>Descrição</th></tr></thead><tbody><tr><td><strong>Protocolo</strong></td><td><code>wss://</code> (WebSocket Secure)</td></tr><tr><td><strong>Host (Chromium)</strong></td><td><code>ubc.oxylabs.io</code></td></tr><tr><td><strong>Autenticação</strong></td><td>Na URL, as informações do usuário – <code>wss://USERNAME:PASSWORD@host</code>. Deve incluir o token de sufixo do nome de usuário (ex.: <code>user_ab12</code>). Não há suporte para autenticação baseada em cabeçalho.</td></tr><tr><td><strong>Transporte</strong></td><td>CDP – <code>chromium.connectOverCDP</code> (Playwright) / <code>puppeteer.connect</code> (Puppeteer)</td></tr><tr><td><strong>Domínios</strong></td><td><code>oxylabs.io</code> – endpoints de conexão que você autentica e aos quais se conecta (ex.: <a href="http://ubc.oxylabs.io">ubc.oxylabs.io</a>)<br><code>headlesify.io</code> – painel, inspeção de sessão e gravações (ex.: <a href="http://dashboard.headlesify.io">dashboard.headlesify.io</a>, <a href="http://vnc.headlesify.io">vnc.headlesify.io</a>).</td></tr><tr><td><strong>Limites de taxa</strong></td><td><code>100</code> sessões simultâneas, <code>10</code> sessão por segundo. <a href="#need-a-feature-enabled-1">Saiba mais</a>.</td></tr></tbody></table>

## Recursos

Oxylabs Headless Browser inclui recursos nativos da nuvem integrados, projetados para serem usados por meio de parâmetros de consulta na URL da conexão WebSocket.

<table data-header-hidden><thead><tr><th width="250"></th><th></th></tr></thead><tbody><tr><td><a href="/pages/24e2a15e0ecd0c58cecacfb7b4f46c0539fbfde9"><strong>Tratamento de CAPTCHA</strong></a> </td><td>Tratamento e monitoramento automáticos de CAPTCHA em tempo real.</td></tr><tr><td><a href="/pages/26ff6594fa5b9d8e7cd7298fff9b980085e70132"><strong>Direcionamento de proxy e geolocalização</strong></a></td><td>Roteie sessões por países, estados ou cidades específicos.</td></tr><tr><td><a href="/pages/c77bb9fe0e43f869d2ad4d98cef632aa89c2de3d"><strong>Emulação de dispositivo</strong></a></td><td>Emule fingerprints e viewports específicos do dispositivo.</td></tr><tr><td><a href="/pages/285e2ede1fbc1737b41f1ae70b2bb49df6398532#session-inspection-vnc"><strong>Inspeção de sessão (VNC)</strong></a></td><td>Monitore sessões ao vivo do navegador sem interface.</td></tr><tr><td><a href="/pages/285e2ede1fbc1737b41f1ae70b2bb49df6398532#session-recording"><strong>Gravação de sessão</strong></a> </td><td>Grave sessões do navegador em formato de vídeo.</td></tr><tr><td><a href="/pages/440b117f14dcfc6c6fe2a8ab8664229a32a29bf3#persistent-sessions"><strong>Sessões persistentes</strong></a></td><td>Crie e gerencie instâncias persistentes do navegador.</td></tr><tr><td><a href="/pages/440b117f14dcfc6c6fe2a8ab8664229a32a29bf3#persistent-profiles"><strong>Perfis persistentes</strong></a></td><td>Salve e restaure cookies/localStorage entre sessões. <em>(</em><a href="#need-a-feature-enabled-1"><em>Ativação necessária</em></a><em>)</em></td></tr></tbody></table>

### Passagem de parâmetros

Todos os recursos são ativados e configurados adicionando parâmetros de consulta diretamente ao seu endpoint WebSocket Secure, encadeando vários recursos com & (`&`).

```bash
# Exemplo: Conectando ao Chrome com geolocalização nos EUA, tratamento de CAPTCHA e transmissão VNC ao vivo
wss://USER:PASS@ubc.oxylabs.io?p_cc=US&solve_captcha=true&o_vnc=true
```

## Exemplos de código

Abaixo estão exemplos básicos para inicializar uma sessão de navegador hospedada na nuvem:

{% tabs %}
{% tab title="Python (Playwrigth)" %}

```python
from playwright.sync_api import sync_playwright

username = "USERNAME" # include any account suffix
password = "PASSWORD"
endpoint = "ubc.oxylabs.io"
browser_url = f"wss://{username}:{password}@{endpoint}?p_cc=US"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    page.goto("https://ip.oxylabs.io/location")
    print(page.title())
    browser.close()
```

{% endtab %}

{% tab title="JavaScript (Playwright)" %}

```javascript
process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import { chromium } from "playwright";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "ubc.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();
```

{% endtab %}

{% tab title="JavaScript (Puppeteer)" %}

```javascript
process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import puppeteer from "puppeteer";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "ubc.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Observação:** Os exemplos usam `USERNAME` e `PASSWORD` apenas para legibilidade. Em projetos reais, carregue-os das variáveis de ambiente (ex.: `process.env.OXYLABS_USERNAME` / `process.env.OXYLABS_PASSWORD`) por meio de um `.env` arquivo.
{% endhint %}

{% hint style="warning" %}
**JavaScript:** Use `NODE_TLS_REJECT_UNAUTHORIZED="0"` sinalizador antes de exigir Playwright no Node.js se você encontrar erros de TLS/certificado. Apenas para testes locais. Em produção, restrinja a confiança à conexão específica ou adicione o certificado CA do provedor ao seu repositório de confiança.
{% endhint %}

## Referência de parâmetros <a href="#need-a-feature-enabled" id="need-a-feature-enabled"></a>

<table><thead><tr><th width="200">Parâmetro</th><th width="431.5">Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>p_cc</code></td><td>Geolocalização do país em <code>ISO 3166-1 alpha-2</code> código de 2 letras (ex.: <code>US</code>, <code>DE</code>).</td><td>cadeia de caracteres</td></tr><tr><td><code>p_state</code></td><td>Geolocalização do estado em minúsculas (ex.: <code>texas</code>). Substitui <code>p_cc</code> se ambos forem usados. <a href="https://content.gitbook.com/content/BQ7Zf9paoN3FTeGcyfY1/blobs/cVjpiu1GKicluiVIT9og/us_states.txt">Lista de estados compatíveis</a>.</td><td>cadeia de caracteres</td></tr><tr><td><code>p_city</code></td><td>Geolocalização da cidade, em minúsculas, <code>_</code> para espaços (ex.: <code>new_york</code>). <code>p_cc</code> / <code>p_state</code> obrigatório.</td><td>cadeia de caracteres</td></tr><tr><td><code>p_device</code></td><td>Defina fingerprints, viewports e user-agents do dispositivo. Suporta <code>desktop</code> (padrão) e <code>mobile</code>.</td><td>cadeia de caracteres</td></tr><tr><td><code>solve_captcha</code></td><td>Resolução automática de CAPTCHA em tempo real ao carregar páginas. Padrão: <code>true</code>.</td><td>booleano</td></tr><tr><td><code>record</code></td><td>Grave vídeo da sessão headless. Padrão: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>record_name</code></td><td>Nomeie a gravação para facilitar a busca (<code>^[a-zA-Z0-9_-]{1,64}$</code>).</td><td>cadeia de caracteres</td></tr><tr><td><code>session_name</code></td><td>Sessões persistentes – reconecta ao mesmo navegador remoto ao vivo (<code>^[A-Za-z0-9-]{3,36}$</code>, suporta hífens, sem underscores). TTL máximo – 24h.</td><td>cadeia de caracteres</td></tr><tr><td><code>keep_alive</code></td><td>Fecha a instância remota do navegador ao desconectar o cliente quando definido como <code>false</code>. Padrão: <code>true</code>.</td><td>booleano</td></tr><tr><td><mark style="background-color:yellow;"><code>o_profile</code></mark></td><td>Perfis persistentes – salve/restaure cookies e <code>localStorage</code> com um perfil nomeado (<code>^[A-Za-z0-9_-]{1,36}$</code>).</td><td>cadeia de caracteres</td></tr><tr><td><mark style="background-color:yellow;"><code>o_profile_save</code></mark></td><td>Perfis persistentes – força o salvamento do perfil no meio da sessão. Padrão: <code>true</code>.</td><td>booleano</td></tr><tr><td><code>proxy_resi_ses_id</code></td><td>ID de sessão personalizado para fixar o IP de saída do proxy residencial entre sessões (<code>^[A-Za-z0-9]{3,36}$</code>).</td><td>cadeia de caracteres</td></tr><tr><td><code>proxy_resi_ses_time</code></td><td>Duração para manter o IP de saída do proxy residencial fixado em minutos. Mín <code>1</code>, máx <code>1440</code> (24h).</td><td>inteiro</td></tr></tbody></table>

&#x20;    – disponível após ativação manual para sua conta. [Saiba mais](#need-a-feature-enabled-1).

## Configuração recomendada

### Otimizando o tráfego

A raspagem de páginas dinâmicas frequentemente faz com que o navegador baixe recursos desnecessários, como mídia pesada, scripts de rastreamento, imagens e fontes. Isso consome largura de banda e reduz o tempo de execução.

Você pode interceptar e abortar essas solicitações programaticamente antes que consumam recursos:

{% tabs %}
{% tab title="Python (Playwrigth)" %}

```python
# Abort heavy assets to save bandwidth and improve speeds
def block_resources(route):
    if route.request.resource_type in ["image", "stylesheet", "media", "font"]:
        route.abort()
    else:
        route.continue_()

page.route("**/*", block_resources)
```

{% endtab %}

{% tab title="JavaScript (Playwright)" %}

```javascript
// Abort heavy assets to save bandwidth and improve speeds
await page.route("**/*", (route) => {
    const type = route.request().resourceType();
    if (["image", "stylesheet", "media", "font"].includes(type)) {
        return route.abort();
    }
    return route.continue();
});
```

{% endtab %}
{% endtabs %}

### Tratamento de erros e novas tentativas <a href="#error-handling-and-retries" id="error-handling-and-retries"></a>

Oscilações de rede e o limite de 10 sessões por segundo significam que uma única `connectOverCDP` chamada pode falhar de forma transitória. Envolva a conexão em um `retry` com `backoff`exponencial, e limite cada tentativa com um timeout. O exemplo abaixo usa a API padrão do Playwright:

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

const MAX_RETRIES = 5;
const BASE_DELAY_MS = 1000;

async function connectWithRetry(endpoint, { maxRetries = MAX_RETRIES } = {}) {
    let lastError;
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            // Cap how long a single connection attempt may take.
            return await chromium.connectOverCDP(endpoint, { timeout: 60_000 });
        } catch (err) {
            lastError = err;
            // Exponential backoff with jitter — backs off when you hit the
            // 10-new-sessions/second rate limit instead of hammering the endpoint.
            const delay = BASE_DELAY_MS * 2 ** attempt + Math.random() * 250;
            console.warn(
                `connect attempt ${attempt + 1} failed: ${err.message}; ` +
                `retrying in ${Math.round(delay)}ms`
            );
            await new Promise((resolve) => setTimeout(resolve, delay));
        }
    }
    throw lastError;
}
```

### Limpeza de recursos <a href="#resource-cleanup" id="resource-cleanup"></a>

Sempre feche o navegador quando terminar, mesmo que sua automação lance um erro no meio. Use um `bloco try { ... } finally { ... }` para que a limpeza seja executada em todos os caminhos:

```javascript
const browser = await connectWithRetry(endpoint);
try {
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    // ... your automation ...
} finally {
    // Runs even if the block above throws. Without this, a session left open
    // after an exception lingers and counts against your 100 concurrent-session limit.
    await browser.close();
}
```

Se ocorrer uma exceção entre connect e close e você não fizer a limpeza, a sessão remota permanece aberta e consome uma de suas **100 sessões simultâneas** até ser liberada. Vazamento de sessões sob carga pode esgotar o limite e bloquear novas conexões.

## Precisa ativar um recurso? <a href="#need-a-feature-enabled" id="need-a-feature-enabled"></a>

Alguns recursos do Headless Browser estão desativados ou restritos por padrão. Para acessá-los, entre em contato com o suporte da Oxylabs ([chat ao vivo](https://oxylabs.io/) ou [email](mailto:support@oxylabs.io)) ou com seu Gerente de Conta Dedicado:

* **Perfis persistentes** – obtenha acesso ao recurso e `o_profile` parâmetros.
* **Mais perfis** – aumente o limite da conta de `max_profiles` para perfis persistentes.
* **Alvos restritos** – desbloqueie mais categorias de alvos por meio do processo KYC.
* **Limites de taxa mais altos** – aumente para além de 100 sessões simultâneas / 10 por segundo.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/pt-br/headless-browser.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.