Apify Fingerprint Suite: Open-Source Browser Fingerprinting for Stealth Scrapers

rprints. It learns the conditional probabilities between attributes. When constrained by parameters (e.g., browser: 'chrome', os: 'windows'), it samples values that maximize the likelihood of the joint distribution. This ensures internal consistency across the entire fingerprint vector.

2. Header Generation:
   The suite includes header-generator, which produces HTTP headers aligned with the generated fingerprint. This covers header names, values, and critically, the header order. Real browsers exhibit specific header ordering based on their implementation and version. Headless browsers often send headers in a sorted or default order, which is a strong detection signal. The generator replicates the ordering patterns of the target browser.

3. Injection Layer:
   The fingerprint-injector package patches the browser context. It overrides JavaScript-exposed properties such as navigator attributes, screen geometry, WebGL strings, and the navigator.webdriver flag. It also injects the generated headers into network requests. This ensures that the client-side JavaScript environment matches the server-side request headers, closing the consistency gap.

Implementation Examples

The following examples demonstrate integration with Playwright and Puppeteer using a factory pattern for context management.

Playwright Integration

import { chromium, Browser, BrowserContext } from 'playwright';
import { newInjectedContext } from 'fingerprint-injector';

interface StealthContextOptions {
    devices?: string[];
    operatingSystems?: string[];
    locales?: string[];
}

async function createStealthContext(
    browser: Browser,
    options: StealthContextOptions = {}
): Promise<BrowserContext> {
    const context = await newInjectedContext(browser, {
        fingerprintOptions: {
            devices: options.devices || ['desktop'],
            operatingSystems: options.operatingSystems || ['windows'],
            locales: options.locales || ['en-US'],
        },
    });

    return context;
}

// Usage
async function runScrape() {
    const browser = await chromium.launch();
    const context = await createStealthContext(browser, {
        operatingSystems: ['linux'],
        devices: ['desktop'],
    });

    const page = await context.newPage();
    await page.goto('https://target-site.com');
    // Proceed with scraping logic
}

Puppeteer Integration

import puppeteer, { Browser, Page } from 'puppeteer';
import { FingerprintInjector } from 'fingerprint-injector';

class PuppeteerStealthManager {
    private injector: FingerprintInjector;

    constructor() {
        this.injector = new FingerprintInjector();
    }

    async createStealthPage(browser: Browser): Promise<Page> {
        const page = await browser.newPage();
        await this.injector.attachFingerprintToPuppeteer(page);
        return page;
    }
}

// Usage
async function runPuppeteerScrape() {
    const browser = await puppeteer.launch();
    const manager = new PuppeteerStealthManager();
    const page = await manager.createStealthPage(browser);

    await page.goto('https://target-site.com');
    // Proceed with scraping logic
}

Architecture Decisions:

• Context-Level Injection: Injecting at the context level (Playwright) or page level (Puppeteer) ensures all resources inherit the fingerprint. This prevents leakage from sub-resources or iframes.
• Constraint-Based Generation: Passing constraints to the generator allows targeting specific user demographics or device types, which is essential for mimicking real traffic patterns or accessing region-locked content.
• Crawlee Compatibility: If using Crawlee, the suite is integrated by default. The standalone packages are necessary when driving Playwright or Puppeteer directly.

Pitfall Guide

1. The "Frankenstein" Fingerprint
   Explanation: Manually combining attributes from different ecosystems (e.g., macOS user-agent with Windows WebGL renderer).
   Fix: Always use the generator with explicit constraints. Never manually override individual attributes after generation.

2. Ignoring Header Order
   Explanation: Treating headers as a key-value map without considering sequence. Anti-bot services analyze header ordering as a fingerprint signal.
   Fix: Use the header-generator package to produce headers with correct ordering. Ensure the injector applies these headers to all requests.

3. Static Content Overkill
   Explanation: Using a headless browser with fingerprint injection for endpoints that serve static HTML or JSON APIs. This increases latency and cost without benefit.
   Fix: Profile the target. If JavaScript execution is not required, use a standard HTTP client. Reserve browser automation for client-side rendered applications or sites with active anti-bot challenges.

