Gestión de CAPTCHA

Aprende sobre los mecanismos de detección y gestión de CAPTCHA de Oxylabs Agent Browser y cómo usarlos.

De forma predeterminada, Oxylabs Agent Browser no no maneja CAPTCHAs automáticamente. Para habilitar la detección y el manejo automáticos en cuanto se cargue una página, agregue solve_captcha=true a su URL de conexión.

Si un sitio objetivo muestra desafíos de forma dinámica durante interacciones de varios pasos, o si necesita supervisión avanzada de eventos y optimizaciones de velocidad, puede usar los parámetros, eventos y técnicas documentados a continuación.

Nota: Las tasas de éxito de acceso dependen mucho del destino. Los resultados pueden variar según la configuración específica del sitio de destino, los niveles de aplicación (p. ej., seguimiento pasivo de huellas digitales frente a escalado activo de desafíos) y la reputación en tiempo real de la IP residencial de la sesión.

Supervisión de eventos CAPTCHA

Puede supervisar el ciclo de vida del solucionador. La extensión interna oxylabs-runtime del navegador transmite eventos de estado directamente al window objeto del navegador. Al registrar un listener de evento personalizado "message", su script puede rastrear estos eventos para pausar y reanudar acciones.

Tipo de evento	Descripción
oxylabs-captcha-start	El solucionador ha detectado un CAPTCHA e inició el proceso de manejo.
oxylabs-captcha-end	El solucionador se completó correctamente y manejó el desafío.
oxylabs-captcha-solve-end	Evento de finalización alternativo emitido después del éxito.
oxylabs-captcha-error	El solucionador no pudo manejar el desafío.

La resolución automática está deshabilitada de forma predeterminada. Agregue solve_captcha=true a la URL de conexión para habilitar el manejo automático y empezar a emitir estos eventos.

Ejemplos de código

Estos ejemplos muestran cómo inyectar un script de inicialización para capturar eventos CAPTCHA en tiempo de ejecución antes de la navegación de la página para que su script se pause durante el manejo activo.

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

Desencadenadores manuales dinámicos

Algunos objetivos solo muestran desafíos CAPTCHA después de acciones del usuario (por ejemplo, después de hacer clic en un botón interactivo de envío de formulario o al realizar desplazamiento dinámico).

Puede activar programáticamente el manejador CAPTCHA de Agent Browser en cualquier momento de su sesión usando window.postMessage evento directamente al objeto window:

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

Para obtener más información sobre los tipos de CAPTCHA compatibles, contacte con el soporte de Oxylabs (chat en vivo o correo electrónico) o a tu gestor de cuenta dedicado.

Patrón de activación estándar

Para elementos típicos, active el solucionador inmediatamente después de ejecutar la acción del usuario:

// Perform form interaction
await page.click("#form-submit-button");

// Trigger solving for late-stage CAPTCHA
await page.evaluate(() => {
    window.postMessage({ action: "solve_captcha", type: "type_name" }, "*");
});

Para obtener más información sobre los tipos de CAPTCHA compatibles o las excepciones para tipos específicos, contacte con el soporte de Oxylabs (chat en vivo o correo electrónico) o con su Dedicated Account Manager para obtener más detalles.

Optimización de velocidad

El manejo de CAPTCHAs añade latencia de ejecución mecánica. Cuando extraiga datos de objetivos que imponen barreras de CAPTCHA repetitivas, considere estos métodos para mejorar el rendimiento:

Reutilizar sesiones	Una vez que una sesión de navegador remoto completa un CAPTCHA en un dominio, la verificación se guarda. Navegue repetidamente o realice pasos adicionales de la página dentro de la misma sesión del navegador sin volver a activar las rutinas de resolución del desafío.
Pestañas múltiples	En lugar de conexiones WebSocket separadas (que inician sandboxes distintos con pools de cookie vacíos), ejecute tareas simultáneas abriendo varias pestañas o contextos dentro de su sesión existente, para reducir el tiempo de conexión y verificación en todas las páginas.
Habilitar de forma selectiva	Dado que solve_captcha está desactivado de forma predeterminada, solo habilítelo (solve_captcha=true) para las conexiones específicas que lo necesiten, en lugar de dejarlo activo para todo un flujo de trabajo — esto evita la latencia de inicialización del solucionador en páginas o sesiones que no enfrentan desafíos CAPTCHA.