Tratamento de CAPTCHA

Saiba mais sobre os mecanismos de detecção e tratamento de CAPTCHA do Headless Browser e como usá-los.

Por padrão, Oxylabs Headless Browser não faz não lida com CAPTCHAs automaticamente. Para ativar a detecção e o tratamento automáticos assim que uma página carregar, adicione solve_captcha=true à sua URL de conexão.

Se um site-alvo exibir desafios dinamicamente durante interações em várias etapas, ou se você precisar de monitoramento avançado de eventos e otimizações de velocidade, pode usar os parâmetros, eventos e técnicas documentados abaixo.

Observação: As taxas de sucesso de acesso dependem muito do alvo. Os resultados podem variar com base na configuração específica do site-alvo, nos níveis de aplicação (por exemplo, rastreamento passivo de fingerprint vs. escalada ativa do desafio) e na reputação em tempo real do IP residencial da sessão.

Monitorando eventos de CAPTCHA

Você pode monitorar o ciclo de vida do resolvedor. A extensão interna oxylabs-runtime do navegador emite eventos de status diretamente para o window objeto window do navegador. Ao registrar um ouvinte personalizado do evento "message", seu script pode rastrear esses eventos para pausar e retomar ações.

Tipo de evento	Descrição
oxylabs-captcha-start	O resolvedor detectou um CAPTCHA e iniciou o processo de tratamento.
oxylabs-captcha-end	O resolvedor foi concluído com sucesso e tratou o desafio.
oxylabs-captcha-solve-end	Evento alternativo de conclusão emitido após o sucesso.
oxylabs-captcha-error	O resolvedor falhou ao tratar o desafio.

A resolução automática está desativada por padrão. Acrescente solve_captcha=true à sua URL de conexão para ativar o tratamento automático e começar a emitir esses eventos.

Exemplos de código

Estes exemplos mostram como injetar um init script para capturar eventos de CAPTCHA em tempo de execução antes da navegação da página, para que seu script pause durante o tratamento ativo.

Python (Playwright)

from playwright.sync_api import sync_playwright

username = "USERNAME_abc12"
password = "PASSWORD"
endpoint = "hb.oxylabs.io"
# solve_captcha=true ativa o tratamento e a emissão de eventos (desativado por padrão)
browser_url = f"wss://{username}:{password}@{endpoint}?solve_captcha=true"

def run():
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(browser_url)
        ctx = browser.contexts[0]
        page = ctx.new_page()

        # Injetar listener ANTES da navegação
        ctx.add_init_script("""
            window.addEventListener("message", (event) => {
                if (event.data && event.data.source === "oxylabs-runtime") {
                    window.__extensionStatus = event.data.type;
                }
            });
        """)

        page.goto("https://example.com/captcha-page", wait_until="domcontentloaded")

        # Aguarde o resolvedor concluir (faz polling do sinalizador de status)
        page.wait_for_function(
            """() => {
                const status = window.__extensionStatus;
                if (status === "oxylabs-captcha-error") {
                    throw new Error("CAPTCHA solving failed");
                }
                return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
            }""",
            timeout=60000
        )
        print("CAPTCHA solved. Resuming automation...")
        browser.close()

if __name__ == "__main__":
    run()

JavaScript (Playwright)

import { chromium } from "playwright";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?solve_captcha=true`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0];
    const page = await ctx.newPage();

    // Registrar script de inicialização para escutar eventos de oxylabs-runtime
    await ctx.addInitScript(() => {
        window.addEventListener("message", (e) => {
            if (e.data?.source === "oxylabs-runtime") {
                window.__extensionStatus = e.data.type;
            }
        });
    });

    await page.goto("https://example.com/captcha-page", { waitUntil: "domcontentloaded" });

    try {
        // Interrompa a execução do script até o CAPTCHA retornar um status de resolução positiva
        await page.waitForFunction(() => {
            const status = window.__extensionStatus;
            if (status === "oxylabs-captcha-error") {
                throw new Error("CAPTCHA solving failed");
            }
            return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
        }, null, { timeout: 60000 });

        console.log("CAPTCHA solved. Resuming automation...");
    } catch (err) {
        console.error("Error during bypass execution:", err.message);
    } finally {
        await browser.close();
    }
})();

JavaScript (Puppeteer)

import puppeteer from "puppeteer";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?solve_captcha=true`;

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();

    // Alternativa do Puppeteer: avaliar na criação do documento
    await page.evaluateOnNewDocument(() => {
        window.addEventListener("message", (e) => {
            if (e.data?.source === "oxylabs-runtime") {
                window.__extensionStatus = e.data.type;
            }
        });
    });

    await page.goto("https://example.com/captcha-page", { waitUntil: "domcontentloaded" });

    try {
        await page.waitForFunction(() => {
            const status = window.__extensionStatus;
            if (status === "oxylabs-captcha-error") {
                throw new Error("CAPTCHA solving failed");
            }
            return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
        }, { timeout: 60000 });

        console.log("CAPTCHA solved. Resuming automation...");
    } catch (err) {
        console.error("Error during bypass execution:", err.message);
    } finally {
        await browser.close();
    }
})();

Gatilhos manuais dinâmicos

Alguns alvos só exibem desafios CAPTCHA após ações do usuário (por exemplo, depois de clicar em um botão interativo de envio de formulário ou realizar rolagem dinâmica).

Você pode acionar programaticamente o tratador de CAPTCHA do Headless Browser a qualquer momento da sua sessão usando window.postMessage evento diretamente no objeto window:

window.postMessage({ action: "solve_captcha", type: "type_name" }, "*");

Para saber mais sobre os tipos de CAPTCHA suportados, entre em contato com o suporte da Oxylabs (chat ao vivo ou email) ou com seu Gerente de Conta Dedicado.

Padrão de acionamento

Para elementos típicos, acione o resolvedor imediatamente após executar a ação do usuário:

// Realize a interação com o formulário
await page.click("#form-submit-button");

// Acione a resolução para CAPTCHA em estágio tardio
await page.evaluate(() => {
    window.postMessage({ action: "solve_captcha", type: "type_name" }, "*");
});

Para saber mais sobre os tipos de CAPTCHA suportados ou exceções para tipos específicos, entre em contato com o suporte da Oxylabs (chat ao vivo ou email) ou com seu Gerente de Conta Dedicado para obter mais detalhes.

Otimização de velocidade

O tratamento de CAPTCHAs adiciona latência de execução mecânica. Ao raspar alvos que impõem verificações de CAPTCHA repetitivas, considere estes métodos para obter melhor desempenho:

Reutilizar sessões	Depois que uma sessão de navegador remoto conclui um CAPTCHA em um domínio, a verificação é salva. Navegue repetidamente ou execute etapas adicionais da página na mesma sessão do navegador sem reativar rotinas de resolução de desafios.
Múltiplas abas	Em vez de conexões WebSocket separadas (que iniciam sandboxes distintos com pools de cookie vazios), execute tarefas concorrentes abrindo várias abas ou contextos dentro da sua sessão existente, para reduzir o tempo de conexão e verificação em todas as páginas.
Ativar seletivamente	Como solve_captcha está desativado por padrão, ative-o apenas (solve_captcha=true) para as conexões específicas que precisam dele, em vez de deixá-lo ativado durante todo o fluxo de trabalho — isso evita a latência de inicialização do resolvedor em páginas ou sessões que não enfrentam desafios CAPTCHA.