4. Corpus Staleness
   Explanation: The Bayesian model relies on a training corpus. If the corpus lags behind current browser versions, generated fingerprints may lack attributes present in modern browsers or include deprecated ones.
   Fix: Keep the fingerprint-generator package updated. Monitor detection rates and correlate drops in success with package version updates.

5. IP/Fingerprint Mismatch
   Explanation: Using a datacenter IP with a residential-grade fingerprint, or a mobile fingerprint on a desktop-oriented site. Anti-bot services cross-reference IP reputation with fingerprint characteristics.
   Fix: Align proxy tier with fingerprint profile. Use residential proxies for high-fidelity fingerprints. Ensure device type matches the target site's expected traffic.

6. Context Leakage
   Explanation: Opening pages or contexts without applying the injector. This results in default headless properties leaking to the server.
   Fix: Implement a strict factory pattern for context/page creation. Verify injection by checking navigator.webdriver or custom properties in the page context.

7. Neglecting navigator.webdriver
   Explanation: Failing to override the navigator.webdriver flag, which is a primary indicator of automation.
   Fix: The injector handles this by default. Verify that the injection script runs before any page navigation. Do not disable the injection step.

Production Bundle

Action Checklist

• Verify Corpus Version: Ensure fingerprint-generator is on the latest version to match current browser distributions.
• Align Proxy Tier: Match proxy reputation (datacenter vs. residential) with the generated fingerprint profile.
• Test Header Order: Validate that injected headers match the expected sequence for the target browser using a debugging proxy.
• Monitor navigator.webdriver: Implement a check in the page context to confirm the flag is correctly overridden.
• Use Constraints: Always specify device, OS, and browser constraints to avoid improbable attribute combinations.
• Rotate Fingerprints: Generate new fingerprints periodically to avoid long-term tracking of a single fingerprint vector.
• Fallback Strategy: Implement logic to switch to HTTP clients for static endpoints to reduce resource usage.
• Audit Injection Scope: Ensure injection applies to all pages, workers, and iframes within the context.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-volume static data	HTTP Client	No JS execution needed; faster and cheaper.	Low
JS-heavy SPA with anti-bot	Fingerprint Suite + Playwright	Necessitates browser automation; suite mitigates detection.	Medium
CAPTCHA-heavy targets	Suite + CAPTCHA Solver	Suite handles fingerprint; solver handles challenges.	High
Mobile app simulation	Suite with mobile constraints	Generates mobile-specific fingerprints and headers.	Medium
Legacy browser testing	Suite with version constraints	Allows targeting specific browser versions for compatibility.	Medium

Configuration Template

Use this TypeScript interface to standardize fingerprint generation across your codebase.

interface FingerprintConfig {
    /** Target device types */
    devices: ('desktop' | 'mobile')[];
    /** Target operating systems */
    operatingSystems: ('windows' | 'macos' | 'linux' | 'android' | 'ios')[];
    /** Target browser engines */
    browsers?: ('chrome' | 'firefox' | 'safari' | 'edge')[];
    /** Browser version range (e.g., '110-120') */
    browserVersionRange?: string;
    /** Target locales */
    locales?: string[];
    /** Target regions */
    countries?: string[];
}

const defaultConfig: FingerprintConfig = {
    devices: ['desktop'],
    operatingSystems: ['windows', 'macos', 'linux'],
    browsers: ['chrome', 'firefox'],
    locales: ['en-US', 'en-GB'],
};

Quick Start Guide

1. Install Packages:
   Run npm install fingerprint-generator fingerprint-injector.

2. Import Modules:
   Import newInjectedContext for Playwright or FingerprintInjector for Puppeteer.

3. Create Context:
   Use the helper function to create a browser context with a generated fingerprint applied.

4. Navigate:
   Open a page and navigate to the target URL. The fingerprint and headers are automatically injected.

5. Validate:
   Check navigator.webdriver and inspect network headers to confirm injection success.