How to Use fingerprint-suite in 5 Steps in 2025

fingerprint-suite is a modular toolkit designed to generate and inject realistic browser fingerprints into your automated browsers—helping you bypass even the toughest anti-bot detection. In this guide, we’ll walk through how to get it up and running with both Playwright and Puppeteer, so your web scraping efforts stay invisible.

If you’ve ever had your scraper blocked by sites like Cloudflare, DataDome, or PerimeterX, you know the frustration. One minute your crawler is humming along, the next—it’s flagged, stopped, or banned.

I’ve been there myself, spending way too many hours trying every trick in the book, only to hit a wall because of one thing: browser fingerprinting. That’s right. Headless browsers like Puppeteer and Playwright leave telltale signs that scream “I’m a bot!”—and modern sites are quick to pick up on them.

Enter fingerprint-suite. Built by the team at Apify, this toolkit crafts realistic browser fingerprints and seamlessly injects them into your automation setup. The result? Your bot looks and behaves just like a regular user.

In this walkthrough, I’ll show you exactly how to get started—from installation to more advanced anti-detection tactics. Whether you're controlling browsers directly or just sending HTTP requests, you’ll find methods here to help you stay undetected.

What You’ll Learn

• How to install and set up fingerprint-suite’s key packages
• The right way to generate realistic browser fingerprints
• How to inject those fingerprints into Playwright and Puppeteer
• Smart strategies to evade detection with minimal effort
• How to use fingerprints in request-based scraping setups

Why You Can Trust This Guide

The Challenge: Traditional scrapers are no match for modern fingerprinting defenses. Without realistic fingerprints, your bots get blocked—fast.

The Fix: fingerprint-suite arms you with everything you need to mimic real browsers. It generates authentic fingerprints and handles the injection automatically.

The Proof: This toolkit includes a set of powerful npm packages like header-generator, fingerprint-generator, and fingerprint-injector. Together, they form a reliable system that’s already proven effective against today’s most aggressive anti-bot services.

Step 1: Install the Required Packages

To start, you’ll need to bring in the core fingerprint-suite components. The toolkit is modular, so you can install only what you need based on your project type.

For Playwright Users:

npm install fingerprint-injector fingerprint-generator playwright

For Puppeteer Users:

npm install fingerprint-injector fingerprint-generator puppeteer

For Header-Only Use Cases:

npm install header-generator

Pro Tip: For best results, use fingerprint-injector alongside fingerprint-generator. This combo ensures proper structure and compatibility.

Common Pitfalls to Watch Out For:

• Avoid global installs—stick to project-level
• Make sure you're running Node.js version 14 or higher
• Double-check compatibility between your browser and fingerprint-suite versions

Step 2: Generate Realistic Browser Fingerprints

Once installed, your next step is to create fingerprints that closely match actual browser environments. The more aligned your fingerprint is with the browser and OS in use, the harder it is to detect.

Basic Fingerprint Generation:

import FingerprintGenerator from 'fingerprint-generator';

// Create generator instance with constraints
const fingerprintGenerator = new FingerprintGenerator({
    browsers: [
        { name: 'chrome', minVersion: 90 },
        { name: 'firefox', minVersion: 88 }
    ],
    devices: ['desktop', 'mobile'],
    operatingSystems: ['windows', 'macos', 'linux']
});

// Generate a fingerprint
const { fingerprint, headers } = fingerprintGenerator.getFingerprint({
    locales: ['en-US', 'en'],
    httpVersion: '2'
});

console.log('Generated fingerprint:', fingerprint.userAgent);

Advanced Fingerprint Constraints:

// Mobile-specific fingerprint
const mobileFingerprint = fingerprintGenerator.getFingerprint({
    devices: ['mobile'],
    operatingSystems: ['ios', 'android'],
    browsers: [{ name: 'chrome', minVersion: 100 }]
});

// Desktop Windows Chrome only
const desktopFingerprint = fingerprintGenerator.getFingerprint({
    devices: ['desktop'],
    operatingSystems: ['windows'],
    browsers: [{ name: 'chrome', minVersion: 110 }]
});

