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, o Oxylabs Headless Browser detecta e lida automaticamente com CAPTCHAs assim que uma página carrega. Nenhuma configuração ou definição de parâmetro é necessária.

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, você 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. escalonamento ativo de desafios) 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 solucionador. O interno oxylabs-runtime a extensão do navegador transmite eventos de status diretamente para o window object. Ao registrar um ouvinte de evento personalizado "message", seu script pode rastrear esses eventos para pausar e retomar ações.

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

A auto resolução é ativada por padrão. Se você acrescentar solve_captcha=false à sua URL de conexão, o tratamento automático será desativado e esses eventos não serão emitidos.

Exemplos de código

Esses 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 = "ubc.oxylabs.io"
# Garantir que solve_captcha=true esteja ativo (padrão) para emitir eventos
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 solucionador concluir (verifica o 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 = "ubc.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 ouvir eventos do 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 {
        // Interromper a execução do script até o CAPTCHA retornar status de soluçã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("Erro durante a execução do bypass:", err.message);
    } finally {
        await browser.close();
    }
})();

JavaScript (Puppeteer)

import puppeteer from "puppeteer";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "ubc.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("Erro durante a execução do bypass:", err.message);
    } finally {
        await browser.close();
    }
})();

Acionamentos manuais dinâmicos

Alguns alvos exibem desafios de CAPTCHA apenas 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 o manipulador de CAPTCHA do Headless Browser programaticamente a qualquer momento da sua sessão usando window.postMessage evento diretamente para o 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 gatilho padrão

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

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

// Acionar a solução para CAPTCHA em fase tardia
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 mais detalhes.

Otimização de velocidade

O tratamento de CAPTCHAs adiciona latência mecânica de execução. Ao fazer scraping de alvos que impõem portões repetitivos de CAPTCHA, considere estes métodos para 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 solução de desafios.
Várias abas	Em vez de inicializar conexões WebSocket separadas (o que inicia sandboxes distintas com pools de cookie vazios), execute tarefas simultâneas abrindo várias abas ou contextos dentro da sessão existente. Isso reduz a sobrecarga de conexão e verificação em todas as páginas.
Desativação adaptativa	Depois que um sinal confiável de confiança da sessão tiver sido estabelecido, você pode desativar completamente as verificações do solucionador em segundo plano conectando-se com solve_captcha=false. Isso evita a latência de inicialização do processo para domínios em que sua sessão já passa livremente sem apresentação de desafios.