> 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

Um navegador headless baseado na nuvem com segurança adaptativa integrada, gerenciamento de CAPTCHA e residential proxies. Teste-o com exemplos de código e personalize com recursos avançados.

Headless Browser permite executar e controlar instâncias remotas para automação baseada em navegador, testes e raspagem web sem gerenciá-las localmente. Ele oferece segurança adaptativa integrada, tratamento automático de CAPTCHA, geodirecionamento, Residential Proxies integrados, gravação de sessão, sticky sessions 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

{% hint style="warning" %}
**Atenção:** Headless Browser está migrando para uma nova infraestrutura. Atualize sua string de conexão de `ubc.oxylabs.io` para `hb.oxylabs.io` antes de **1º de outubro**. A partir de 1º de outubro, o tráfego enviado ao domínio antigo será roteado automaticamente para o novo. 

O Dashboard e as ferramentas de inspeção de sessão também foram movidos de `headlesify.io` para `hb.oxylabs.io`. [Inspeção e Gravação de Sessão](/products/pt-br/headless-browser/session-inspection-and-recording.md) para detalhes.
{% endhint %}

<table><thead><tr><th width="161">Campo</th><th>Descrição</th></tr></thead><tbody><tr><td><strong>Protocolo</strong></td><td><code>wss://</code> (WebSocket Seguro)</td></tr><tr><td><strong>Host (Chromium)</strong></td><td><code>hb.oxylabs.io</code></td></tr><tr><td><strong>Autenticação</strong></td><td>No URL, informações do usuário – <code>wss://USERNAME:PASSWORD@host</code>. Deve incluir o token de sufixo do nome de usuário (por exemplo, <code>user_ab12</code>). Autenticação baseada em cabeçalho não suportada.</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ínio</strong></td><td><code>oxylabs.io</code> – usado para endpoints de conexão (por exemplo, <a href="http://hb.oxylabs.io">hb.oxylabs.io</a>), o Dashboard (<a href="http://hb.oxylabs.io/dashboard">hb.oxylabs.io/dashboard</a>), e a inspeção de sessão (<a href="http://hb.oxylabs.io/novnc">hb.oxylabs.io/novnc</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">Veja mais</a>.</td></tr></tbody></table>

## Recursos

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

<table data-header-hidden><thead><tr><th width="250"></th><th></th></tr></thead><tbody><tr><td><a href="/products/pt-br/headless-browser/captcha-handling.md"><strong>Tratamento de CAPTCHA</strong></a></td><td>Tratamento e monitoramento automático de CAPTCHA em tempo real (padrão – desativado).</td></tr><tr><td><a href="/products/pt-br/headless-browser/geolocation-and-proxy-selection.md"><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="/products/pt-br/headless-browser/device-type.md"><strong>Emulação de dispositivo</strong></a></td><td>Emule fingerprints e viewports específicos do dispositivo.</td></tr><tr><td><a href="/products/pt-br/headless-browser/session-inspection-and-recording.md#session-inspection-vnc"><strong>Inspeção de sessão (VNC)</strong></a></td><td>Monitore sessões ativas do navegador headless.</td></tr><tr><td><a href="/products/pt-br/headless-browser/session-inspection-and-recording.md#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="/products/pt-br/headless-browser/persistent-sessions-and-profiles.md#persistent-sessions"><strong>Sessões persistentes</strong></a></td><td>Crie e gerencie instâncias sticky do navegador.</td></tr><tr><td><a href="/products/pt-br/headless-browser/persistent-sessions-and-profiles.md#persistent-profiles"><strong>Perfis persistentes</strong></a></td><td>Salve e restaure cookies/localStorage entre sessões.</td></tr></tbody></table>

### Passando parâmetros

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

```bash
# Exemplo: Conectando ao Chrome com geolocalização dos EUA e tratamento de CAPTCHA ativado
wss://USER:PASS@hb.oxylabs.io?p_cc=US&solve_captcha=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 (Playwright)" %}

```python
from playwright.sync_api import sync_playwright

username = "USERNAME" # include any account suffix
password = "PASSWORD"
endpoint = "hb.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 = "hb.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 = "hb.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 de variáveis de ambiente (por exemplo, `process.env.OXYLABS_USERNAME` / `process.env.OXYLABS_PASSWORD`) por meio de um arquivo  `.env` arquivo.
{% endhint %}

{% hint style="warning" %}
**JavaScript:** Use `NODE_TLS_REJECT_UNAUTHORIZED="0"` sinalizador antes de importar o Playwright no Node.js se 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 alfa-2</code> código de 2 letras (por exemplo, <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 (por exemplo, <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>  use _ para espaços (por exemplo, <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 no carregamento das páginas. Padrão: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>record</code></td><td>Grave o 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 sticky – reconecta ao mesmo navegador remoto ativo (<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>Mantém a instância remota do navegador ativa quando o cliente se desconecta, quando definido como <code>true</code>. Padrão: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>o_profile</code></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><code>o_profile_save</code></td><td>Perfis persistentes – force o salvamento do perfil durante ou ao final da sessão. Padrão: <code>false</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 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 fixo, em minutos. Mín <code>1</code>, máx <code>1440</code> (24h).</td><td>inteiro</td></tr></tbody></table>

## Configuração recomendada

### Otimizando o tráfego

Raspar páginas dinâmicas muitas vezes faz com que o navegador baixe ativos desnecessários, como mídia pesada, scripts de rastreamento, imagens e fontes. Isso consome largura de banda e reduz a velocidade de execução.

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

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

```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>

Falhas de rede e o limite de taxa de 10 sessões por segundo significam que uma única chamada `connectOverCDP` pode falhar de forma transitória. Envolva a conexão em uma `nova tentativa` com `retardo exponencial`, e limite cada tentativa com um tempo limite. 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 uma exceção no meio do processo. Use um `try { ... } finally { ... }` bloco 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 recuperada. Vazamento de sessões sob carga pode esgotar o limite e bloquear novas conexões.

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

Alguns recursos do Headless Browser têm limites por padrão. Para ajustar seus limites, entre em contato com o suporte da Oxylabs ([chat ao vivo](https://oxylabs.io/) ou [e-mail](mailto:support@oxylabs.io)) ou com seu Gerente de Conta Dedicado:

* **Mais perfis persistentes** – aumente o limite padrão da sua conta de 5 perfis salvos.
* **Mais sessões persistentes** – aumente o limite padrão da sua conta de 5 sessões persistentes simultâneas.
* **Alvos restritos** – desbloqueie mais categorias de alvos por meio do processo KYC.
* **Limites de taxa mais altos** – aumente 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.