Introducción a BotBrowser y Puppeteer

Introducción

Puppeteer es la librería de Node.js de Google para controlar Chrome mediante el Chrome DevTools Protocol (CDP). Proporciona una API de alto nivel para navegación, capturas de pantalla, interacción con formularios, intercepción de red y más. BotBrowser reemplaza el binario Chromium estándar por uno que produce huellas consistentes controladas por archivos de perfil. Puppeteer gestiona la automatización; BotBrowser gestiona la identidad.

Esta guía cubre la instalación, la configuración de lanzamiento, la gestión del viewport, la configuración de proxy, el acceso CDP, el despliegue en servidores Linux y la resolución de problemas comunes.

Por qué Puppeteer + BotBrowser

El Chromium predeterminado expone la huella del equipo anfitrión. Con BotBrowser, cada instancia de Puppeteer puede cargar un perfil de huella diferente, proporcionando identidades de navegador distintas sin cambiar el código de automatización.

Antecedentes técnicos

puppeteer-core vs puppeteer

El paquete puppeteer incluye un binario de Chromium. puppeteer-core ofrece la misma API sin bundlear navegadores, por lo que debes especificar executablePath al lanzar, apuntando al binario de BotBrowser.

# Instala puppeteer-core, no puppeteer
npm install puppeteer-core

defaultViewport

Puppeteer establece por defecto defaultViewport a 800x600, lo que puede sobrescribir el tamaño de viewport definido en el perfil de BotBrowser. Siempre establece defaultViewport: null para permitir que el perfil controle el viewport.

Ejemplo básico

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: ['--bot-profile=/path/to/profile.enc'],
    headless: true,
    defaultViewport: null,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');

  console.log('Page title:', await page.title());
  await browser.close();
})();

Buenas prácticas

• Usa puppeteer-core.
• Usa rutas absolutas para --bot-profile.
• No olvides defaultViewport: null.
• En servidores Linux, configura DISPLAY=:10.0 si corresponde.

Resumen

Integrar BotBrowser con Puppeteer requiere cambiar solo la configuración de lanzamiento: usar puppeteer-core, apuntar executablePath al binario de BotBrowser y pasar --bot-profile con defaultViewport: null.

title: "Primeros pasos con BotBrowser y Puppeteer" description: "Guia rapida para ejecutar BotBrowser con Puppeteer para automatizacion de navegador con perfiles de huella digital consistentes." date: "2025-03-04" locale: es category: getting-started tags: ["puppeteer", "automation", "getting-started", "tutorial"] published: true

Descripcion general

Puppeteer es la biblioteca Node.js de Google para controlar Chrome. BotBrowser reemplaza el binario Chromium estandar con uno que produce salida de huella digital consistente controlada por archivos de perfil. Puppeteer gestiona la automatizacion, BotBrowser gestiona la identidad.

Requisitos previos

• Binario de BotBrowser (descargar desde GitHub)
• Un archivo de perfil de huella digital (formato .enc)
• Node.js 18+
• npm install puppeteer-core

Inicio rapido

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
    ],
    headless: true,
    defaultViewport: null,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');

  // Tu logica de automatizacion aqui

  await browser.close();
})();

Configuracion clave

Usa puppeteer-core, no el paquete completo puppeteer que descarga su propio Chromium.

Establece defaultViewport: null para que Puppeteer no sobreescriba las dimensiones del viewport de tu perfil.

Ejemplo con perfil + proxy

const browser = await puppeteer.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
    '--proxy-server=socks5://user:pass@proxy:1080',
    '--bot-config-timezone=Europe/London',
    '--bot-config-locale=en-GB',
    '--bot-config-languages=en-GB,en',
  ],
  headless: true,
  defaultViewport: null,
});

Headless en Ubuntu

Establece la variable de entorno DISPLAY=:10.0 incluso en modo headless en servidores Linux.

Problemas comunes

El navegador no se inicia: Verifica permisos de ejecucion y ruta del binario.

Viewport incorrecto: Siempre establece defaultViewport: null.

Problemas de ruta del perfil: Usa rutas absolutas para --bot-profile.

Siguientes pasos

• Recetas CLI para mas combinaciones de flags
• Configuracion de servidor headless para despliegue en produccion
• Gestion de perfiles para organizar perfiles