Heads Up: The output changes every time you generate a fingerprint—even with identical constraints. This randomness is intentional and essential. It prevents pattern detection that could compromise your stealth.

Step 3: Inject Fingerprints into Your Browser

Here’s where things get interesting. This step integrates the fingerprint directly into your browser session, making it blend in seamlessly with normal users.

Playwright Example:

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

(async () => {
    const browser = await chromium.launch({ 
        headless: false // Use headful mode for better evasion
    });
    
    // Create context with injected fingerprint
    const context = await newInjectedContext(browser, {
        fingerprintOptions: {
            devices: ['desktop'],
            operatingSystems: ['windows'],
            browsers: [{ name: 'chrome', minVersion: 110 }]
        },
        // Additional Playwright context options
        newContextOptions: {
            viewport: { width: 1920, height: 1080 },
            geolocation: { latitude: 40.7128, longitude: -74.0060 },
            permissions: ['geolocation']
        }
    });
    
    const page = await context.newPage();
    await page.goto('https://bot.sannysoft.com');
    
    // Your scraping logic here
    
    await browser.close();
})();

Puppeteer Example:

import puppeteer from 'puppeteer';
import { newInjectedPage } from 'fingerprint-injector';

(async () => {
    const browser = await puppeteer.launch({ 
        headless: false,
        args: ['--no-sandbox', '--disable-setuid-sandbox']
    });
    
    // Create page with injected fingerprint
    const page = await newInjectedPage(browser, {
        fingerprintOptions: {
            devices: ['mobile'],
            operatingSystems: ['android'],
            browsers: [{ name: 'chrome' }]
        }
    });
    
    await page.goto('https://example.com');
    
    // Your scraping logic here
    
    await browser.close();
})();

No-Browser, Request-Only Setup:

Don’t need a browser? If you’re just pulling pages without rendering, headers alone might be enough.

import { HeaderGenerator } from 'header-generator';
import fetch from 'node-fetch';

const headerGenerator = new HeaderGenerator({
    browsers: ['chrome', 'firefox'],
    operatingSystems: ['windows', 'linux']
});

const headers = headerGenerator.getHeaders({
    httpVersion: '2',
    locales: ['en-US']
});

// Use with your HTTP client
const response = await fetch('https://example.com', {
    headers: {
        ...headers,
        'Accept': 'text/html,application/xhtml+xml',
        'Accept-Encoding': 'gzip, deflate, br'
    }
});

Technical Note: The request-only method is quick and resource-efficient, but it won’t cut it for JS-heavy pages or interactive flows.

Step 4: Test and Validate Your Setup

Before putting your bot to work, make sure it actually passes inspection. Testing now can save you a lot of pain later.

Fingerprint Test Function:

async function testFingerprint(page) {
    // Test 1: Check basic fingerprint properties
    const fingerprint = await page.evaluate(() => ({
        userAgent: navigator.userAgent,
        webdriver: navigator.webdriver,
        plugins: navigator.plugins.length,
        languages: navigator.languages,
        platform: navigator.platform,
        hardwareConcurrency: navigator.hardwareConcurrency
    }));
    
    console.log('Fingerprint test results:', fingerprint);
    
    // Test 2: Visit fingerprinting test sites
    await page.goto('https://bot.sannysoft.com');
    await page.screenshot({ path: 'bot-test.png' });
    
    // Test 3: Check for WebDriver detection
    const isBot = await page.evaluate(() => {
        return window.navigator.webdriver || 
               window.document.__selenium_unwrapped ||
               window.callPhantom || 
               window._phantom;
    });
    
    console.log('Bot detection:', isBot ? 'DETECTED' : 'PASSED');
}

Advanced Validation Using CreepJS:

