Headless Browser

Um Headless Browser baseado em nuvem com segurança adaptativa integrada, gerenciamento de CAPTCHA e Residential Proxies. Teste-o com exemplos de código e personalize-o 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 (Python e Node.js)
• Puppeteer (Node.js)
• Outros frameworks de automação compatíveis com CDP

Detalhes da conexão

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 para detalhes.

Campo	Descrição
Protocolo	wss:// (WebSocket Seguro)
Host (Chromium)	hb.oxylabs.io
Autenticação	No URL, informações do usuário – wss://USERNAME:PASSWORD@host. Deve incluir o token de sufixo do nome de usuário (por exemplo, user_ab12). Autenticação baseada em cabeçalho não suportada.
Transporte	CDP – chromium.connectOverCDP (Playwright) / puppeteer.connect (Puppeteer).
Domínio	oxylabs.io – usado para endpoints de conexão (por exemplo, hb.oxylabs.io), o Dashboard (hb.oxylabs.io/dashboard), e a inspeção de sessão (hb.oxylabs.io/novnc).
Limites de taxa	100 sessões simultâneas, 10 sessão por segundo. Veja mais.

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.

Tratamento de CAPTCHA	Tratamento e monitoramento automático de CAPTCHA em tempo real (padrão – desativado).
Direcionamento de Proxy e Geolocalização	Roteie sessões por países, estados ou cidades específicos.
Emulação de dispositivo	Emule fingerprints e viewports específicos do dispositivo.
Inspeção de sessão (VNC)	Monitore sessões ativas do navegador headless.
Gravação de sessão	Grave sessões do navegador em formato de vídeo.
Sessões persistentes	Crie e gerencie instâncias sticky do navegador.
Perfis persistentes	Salve e restaure cookies/localStorage entre sessões.

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 & (&).

# Exemplo: Conectando ao Chrome com geolocalização dos EUA e tratamento de CAPTCHA ativado
wss://USER:[e-mail]?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:

Python (Playwright)

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()

JavaScript (Playwright)

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();
})();

JavaScript (Puppeteer)

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();
})();

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.

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.

Referência de parâmetros

Parâmetro	Descrição	Tipo
p_cc	Geolocalização do país em ISO 3166-1 alfa-2 código de 2 letras (por exemplo, US, DE).	cadeia de caracteres
p_state	Geolocalização do estado em minúsculas (por exemplo, texas). Substitui p_cc se ambos forem usados. Lista de estados compatíveis.	cadeia de caracteres
p_city	Geolocalização da cidade, em minúsculas, _ use _ para espaços (por exemplo, new_york). p_cc / p_state obrigatório.	cadeia de caracteres
p_device	Defina fingerprints, viewports e user-agents do dispositivo. Suporta desktop (padrão) e mobile.	cadeia de caracteres
solve_captcha	Resolução automática de CAPTCHA em tempo real no carregamento das páginas. Padrão: false.	booleano
record	Grave o vídeo da sessão headless. Padrão: false.	booleano
record_name	Nomeie a gravação para facilitar a busca (^[a-zA-Z0-9_-]{1,64}$).	cadeia de caracteres
session_name	Sessões sticky – reconecta ao mesmo navegador remoto ativo (^[A-Za-z0-9-]{3,36}$, suporta hífens, sem underscores). TTL máximo – 24h.	cadeia de caracteres
keep_alive	Mantém a instância remota do navegador ativa quando o cliente se desconecta, quando definido como true. Padrão: false.	booleano
o_profile	Perfis persistentes – salve/restaure cookies e localStorage com um perfil nomeado (^[A-Za-z0-9_-]{1,36}$).	cadeia de caracteres
o_profile_save	Perfis persistentes – force o salvamento do perfil durante ou ao final da sessão. Padrão: false.	booleano
proxy_resi_ses_id	ID de sessão personalizado para fixar o IP de saída residencial entre sessões (^[A-Za-z0-9]{3,36}$).	cadeia de caracteres
proxy_resi_ses_time	Duração para manter o IP de saída do proxy residencial fixo, em minutos. Mín 1, máx 1440 (24h).	inteiro

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:

Python (Playwright)

# 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)

JavaScript (Playwright)

// 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();
});

Tratamento de erros e novas tentativas

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:

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

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:

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?

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 ou e-mail) 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.