Skip to Content
Getting StartedPuppeteer

Getting Started with Puppeteer

Launch BotBrowser with Puppeteer using Chrome-mode startup and profile-controlled viewport behavior.

Prerequisites

  • BotBrowser installed. See Installation.
  • Node.js 18+.
  • puppeteer-core installed.
  • Profile file (.enc for production).

Quick Start

npm init -y
npm install puppeteer-core
import puppeteer from "puppeteer-core";
 
const browser = await puppeteer.launch({
  browser: "chrome",
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  defaultViewport: null,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    "--proxy-server=socks5://user:pass@proxy.example.com:1080",
  ],
});
 
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

How It Works

Puppeteer integration has three key requirements in addition to normal BotBrowser launch:

  1. Use browser: "chrome" when launching with puppeteer-core.
  2. Set defaultViewport: null so profile dimensions remain authoritative.
  3. Use BotBrowser flags in args (--bot-profile, optional --proxy-server).

For shared automation guidance (runtime consistency, console behavior, bot-script fallback), see Automation Consistency.

Common Scenarios

Geo override with Puppeteer

const browser = await puppeteer.launch({
  browser: "chrome",
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  defaultViewport: null,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    "--proxy-server=socks5://user:pass@proxy.example.com:1080",
    "--bot-config-timezone=Asia/Tokyo",
    "--bot-config-locale=ja-JP",
    "--bot-config-languages=ja-JP,ja,en-US,en",
  ],
});

Browser-level CDP call

const browser = await puppeteer.launch({
  browser: "chrome",
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  defaultViewport: null,
  args: [`--bot-profile=${process.env.BOT_PROFILE_PATH}`],
});
 
const cdp = await browser.target().createCDPSession();
await cdp.send("BotBrowser.setCustomHeaders", {
  headers: { "x-client-app": "bb" },
});

Troubleshooting / FAQ

ProblemSolution
Viewport is 800x600Set defaultViewport: null.
Launch error in puppeteer-coreEnsure browser: "chrome" is present and executable path is valid.
Geo values do not match proxyPass proxy via args with --proxy-server; avoid framework-only proxy auth patterns.
Multiple instances conflictProvide unique --user-data-dir per instance.

Next Steps

Related documentation: Examples  | Per-Context Fingerprint

Legal Disclaimer & Terms of Use  • Responsible Use Guidelines . BotBrowser is for authorized fingerprint protection and privacy research only.

PlaywrightBot Script