Puppeteer Integration Guide: Connect to BotCloud in 5 Minutes

Introduction

If you already use Puppeteer, connecting to BotCloud requires changing exactly one line of code. Instead of launching a local browser with puppeteer.launch(), you connect to a cloud browser with puppeteer.connect(). Everything else stays the same: your selectors, your logic, your error handling.

Prerequisites

• Node.js 18 or later
• puppeteer-core package (not full puppeteer - you do not need a local Chromium)
• A BotCloud API key from bots.win

npm install puppeteer-core

Basic Connection

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

async function main() {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'wss://bots.win/ws?apiKey=YOUR_API_KEY',
  });

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

  const title = await page.title();
  console.log('Page title:', title);

  await browser.close();
}

main().catch(console.error);

Common Patterns

Screenshot Capture

const page = await browser.newPage();
await page.setViewport({ width: 1920, height: 1080 });
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.screenshot({ path: 'screenshot.png', fullPage: true });

Form Submission

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

await page.type('#username', 'user@example.com');
await page.type('#password', 'password123');
await page.click('#submit-button');

await page.waitForNavigation();

Data Extraction

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

const products = await page.evaluate(() => {
  return Array.from(document.querySelectorAll('.product-card')).map(card => ({
    name: card.querySelector('.name')?.textContent?.trim(),
    price: card.querySelector('.price')?.textContent?.trim(),
    url: card.querySelector('a')?.href,
  }));
});

console.log(products);

PDF Generation

const page = await browser.newPage();
await page.goto('https://example.com/report', { waitUntil: 'networkidle0' });
await page.pdf({
  path: 'report.pdf',
  format: 'A4',
  printBackground: true,
});

Request Interception

const page = await browser.newPage();
await page.setRequestInterception(true);

page.on('request', (request) => {
  // Block images for faster loading
  if (request.resourceType() === 'image') {
    request.abort();
  } else {
    request.continue();
  }
});

await page.goto('https://example.com');

With Proxy

const browser = await puppeteer.connect({
  browserWSEndpoint:
    'wss://bots.win/ws?apiKey=YOUR_API_KEY&proxy=socks5h://user:pass@proxy.example.com:1080',
});

Error Handling

Always wrap browser operations in try/finally to ensure cleanup:

async function automateTask(url) {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'wss://bots.win/ws?apiKey=YOUR_API_KEY',
  });

  try {
    const page = await browser.newPage();
    await page.goto(url, {
      waitUntil: 'domcontentloaded',
      timeout: 30000,
    });

    // Your automation logic here
    return await page.evaluate(() => document.title);
  } finally {
    await browser.close();
  }
}

Migration from Local Puppeteer

If you have existing Puppeteer scripts using puppeteer.launch():

// Before
const browser = await puppeteer.launch({
  headless: true,
  args: ['--no-sandbox'],
});

// After - just change this one line
const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://bots.win/ws?apiKey=YOUR_API_KEY',
});

// All your existing code below this line stays exactly the same

Next Steps

• Playwright Integration Guide - If you prefer Playwright
• Scaling Browser Automation - Running hundreds of sessions
• Proxy Configuration - Geographic distribution