TL;DR
- Una conexión de navegador remoto de Puppeteer utiliza
puppeteer.connect()y el punto final WebSocket del navegador remoto. puppeteer-corees apropiado cuando tu trabajador se conecta a un navegador que ya está siendo ejecutado por otro servicio.- Las llamadas HTTP del ciclo de vida de Nstdata utilizan una clave de API comercial; las conexiones CDP utilizan credenciales emitidas por separado y de corta duración.
- Usa
browserWSEndpointpara la URL WebSocket CDP devuelta y pasa la autenticación a través del nombre del encabezado devuelto. - Establece
defaultViewport: nullcuando quieras preservar el viewport existente del navegador remoto en lugar de aplicar la sobrescritura predeterminada de Puppeteer. browser.disconnect()deja el navegador remoto en funcionamiento; detén la sesión de Nstdata por separado después de la tarea.
¿Qué es una conexión de navegador remoto de Puppeteer?
Una conexión de navegador remoto de Puppeteer permite a un cliente Node.js controlar un navegador que ya está en ejecución en lugar de lanzar un ejecutable local. Puppeteer envía comandos de automatización a través de una conexión de protocolo; el navegador realiza la navegación, ejecución de JavaScript y renderizado en su propio host. Esto es útil cuando los trabajadores deben permanecer pequeños o un operador necesita ver la misma sesión que controla el script.
Nstdata Cloud Browser proporciona navegadores en la nube gestionados para la automatización del navegador y agentes de IA con una superficie de conexión CDP. En este recorrido, el panel de control se encarga de la creación y detención de sesiones, mientras que un pequeño cliente Puppeteer se encarga de una página temporal. Separar esas responsabilidades hace que la primera integración sea más fácil de inspeccionar.
El ejemplo valida una página pública sin iniciar sesión en una cuenta ni enviar datos. Para una introducción más amplia al marco, la existente guía de Node.js Puppeteer y Playwright cubre la automatización de páginas locales. Este artículo se centra en el contrato adicional introducido por un navegador remoto: identidad de punto final, duración de credenciales, propiedad de la página y apagado.
¿Deberías usar Puppeteer o Puppeteer-Core?
Usa puppeteer-core cuando tu aplicación suministre un punto final de navegador existente y no necesite la descarga de navegador gestionada de Puppeteer. La guía de instalación de Puppeteer distingue el paquete completo de la biblioteca base. Elegir el paquete básico no crea un navegador; ya debe estar disponible un navegador remoto compatible.
| Decisión | Uso en este tutorial |
|---|---|
| Creación de navegador | Nstdata Playground |
| Paquete del cliente | puppeteer-core |
| Método de conexión | puppeteer.connect() |
| Opción de punto final | browserWSEndpoint |
| Propiedad de la página | Crear y cerrar una página de demostración |
| Limpieza gestionada | Detener la sesión original en el panel de control |
No confundas ejecutar Puppeteer en tu trabajador Node.js con empaquetar su API dentro de una página web de cliente. Este ejemplo es un script del lado del servidor. Las claves de API comerciales se quedan en el entorno del trabajador y nunca entran en el paquete JavaScript de un sitio web.
¿Qué credenciales y configuraciones necesitas?
Necesitas una sesión de Cloud Browser lista, Node.js 22.12 o posterior, y una clave de API comercial para el espacio de trabajo que posee la sesión. Obtén una clave personal de Settings → Account, o usa una clave de miembro del equipo de Members. Verifica el saldo del espacio de trabajo actual y la asignación de concurrencia antes de lanzar.
El ID de sesión identifica el navegador en ejecución. NSTDATA_API_KEY se convierte en el encabezado del ciclo de vida x-api-key sin un prefijo Bearer. Opcionalmente, una clave personal puede seleccionar un equipo unido a través de NSTDATA_TEAM_ID, enviada como x-team-id; una clave de miembro de equipo utiliza su equipo asociado. Mantén este contexto el mismo para la búsqueda y la emisión de credenciales.
El punto final de credenciales devuelve cdpUrl, headerName, accessToken y expiresAt para la misma sesión. Esos valores autentican la conexión WebSocket. No son un sustituto reutilizable de la clave de API comercial, y un token antiguo no revive un navegador terminado.
El apretón de manos, navegación, afirmación y desconexión de Puppeteer de este tutorial se ejecutaron contra un Chromium local aislado. La rama de credenciales de cuenta gestionada requiere tu clave y no se ejecutó contra un espacio de trabajo de pago de Nstdata. Trata tu primera ejecución gestionada como un canario de integración, con el apagado de sesión incluido en la aceptación.
¿Cómo conectas Puppeteer a un Cloud Browser?
Conecta Puppeteer lanzando una sesión, instalando el cliente base, recuperando credenciales específicas de sesión y suministrándolas a puppeteer.connect(). La API de conexión de Puppeteer es la referencia del cliente para esta operación.
Paso 1: Crear una sesión remota visible
Abrir Cloud Browser → Playground y seleccionar el espacio de trabajo personal o de equipo deseado. Establecer Session Name, Proxy Country, Resource Class y Session Duration, luego hacer clic en Launch Browser. Esperar a que esté en Running y tenga una vista previa utilizable.
[Captura de pantalla: Una sesión de Navegador en la Nube en ejecución con el espacio de trabajo y el nombre de la sesión visibles; ocultar enlaces de acceso, tokens y contenido de páginas privadas.]
Configurar el país del proxy antes de que la sesión comience. El cliente hereda la ruta de red configurada de la sesión, por lo que este ejemplo no pasa una segunda URL de proxy a Puppeteer. El país del proxy, el idioma y la zona horaria son configuraciones distintas; seleccionar un país no garantiza una dirección fija o una sesión de sitio web autenticada.
Paso 2: Instalar Puppeteer-core
Inicializar un proyecto e instalar la versión exacta del cliente utilizada para el ejemplo. Conservar el archivo de bloqueo generado para que otro trabajador pueda reproducir la elección de dependencias.
mkdir cloud-puppeteer-demo cd cloud-puppeteer-demo npm init -y npm install --save-exact puppeteer-core@25.17.0
Paso 3: Guardar el ayudante de credenciales
Guardar el siguiente código como cloud-api.mjs. Este consulta la sesión antes de solicitar credenciales de automatización y construye el encabezado CDP a partir del campo devuelto. Cuando ese campo es Authorization, el valor recibe el prefijo Bearer; otros nombres de encabezados devueltos reciben el token de acceso en bruto.
Prerequisito de credenciales: la rama Nstdata requiere su clave API comercial y una sesión lista. La opción de bucle inverso del ayudante existe solo para un navegador de prueba local separado y debe permanecer sin configurar para el flujo de trabajo gestionado.
const root = 'https://api.nstdata.io/api/v1/cloud-browser'; export async function api(method, path, body) { const key = process.env.NSTDATA_API_KEY; if (!key) throw new Error('Set NSTDATA_API_KEY'); const headers = { 'x-api-key': key }; if (process.env.NSTDATA_TEAM_ID) headers['x-team-id'] = process.env.NSTDATA_TEAM_ID; if (body) headers['content-type'] = 'application/json'; let response; try { response = await fetch(root + path, { method, headers, redirect: 'error', body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(20_000), }); } catch { throw Object.assign(new Error('API transport failed; reconcile the original operation'), { retryable: true }); } const retryable = response.status === 429 || response.status >= 500; let result; try { result = await response.json(); } catch { throw Object.assign(new Error('Invalid API JSON'), { retryable }); } if (!response.ok || result.err === true || result.success === false) { throw Object.assign(new Error(`Cloud Browser API HTTP ${response.status}`), { retryable }); } if (!result.data) throw new Error('Missing API data'); return result.data; } export async function connection(id) { if (!id) throw new Error('Set NSTDATA_SESSION_ID'); const path = `/sessions/${encodeURIComponent(id)}`; const session = await api('GET', path); if (session.state !== 'ready') throw new Error(`Session is ${session.state}, not ready`); const c = await api('POST', path + '/automation-credentials'); if (c.sessionId !== id || !c.headerName || !c.accessToken || !(Date.parse(c.expiresAt) > Date.now()) || new URL(c.cdpUrl).protocol !== 'wss:') { throw new Error('Invalid or expired CDP credentials'); } return { endpoint: c.cdpUrl, headers: { [c.headerName]: c.headerName.toLowerCase() === 'authorization' ? `Bearer ${c.accessToken}` : c.accessToken }, }; } export async function endpoint() { // An isolated local CDP endpoint can test the client without managed credentials. if (process.env.LOCAL_CDP_URL) { const url = new URL(process.env.LOCAL_CDP_URL); if (!['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)) { throw new Error('LOCAL_CDP_URL must use loopback'); } return { endpoint: url.href, headers: {} }; } return connection(process.env.NSTDATA_SESSION_ID); }
Paso 4: Guardar la tarea del navegador
Guardar este script como connect-puppeteer.mjs. Abre una página, verifica la respuesta de navegación y valida el encabezado esperado antes de cerrar la página y desconectar. Los valores de tiempo de espera limitan esta demostración; no son cuotas de servicio.
Prerequisito de credenciales: la ejecución gestionada requiere la clave y la configuración del entorno de sesión descrita anteriormente. La rama del cliente se ejecutó a través de una conexión CDP local real.
import puppeteer from 'puppeteer-core'; import { endpoint } from './cloud-api.mjs'; async function main() { const config = await endpoint(); let browser; let page; try { browser = await puppeteer.connect({ browserWSEndpoint: config.endpoint, headers: config.headers, defaultViewport: null, protocolTimeout: 30_000, }); page = await browser.newPage(); const response = await page.goto(process.env.TARGET_URL || 'https://example.com/', { waitUntil: 'domcontentloaded', timeout: 30_000, }); if (!response?.ok()) throw new Error('Navigation failed'); await page.waitForSelector('h1', { visible: true, timeout: 15_000 }); const heading = await page.$eval('h1', element => element.textContent.trim()); if (heading !== 'Example Domain') throw new Error('Unexpected heading'); console.log(JSON.stringify({ heading, taskPassed: true })); } finally { try { if (page) await page.close(); } finally { if (browser) await browser.disconnect(); } } } main().catch(() => { console.error("Browser task failed; inspect private diagnostics and the original session."); process.exitCode = 1; });
defaultViewport: null preserva el viewport existente en lugar de imponer un valor predeterminado de Puppeteer. No cambia la huella de pantalla de la sesión, el país del proxy o el zoom de Live View. Si tu tarea necesita un viewport particular, configúralo intencionalmente y verifica el diseño renderizado después de la conexión.
Paso 5: Ejecuta la afirmación de la página
Crea un archivo privado .env con NSTDATA_API_KEY y NSTDATA_SESSION_ID, además de NSTDATA_TEAM_ID solo cuando sea necesario. Exclúyelo del control de versiones. Ejecuta el siguiente comando desde el directorio que contiene ambos módulos.
node --env-file=.env connect-puppeteer.mjs
Para el objetivo predeterminado, el script imprime un objeto JSON con heading: "Example Domain" y taskPassed: true. Una conexión de punto final por sí sola no produciría esa afirmación. Si personalizas el objetivo, actualiza el selector y el valor esperado juntos; una página no relacionada con un h1 no es evidencia suficiente.
Paso 6: Detén la sesión que creaste
Haz clic en Stop Browser en la sesión original y espera a que se complete. El método de desconexión de Puppeteer libera la conexión del cliente mientras deja el navegador en ejecución. El apagado del navegador administrado sigue siendo una acción separada.
Para un trabajo de propiedad de la API, detén con DELETE /api/v1/cloud-browser/sessions/{sessionId} y consulta hasta que state sea ended. Un fallo del trabajador puede omitir la limpieza ordinaria, así que retén el ID de sesión fuera de la memoria de proceso transitoria. Usa el actual ciclo de vida de automatización de navegador al implementar ese servicio propietario.
¿Cómo puede Nstdata apoyar un flujo de trabajo de Puppeteer más allá de la demostración?
Nstdata Cloud Browser suministra el navegador alojado mientras Puppeteer retiene el control de la navegación y la interacción con la página. Un desarrollador puede adjuntar un script de un corredor de trabajo existente sin desplegar Chromium en cada trabajador. Un operador puede inspeccionar el mismo navegador en ejecución cuando una tarea necesita atención. La configuración de la sesión proporciona un punto de lanzamiento controlado para recursos y ubicación del proxy. La aplicación aún decide qué página es válida, qué salida es aceptable y cuándo debe detenerse la sesión.
- Tiempo de ejecución del navegador administrado: mueve la ejecución del navegador fuera del despliegue del trabajador, luego prueba tus operaciones específicas de Puppeteer contra ese tiempo de ejecución.
- Configuración de proxy integrada: elige el país del proxy soportado por la sesión sin mantener una puerta de enlace proxy separada en el cliente de ejemplo; monitorea el costo de tráfico resultante.
- Live View y diagnósticos: observa la representación e inspecciona la información de Consola o Red disponible cuando una espera de página falla.
- Ciclo de vida explícito: usa los estados de sesión para distinguir problemas de conexión de un navegador expirado o detenido.
Revisa los precios de uso de Cloud Browser antes de escalar. El tiempo de ejecución, el tráfico del proxy y el uso opcional de CAPTCHA son componentes de costo separados; una conexión remota no es un sustituto de costo fijo para trabajar con navegador ilimitado. La introducción al producto de Cloud Browser describe el límite del producto, y el tutorial práctico de Playwright proporciona un enfoque complementario al diseño de tareas de navegador.
¿Cómo reutilizas una pestaña existente sin perder estado?
Reutiliza una pestaña existente identificándola dentro de la misma sesión en lugar de crear un nuevo navegador o elegir la primera entrada en browser.pages(). Lista las páginas disponibles, coincide con un origen y una ruta esperados, y requiere exactamente un candidato. Luego verifica un marcador de cuenta o espacio de trabajo específico de la aplicación antes de leer datos o hacer clic en controles.
La demostración utiliza intencionadamente newPage() porque no tiene un estado de sesión iniciada que preservar. Un traspaso humano tiene un contrato diferente: no navegar la pestaña seleccionada de vuelta a una URL de inicio de sesión, crear un contexto de incognito, o asumir que una nueva sesión contiene las cookies de la sesión anterior. Una aplicación también puede invalidar su inicio de sesión independientemente de la duración del navegador.
¿Por qué se conecta el navegador pero falla la tarea?
El navegador puede conectarse exitosamente mientras la página seleccionada es redirigida, está incompleta, desconectada o es diferente de la aplicación esperada. Diagnostique la capa de tarea después de verificar la capa de conexión.
| Síntoma | Causa a investigar | Solución |
|---|---|---|
| La solicitud de credenciales falla | Desajuste de clave API o equipo | Mantenga la autenticación empresarial y el contexto del espacio de trabajo consistentes |
| WebSocket rechaza la autenticación | Token CDP expirado o mal aplicado | Solicite credenciales frescas para la misma sesión lista |
| Falta un encabezado | La navegación o renderizado no alcanzó el estado esperado | Verifique la respuesta, la URL de la página de forma privada y un marcador específico de disponibilidad |
| Falta un inicio de sesión existente | Nueva pestaña/contexto o sesión de navegador incorrecta | Seleccione la sesión original y la página prevista |
| El navegador permanece en el historial como en funcionamiento | Cliente desconectado sin parar | Detenga a través del propietario del ciclo de vida y confirme ended |
No agregue pausas arbitrarias antes de verificar estas condiciones. Espere el elemento o respuesta particular que demuestre disponibilidad. Un tiempo de espera largo simplemente retrasa un fallo cuando el script está observando la pestaña incorrecta.
¿Cuál es una prueba de producción inicial sensata?
Una prueba de producción inicial sensata realiza una tarea autorizada y de solo lectura y registra su resultado de forma independiente del éxito de la conexión. Utilice una duración de sesión corta, un tiempo de espera explícito para la tarea y un propietario responsable de detener el navegador. Mantenga la salida aceptada y el ID de sesión, redacte credenciales y verifique el apagado antes de aumentar la concurrencia. Esto convierte la conexión remota en un flujo de trabajo operativo que puede contabilizar.
FAQ
Q: ¿Descarga Puppeteer-core un navegador para este ejemplo?
No. El ejemplo se conecta a un navegador remoto existente. Instale el cliente principal y suministre el punto final devuelto para la sesión gestionada.
Q: ¿Debería poner la URL de CDP en browserURL?
Utilice browserWSEndpoint para la URL de WebSocket CDP devuelta en este tutorial. No intercambie un punto final de WebSocket con una página de tablero o URL de Vista en Vivo.
Q: ¿Desconectar detiene el uso del navegador?
No. browser.disconnect() deja el navegador en funcionamiento. Detenga la sesión Nstdata por separado y confirme su estado finalizado.
Q: ¿Puedo compartir un navegador entre trabajos de cliente no relacionados?
Un navegador compartido puede exponer estado y permitir acciones en competencia. Asigne la propiedad de sesión e aisle trabajos no relacionados en lugar de depender del orden de las pestañas para separar clientes.
Q: ¿La configuración de proxy incorporada garantiza el acceso a sitios web?
No. La configuración del proxy proporciona un camino de red. Los permisos del sitio web, los requisitos de inicio de sesión, el comportamiento de renderizado y la aceptación de tareas aún necesitan verificaciones independientes.
Q: ¿Qué debo hacer después de que se caiga la conexión?
Consulta primero la sesión original. Si permanece lista, solicite credenciales frescas y redescubra la página prevista; si terminó, comience una nueva tarea autorizada y restaure solo el estado que su aplicación tiene permitido reutilizar.





