Tratamento de CAPTCHA

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

Por padrão, Oxylabs Agent Browser não faz não o tratamento automático de CAPTCHAs. 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 de destino 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, use 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 de destino, nos níveis de imposição (por exemplo, rastreamento passivo de fingerprint vs. escalonamento ativo de 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 solucionador. A extensão interna oxylabs-runtime do navegador transmite eventos de status diretamente para o window object. Ao registrar um listener de evento "message" personalizado, 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 resolução automática é 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 enables handling and event emission (off by default)
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()

        # Inject listener BEFORE navigation
        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")

        # Wait for solver to complete (polls status flag)
        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();

    // Register init script to listen for oxylabs-runtime events
    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 {
        // Halt script execution until CAPTCHA returns positive solve status
        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();

    // Puppeteer alternative: Evaluate on document creation
    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 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 programaticamente o manipulador de CAPTCHA do Agent Browser a qualquer momento na sua sessão usando window.postMessage evento diretamente ao objeto window:

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

Para saber mais sobre os tipos de CAPTCHA suportados, contate a Oxylabs (chat ao vivo ou e-mail) ou seu Gerente de Conta Dedicado.

Padrão de acionamento

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 resolução para CAPTCHA de etapa final
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, contate o suporte da Oxylabs (chat ao vivo ou e-mail) ou seu Gerente de Conta Dedicado para mais detalhes.

Otimização de velocidade

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

Reutilizar sessões	Depois que uma sessão remota do navegador 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 acionar novamente as rotinas de resolução de desafios.
Várias abas	Em vez disso, de conexões WebSocket separadas (que iniciam sandboxes distintos com pools de cookie vazios), execute tarefas simultâneas 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, habilite-o apenas (solve_captcha=true) para as conexões específicas que precisam dele, em vez de mantê-lo ativado em todo o fluxo de trabalho — isso evita a latência de inicialização do solucionador em páginas ou sessões que não enfrentam desafios de CAPTCHA.