async function advancedValidation(page) {
    await page.goto('https://abrahamjuliot.github.io/creepjs/');
    
    // Wait for fingerprint analysis
    await page.waitForTimeout(5000);
    
    // Extract trust score
    const trustScore = await page.evaluate(() => {
        const scoreElement = document.querySelector('.visitor-rating');
        return scoreElement ? scoreElement.textContent : 'Unknown';
    });
    
    console.log('CreepJS Trust Score:', trustScore);
}

What to Look For:

• WebDriver should be undetectable
• Plugins should appear present (not zero)
• The overall fingerprint should mimic a real user closely
• Trust scores on testing tools like CreepJS should land in a realistic range

Step 5: Implement Advanced Anti-Detection Strategies

Once you've got fingerprinting down, it’s time to layer in even more evasion strategies. These extras help ensure long-term success across aggressive anti-bot setups.

1. Use Proxy Rotation + Matching Fingerprints:

import { newInjectedContext } from 'fingerprint-injector';

async function createStealthContext(browser, proxyConfig) {
    // Match fingerprint to proxy location
    const context = await newInjectedContext(browser, {
        fingerprintOptions: {
            devices: ['desktop'],
            operatingSystems: ['windows'],
            locales: [proxyConfig.locale || 'en-US']
        },
        newContextOptions: {
            proxy: {
                server: `http://${proxyConfig.host}:${proxyConfig.port}`,
                username: proxyConfig.username,
                password: proxyConfig.password
            },
            timezone: proxyConfig.timezone || 'America/New_York'
        }
    });
    
    return context;
}

2. Simulate Human Behavior:

async function humanizeInteractions(page) {
    // Random mouse movements
    await page.mouse.move(
        Math.random() * 1000, 
        Math.random() * 700
    );
    
    // Variable typing speed
    await page.type('input[type="text"]', 'search query', {
        delay: 50 + Math.random() * 150
    });
    
    // Random scroll patterns
    await page.evaluate(() => {
        const scrollHeight = document.body.scrollHeight;
        const randomScroll = Math.random() * scrollHeight * 0.7;
        window.scrollTo({
            top: randomScroll,
            behavior: 'smooth'
        });
    });
    
    // Random wait times
    await page.waitForTimeout(2000 + Math.random() * 3000);
}

3. Maintain Persistent Fingerprint Sessions:

class FingerprintSession {
    constructor() {
        this.sessions = new Map();
    }
    
    async getOrCreateFingerprint(sessionId, generator) {
        if (!this.sessions.has(sessionId)) {
            const { fingerprint } = generator.getFingerprint();
            this.sessions.set(sessionId, fingerprint);
        }
        return this.sessions.get(sessionId);
    }
    
    clearSession(sessionId) {
        this.sessions.delete(sessionId);
    }
}

// Usage
const sessionManager = new FingerprintSession();
const fingerprint = await sessionManager.getOrCreateFingerprint(
    'user123', 
    fingerprintGenerator
);

4. Rotate Fingerprints Periodically:

// Rotate fingerprints periodically
const rotationInterval = 30 * 60 * 1000; // 30 minutes

setInterval(async () => {
    // Close current context
    await context.close();
    
    // Create new context with fresh fingerprint
    context = await newInjectedContext(browser, {
        fingerprintOptions: {
            devices: ['desktop'],
            operatingSystems: ['windows']
        }
    });
    
    console.log('Fingerprint rotated');
}, rotationInterval);

This step can help avoid detection in long scraping sessions. A fresh fingerprint every so often adds another layer of unpredictability.

Final Thoughts

fingerprint-suite is powerful—but like any stealth tool, it works best when you understand how to use it thoughtfully. While it does a great job patching the major leaks that give away bots, remember that no solution is 100% foolproof.

If you're serious about scraping at scale:

• Test your setup on real target sites before full deployment
• Mix fingerprinting with other detection-avoidance strategies
• Keep a close eye on your detection rates and adapt accordingly
• Don’t hesitate to explore commercial anti-detect solutions if needed

And above all, remember: anti-bot tech evolves constantly. Staying ahead means keeping your approach flexible and informed.