Skip to main content

Node.js Quick Start

Get started with the Browser7 Node.js SDK in minutes.

Prerequisites​

  • Node.js 18+ (uses native fetch API)
  • A Browser7 API key from the Dashboard

Installation​

npm install browser7

The SDK supports both ESM and CommonJS - use whichever you prefer!

Your First Render​

The simplest way to render a page:

// ESM
import Browser7 from 'browser7';

// Or CommonJS
const Browser7 = require('browser7');

// Create client with your API key
const client = new Browser7({ apiKey: 'b7_your_api_key_here' });

// Render a page and wait for the result
const result = await client.render('https://example.com');
console.log(result.html);

The render() method automatically:

  • Creates a render job
  • Polls for completion
  • Decompresses the HTML
  • Returns the final result

Basic Options​

Geo-Targeting​

Render pages from specific countries:

const result = await client.render('https://example.com', {
  countryCode: 'US'  // Render from United States
});

console.log(result.selectedCity.displayName);  // e.g., "New York"

You can also specify a city:

const result = await client.render('https://example.com', {
  countryCode: 'GB',
  city: 'london'
});

See the Geo-Targeting Guide for available countries and cities.

Performance Options​

Block images for faster rendering and lower bandwidth (enabled by default):

const result = await client.render('https://example.com', {
  blockImages: true  // Default is true
});

console.log(result.bandwidthMetrics);
// {
//   networkBytes: 524288,
//   cachedBytes: 102400,
//   cacheHitRate: '16.3%'
// }

Wait Actions​

Wait for dynamic content to load using the helper methods:

const result = await client.render('https://example.com', {
  waitFor: [
    Browser7.waitForSelector('.main-content'),  // Wait for element
    Browser7.waitForDelay(2000)                 // Wait 2 seconds
  ]
});

Available wait action helpers:

  • Browser7.waitForDelay(ms) - Wait for a specific time
  • Browser7.waitForSelector(selector, state, timeout) - Wait for an element
  • Browser7.waitForText(text, selector, timeout) - Wait for text to appear
  • Browser7.waitForClick(selector, timeout) - Click an element

Example with multiple actions:

const result = await client.render('https://example.com', {
  countryCode: 'US',
  waitFor: [
    Browser7.waitForClick('.cookie-accept'),              // Click cookie banner
    Browser7.waitForSelector('.main-content', 'visible'), // Wait for content
    Browser7.waitForText('Subscribe', '.footer'),         // Wait for footer text
    Browser7.waitForDelay(1000)                           // Wait 1 second
  ]
});

See the Wait Actions Guide for more details.

Screenshots​

Capture screenshots of rendered pages for verification or debugging:

const result = await client.render('https://example.com', {
  countryCode: 'US',
  includeScreenshot: true,      // Enable screenshot capture
  screenshotFormat: 'jpeg',     // 'jpeg' or 'png' (default: 'jpeg')
  screenshotQuality: 80,        // 1-100 for JPEG quality (default: 80)
  screenshotFullPage: false     // false = viewport, true = full page (default: false)
});

// Screenshot is returned as base64-encoded image data
// Save to file:
import fs from 'fs';
const buffer = Buffer.from(result.screenshot, 'base64');
fs.writeFileSync('screenshot.jpg', buffer);

Notes:

  • Screenshots are opt-in (default: false) to keep responses fast and small
  • JPEG format is recommended for smaller file sizes (50-150KB for viewport)
  • Full page screenshots can be large (200KB-2MB+) depending on page length
  • Use viewport-only screenshots for most use cases

Progress Tracking​

Track render progress with a callback:

const result = await client.render(
  'https://example.com',
  { countryCode: 'GB' },
  (progress) => {
    console.log(`[${progress.type}] ${progress.status || ''}`);
  }
);

// Output:
// [started]
// [polling] processing
// [polling] processing
// [completed] completed

The progress callback receives events with:

  • type - Event type: 'started', 'polling', 'completed', 'failed'
  • renderId - The render job ID
  • status - Current status (for polling events)
  • attempt - Current polling attempt number
  • timestamp - ISO timestamp

Error Handling​

Always wrap your calls in try-catch blocks:

try {
  const result = await client.render('https://example.com');
  console.log('Success:', result.html.length, 'characters');
} catch (error) {
  if (error.message.includes('Failed to start render')) {
    console.error('API error:', error.message);
  } else if (error.message.includes('Render failed')) {
    console.error('Render failed:', error.message);
  } else if (error.message.includes('timed out')) {
    console.error('Render timed out after 60 attempts');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Complete Example​

Here's a complete example showing common patterns:

import Browser7 from 'browser7';

const client = new Browser7({ apiKey: 'b7_your_api_key_here' });

async function scrapeWebsite() {
  try {
    console.log('Starting render...');

    const result = await client.render(
      'https://example.com',
      {
        countryCode: 'US',
        city: 'new.york',
        blockImages: true,
        waitFor: [
          Browser7.waitForClick('.cookie-accept'),
          Browser7.waitForSelector('.main-content', 'visible'),
          Browser7.waitForDelay(1000)
        ]
      },
      (progress) => {
        if (progress.type === 'polling') {
          console.log(`⏳ Polling... attempt ${progress.attempt}`);
        }
      }
    );

    console.log('✅ Render completed!');
    console.log(`📍 City: ${result.selectedCity.displayName}`);
    console.log(`📄 HTML: ${result.html.length} characters`);
    console.log(`📊 Bandwidth: ${result.bandwidthMetrics.networkBytes} bytes`);
    console.log(`⏱️  Time: ${result.timingBreakdown.totalMs}ms`);

    return result.html;
  } catch (error) {
    console.error('❌ Error:', error.message);
    throw error;
  }
}

scrapeWebsite();

What You Get Back​

Every successful render returns a RenderResult object with:

{
  status: 'completed',
  html: '<!DOCTYPE html>...',               // Decompressed HTML
  screenshot: 'iVBORw0KGgoAAAANS...',        // Base64-encoded image (if requested)
  loadStrategy: 'default',                  // Load strategy: 'default' or 'custom'
  selectedCity: {                           // City information
    name: 'new.york',
    displayName: 'New York',
    latitude: 40.7128,
    longitude: -74.0060,
    timezoneId: 'America/New_York'
  },
  bandwidthMetrics: {                       // Network stats
    networkBytes: 524288,
    cachedBytes: 102400,
    cacheHitRate: '16.3%'
  },
  captcha: {                                // CAPTCHA info
    detected: false,
    handled: false
  },
  timingBreakdown: {                        // Performance metrics
    totalMs: 5234,
    navigationMs: 1523,
    loadStrategyMs: 2341,
    captchaMs: 45,
    waitActionsMs: 1325
  },
  retryAfter: 1                             // Polling interval (seconds)
}

Next Steps​

Now that you're familiar with the basics: