BBRE Fingerprint and Profile Guide

What is a Browser Fingerprint?

A browser fingerprint is a collection of attributes that, taken together, create a unique identifier for a specific browser instance. When you visit a website with a regular browser, the site can read your user agent string, screen dimensions, timezone, language settings, WebGL capabilities, installed plugins, and dozens of other properties through JavaScript APIs and HTTP headers. Bot detection services like DataDome, PerimeterX, Cloudflare, and Akamai collect these signals and compare them against known patterns to determine whether a visitor is a real human or an automated tool.

The challenge for web automation is that default configurations of tools like Puppeteer, Playwright, and Selenium produce fingerprints that are trivially detectable. They expose automation-specific properties (like navigator.webdriver = true), use default screen sizes that no real user would have, and generate WebGL signatures that do not match any real GPU. Even if you override the user agent string, the rest of the fingerprint remains inconsistent, and modern detection systems check for these inconsistencies.

BBRE addresses this by generating complete, internally consistent fingerprints where every attribute matches what a real browser on a real operating system would produce. When you set the platform to "Win32", the user agent reflects a Windows browser, the screen resolution matches common Windows display configurations, the WebGL renderer corresponds to a GPU that actually exists on Windows machines, and the timezone and language settings are geographically plausible. This level of consistency is what separates BBRE from simple header-spoofing approaches.

Why Fingerprints Matter

Modern anti-bot systems do not just check individual fingerprint attributes in isolation. They analyze the relationships between attributes to detect inconsistencies. For example, if your user agent claims to be Chrome on Windows but your WebGL renderer reports an Apple GPU, that is an immediate red flag. If your screen resolution is 1920x1080 but your device pixel ratio is 3 (which would only occur on a high-DPI mobile device), the detection system knows something is wrong. BBRE ensures that all fingerprint attributes are mutually consistent, which is why it achieves significantly higher success rates than manual fingerprint configuration.

Fingerprint Attributes Collected by Detection Systems

Fingerprint Object Structure

When you send a request or create a session through the BBRE API, you can optionally include a fingerprint parameter to customize the browser identity used for that request. The fingerprint object lets you specify individual attributes that BBRE should use instead of generating them automatically. Any attributes you do not specify will be filled in by BBRE with values that are consistent with the ones you did provide.

The fingerprint parameter is accepted by the following API endpoints:

• POST /request/create - for asynchronous requests
• POST /request/execute - for synchronous requests
• POST /session/create - for session-based workflows

Complete Fingerprint Object

Example Fingerprint Object

{
  "fingerprint": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    "platform": "Win32",
    "screen": {
      "width": 1920,
      "height": 1080
    },
    "timezone": "America/New_York",
    "language": "en-US",
    "webgl": {
      "vendor": "Google Inc.",
      "renderer": "ANGLE (Intel(R) UHD Graphics 630 Direct3D11 vs_5_0 ps_5_0)"
    },
    "hardwareConcurrency": 8,
    "deviceMemory": 16
  }
}

When to Use Custom Fingerprints

In most cases, you do not need to provide a custom fingerprint at all. BBRE automatically generates realistic, consistent fingerprints for every request. However, there are specific scenarios where providing a custom fingerprint gives you an advantage or is necessary for your use case.

Scenario 1: Geographic Targeting

When you are scraping a website that serves different content based on the visitor's apparent location, you may want to set the timezone and language to match a specific region. For example, if you need to see prices in Euros on a European e-commerce site, setting the timezone to "Europe/Berlin" and the language to "de-DE" signals to the site that you are a German user. BBRE will automatically generate the rest of the fingerprint to be consistent with these geographic settings.

Scenario 2: Device-Specific Content

Some websites serve different layouts or content based on the detected device type. If you need to access the desktop version of a site, you can set a desktop user agent and a desktop-appropriate screen resolution. Conversely, if you need the mobile version, you can set a mobile user agent with a smaller screen size. This is more reliable than just changing the user agent because BBRE ensures all other fingerprint attributes match the device type you specified.

Scenario 3: Identity Persistence Across Sessions

When you need to maintain the same browser identity across multiple sessions over time (for example, when managing multiple accounts or maintaining a long-term presence on a site), you can save the profile data from one session and pass it as the fingerprint for the next session. This ensures that the site sees the same browser identity every time, which is important for avoiding detection based on fingerprint rotation patterns.

Scenario 4: Matching a Specific Browser Version

If a target website only works correctly with a specific browser version or blocks older browsers, you can set the user agent to match the required version. BBRE will adjust the rest of the fingerprint to be consistent with that browser version, including the appropriate WebGL capabilities and JavaScript API behaviors.

Default Fingerprint Behavior

When you send a request or create a session without providing a fingerprint parameter, BBRE automatically generates a complete, realistic fingerprint for that request. This is the recommended approach for most use cases because BBRE's fingerprint generation engine is specifically designed to produce identities that pass modern bot detection systems.

How Automatic Generation Works

BBRE maintains a database of real browser fingerprint profiles collected from actual devices and browser installations. When it generates a fingerprint, it selects attributes from this database and combines them in ways that are internally consistent. The generated fingerprint includes a realistic user agent string for a current browser version, a platform that matches the user agent, a screen resolution that is common for that platform, a WebGL renderer that corresponds to a real GPU available on that platform, and timezone and language settings that are geographically plausible.

Fingerprint Rotation

By default, BBRE generates a new fingerprint for each standalone request (requests made outside of a session). This means that consecutive requests to the same site will appear to come from different browsers, which is ideal for high-volume data collection where you want to distribute your traffic across many apparent identities. Within a session, the fingerprint remains constant for the lifetime of that session, ensuring that all requests within the session appear to come from the same browser.

When Default Is Sufficient

• General web scraping where you do not need a specific geographic identity
• High-volume data collection where fingerprint diversity is beneficial
• Testing and development where you just need requests to succeed
• One-off requests where identity persistence is not required
• Session-based workflows where BBRE manages the identity automatically

What is a Profile?

A profile is the complete browser identity that BBRE actually used when processing your request. While a fingerprint is what you send to BBRE as input (your preferences for the browser identity), a profile is what BBRE sends back to you as output (the actual identity that was used). The profile contains the full set of browser attributes that were presented to the target website, including any values you specified in your fingerprint plus all the additional values that BBRE generated automatically.

Profile data is valuable because it tells you exactly what identity was used for a request, which is essential for debugging, logging, and identity persistence. If a request succeeds with a particular profile, you can save that profile and reuse it as a fingerprint for future requests to maintain the same identity. If a request fails, the profile data helps you understand what identity was presented to the site, which can help diagnose why the request was blocked.

Where Profile Data Appears

Profile data is returned in the API response after a request is processed. The exact location depends on which endpoint you used:

• For POST /request/create followed by POST /request/result, the profile is in result.profile
• For POST /request/execute, the profile is in response.profile
• For session-based requests via POST /session/request, the profile is in result.profile
• In the Node.js SDK, use session.getProfile() or session.getProfileSummary()

Profile vs Fingerprint

The distinction between fingerprint and profile is important to understand. Think of the fingerprint as your request and the profile as the response. You send a fingerprint to tell BBRE what identity you want. BBRE processes your request, fills in any missing attributes, ensures everything is consistent, and returns the complete profile showing exactly what was used.

Profile Data Structure

The profile object returned by BBRE contains the complete set of browser identity attributes that were used for the request. Here is a detailed breakdown of every field in the profile response.

Full Profile Response Example

{
  "success": true,
  "task": {
    "id": "task_abc123def456",
    "status": "completed",
    "result": {
      "statusCode": 200,
      "headers": {
        "content-type": "text/html; charset=utf-8",
        "server": "nginx"
      },
      "body": "<html>...page content...</html>",
      "cookies": {
        "session_id": "xyz789",
        "preferences": "lang=en"
      },
      "profile": {
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "platform": "Win32",
        "screen": {
          "width": 1920,
          "height": 1080
        },
        "timezone": "America/New_York",
        "language": "en-US",
        "webgl": {
          "vendor": "Google Inc.",
          "renderer": "ANGLE (Intel(R) UHD Graphics 630 Direct3D11 vs_5_0 ps_5_0)"
        },
        "hardwareConcurrency": 8,
        "deviceMemory": 16
      }
    }
  }
}

Profile Summary

In addition to the full profile, the Node.js SDK provides a getProfileSummary() method that returns a condensed version of the profile data. This is useful for logging and monitoring where you need a quick overview of the identity without the full detail.

{
  "browser": "Chrome 120",
  "os": "Windows 10",
  "screen": "1920x1080",
  "timezone": "America/New_York",
  "language": "en-US"
}

Using Profiles for Consistent Identity

One of the most powerful patterns in BBRE is using profile data from a completed request as the fingerprint for subsequent requests. This creates a persistent browser identity that the target website sees as the same visitor returning over time. This pattern is essential for scenarios like account management, long-running monitoring, and any workflow where the site tracks returning visitors.

The Profile Reuse Pattern

The workflow is straightforward: make your first request without a fingerprint (or with a partial fingerprint), extract the profile from the response, save it, and then pass it as the fingerprint for all future requests. Because the profile contains the complete set of attributes that BBRE used, passing it back as a fingerprint ensures that the exact same identity is used again.

Step-by-Step Identity Persistence

1. Send your first request without a fingerprint parameter
2. Extract the profile object from the response
3. Store the profile data in your database or configuration file
4. For subsequent requests, pass the stored profile as the fingerprint parameter
5. BBRE will use the exact same identity, and the target site will see the same browser returning

Fingerprint vs Profile Comparison

Understanding the difference between fingerprints and profiles is fundamental to using BBRE effectively. The following table provides a clear comparison of these two concepts.

SDK Fingerprint and Profile Methods

The mydisctsolver-bbre Node.js SDK provides several methods for working with fingerprints and profiles. These methods make it easy to set default fingerprints, retrieve profile data from sessions, and check whether profile information is available.

client.setDefaultFingerprint(fingerprint)

Sets a default fingerprint that will be used for all requests made through this client instance unless overridden at the request level. This is useful when you want all requests from a particular client to use the same browser identity.

session.getProfile()

Returns the full profile object for the current session. This contains the complete browser identity that BBRE is using for this session, including all automatically generated attributes. Returns null if no profile data is available yet (for example, if no requests have been made in the session).

session.getProfileSummary()

Returns a condensed summary of the session's profile data. The summary includes the browser name and version, operating system, screen resolution, timezone, and language in a human-readable format. This is ideal for logging and monitoring dashboards where you need a quick overview without the full detail.

session.hasProfile()

Returns a boolean indicating whether profile data is available for the current session. Use this method to check before calling getProfile() or getProfileSummary() to avoid handling null values.

Code Examples

The following examples demonstrate common fingerprint and profile workflows using the BBRE API and the Node.js SDK. Each example shows a practical, real-world scenario that you can adapt for your own projects.

Example 1: Custom Fingerprint with SDK

This example shows how to set a default fingerprint on the client and then make requests that all use the same browser identity. The fingerprint specifies a German Windows user, and BBRE fills in the remaining attributes automatically.

const BBREClient = require("mydisctsolver-bbre");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY"
});

client.setDefaultFingerprint({
  platform: "Win32",
  timezone: "Europe/Berlin",
  language: "de-DE",
  screen: { width: 1920, height: 1080 }
});

async function scrapeGermanPrices() {
  const result = await client.get("https://shop.example.de/products", {
    mode: "passive",
    sensibility: "medium"
  });

  console.log("Status:", result.statusCode);
  console.log("Body length:", result.body.length);

  return result;
}

scrapeGermanPrices();

Example 2: Extracting and Reusing Profile Data

This example demonstrates the profile reuse pattern. The first request is made without a fingerprint, the profile is extracted from the response, and then subsequent requests use that profile as their fingerprint to maintain the same identity.

const BBREClient = require("mydisctsolver-bbre");
const fs = require("fs");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY"
});

const PROFILE_FILE = "./saved-profile.json";

async function getOrCreateProfile() {
  if (fs.existsSync(PROFILE_FILE)) {
    const saved = JSON.parse(fs.readFileSync(PROFILE_FILE, "utf8"));
    console.log("Loaded saved profile:", saved.userAgent);
    return saved;
  }

  const result = await client.get("https://example.com", {
    mode: "passive",
    sensibility: "low"
  });

  const profile = result.profile;
  fs.writeFileSync(PROFILE_FILE, JSON.stringify(profile, null, 2));
  console.log("Saved new profile:", profile.userAgent);

  return profile;
}

async function scrapeWithConsistentIdentity() {
  const profile = await getOrCreateProfile();

  client.setDefaultFingerprint(profile);

  const pages = [
    "https://example.com/page/1",
    "https://example.com/page/2",
    "https://example.com/page/3"
  ];

  for (const url of pages) {
    const result = await client.get(url, {
      mode: "passive",
      sensibility: "medium"
    });

    console.log("Fetched:", url, "Status:", result.statusCode);
  }
}

scrapeWithConsistentIdentity();

Example 3: Session Profile Access

When working with sessions, you can access the profile data through the session object. This example creates an adaptive session, performs some browser actions, and then retrieves the profile information.

const BBREClient = require("mydisctsolver-bbre");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY"
});

async function sessionWithProfile() {
  const session = await client.createSession({
    mode: "adaptive",
    sensibility: "high",
    timeout: 300
  });

  await session.start();
  const browser = session.browser();

  await browser.navigate("https://app.example.com/dashboard");
  await browser.waitForSelector(".content-loaded");

  if (session.hasProfile()) {
    const profile = session.getProfile();
    console.log("User Agent:", profile.userAgent);
    console.log("Platform:", profile.platform);
    console.log("Screen:", profile.screen.width + "x" + profile.screen.height);
    console.log("Timezone:", profile.timezone);
    console.log("Language:", profile.language);

    const summary = session.getProfileSummary();
    console.log("Summary:", JSON.stringify(summary));
  }

  await session.close();
}

sessionWithProfile();

Example 4: Custom Fingerprint via API (Python)

This example shows how to send a custom fingerprint directly through the BBRE API using Python, and how to extract the profile from the response for future use.

import requests
import json

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

custom_fingerprint = {
    "platform": "MacIntel",
    "timezone": "America/Los_Angeles",
    "language": "en-US",
    "screen": {"width": 2560, "height": 1440},
    "webgl": {
        "vendor": "Apple",
        "renderer": "Apple M1 Pro"
    }
}

response = requests.post(
    API_BASE + "/request/execute",
    headers=headers,
    json={
        "url": "https://example.com/products",
        "method": "GET",
        "mode": "passive",
        "sensibility": "medium",
        "fingerprint": custom_fingerprint
    }
)

data = response.json()
profile = data["task"]["result"]["profile"]

print("Used User Agent:", profile["userAgent"])
print("Used Platform:", profile["platform"])
print("Used Screen:", profile["screen"])
print("Used Timezone:", profile["timezone"])

with open("saved_profile.json", "w") as f:
    json.dump(profile, f, indent=2)

print("Profile saved for future use")

Example 5: Profile Reuse via API (Python)

This example loads a previously saved profile and uses it as the fingerprint for a new request, ensuring the same browser identity is presented to the target website.

import requests
import json

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY
}

with open("saved_profile.json", "r") as f:
    saved_profile = json.load(f)

urls = [
    "https://example.com/products?page=1",
    "https://example.com/products?page=2",
    "https://example.com/products?page=3"
]

for url in urls:
    response = requests.post(
        API_BASE + "/request/execute",
        headers=headers,
        json={
            "url": url,
            "method": "GET",
            "mode": "passive",
            "sensibility": "medium",
            "fingerprint": saved_profile
        }
    )

    data = response.json()
    status = data["task"]["result"]["statusCode"]
    body_length = len(data["task"]["result"]["body"])
    print(f"Fetched {url} - Status: {status}, Body: {body_length} bytes")

Example 6: Custom Fingerprint via cURL

This example demonstrates sending a request with a custom fingerprint using cURL. The fingerprint is included in the JSON request body alongside the other request parameters.

curl -X POST https://bbre-solver-api.mydisct.com/request/execute   -H "Content-Type: application/json"   -H "x-api-key: YOUR_API_KEY"   -d '{
    "url": "https://example.com/products",
    "method": "GET",
    "mode": "passive",
    "sensibility": "medium",
    "fingerprint": {
      "platform": "Win32",
      "timezone": "Europe/London",
      "language": "en-GB",
      "screen": {"width": 1366, "height": 768}
    }
  }'

Example 7: Session with Custom Fingerprint via cURL

When creating a session with a custom fingerprint, the fingerprint is applied to all requests made within that session. This ensures a consistent identity throughout the session lifetime.

curl -X POST https://bbre-solver-api.mydisct.com/session/create   -H "Content-Type: application/json"   -H "x-api-key: YOUR_API_KEY"   -d '{
    "mode": "adaptive",
    "sensibility": "high",
    "timeout": 300,
    "fingerprint": {
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
      "platform": "MacIntel",
      "timezone": "America/Chicago",
      "language": "en-US",
      "screen": {"width": 1440, "height": 900}
    }
  }'

Example 8: Asynchronous Request with Fingerprint via cURL

For asynchronous workflows, you include the fingerprint in the create request and then retrieve the profile from the result response.

curl -X POST https://bbre-solver-api.mydisct.com/request/create   -H "Content-Type: application/json"   -H "x-api-key: YOUR_API_KEY"   -d '{
    "url": "https://example.com/data",
    "method": "GET",
    "mode": "passive",
    "sensibility": "low",
    "fingerprint": {
      "timezone": "Asia/Tokyo",
      "language": "ja-JP"
    }
  }'

curl -X POST https://bbre-solver-api.mydisct.com/request/result   -H "Content-Type: application/json"   -H "x-api-key: YOUR_API_KEY"   -d '{
    "taskId": "TASK_ID_FROM_CREATE_RESPONSE"
  }'

Advanced Fingerprint Patterns

Beyond the basic usage patterns, there are several advanced strategies for fingerprint management that can improve your success rates and help you handle complex automation scenarios.

Fingerprint Pools

For high-volume scraping operations, you can create a pool of saved profiles and rotate through them. Each profile represents a distinct browser identity, and by cycling through them, you distribute your requests across multiple apparent visitors. This is more effective than using random fingerprints because each identity in the pool is a complete, consistent profile that has been validated against real websites.

const BBREClient = require("mydisctsolver-bbre");
const fs = require("fs");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY"
});

const POOL_FILE = "./fingerprint-pool.json";

async function buildFingerprintPool(size) {
  const pool = [];

  for (let i = 0; i < size; i++) {
    const result = await client.get("https://example.com", {
      mode: "passive",
      sensibility: "low"
    });

    pool.push(result.profile);
  }

  fs.writeFileSync(POOL_FILE, JSON.stringify(pool, null, 2));
  return pool;
}

async function scrapeWithPool(urls) {
  let pool;

  if (fs.existsSync(POOL_FILE)) {
    pool = JSON.parse(fs.readFileSync(POOL_FILE, "utf8"));
  } else {
    pool = await buildFingerprintPool(10);
  }

  for (let i = 0; i < urls.length; i++) {
    const fingerprint = pool[i % pool.length];

    const result = await client.get(urls[i], {
      mode: "passive",
      sensibility: "medium",
      fingerprint: fingerprint
    });

    console.log("URL:", urls[i], "Status:", result.statusCode);
  }
}

const targetUrls = [
  "https://example.com/page/1",
  "https://example.com/page/2",
  "https://example.com/page/3",
  "https://example.com/page/4",
  "https://example.com/page/5"
];

scrapeWithPool(targetUrls);

Geographic Fingerprint Mapping

When scraping region-specific content, you can create fingerprint templates for different geographic regions and apply the appropriate one based on the target URL or content requirements. This ensures that the browser identity matches the expected visitor profile for each region.

const BBREClient = require("mydisctsolver-bbre");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY"
});

const regionFingerprints = {
  us: {
    timezone: "America/New_York",
    language: "en-US",
    platform: "Win32",
    screen: { width: 1920, height: 1080 }
  },
  uk: {
    timezone: "Europe/London",
    language: "en-GB",
    platform: "Win32",
    screen: { width: 1366, height: 768 }
  },
  de: {
    timezone: "Europe/Berlin",
    language: "de-DE",
    platform: "Win32",
    screen: { width: 1920, height: 1080 }
  },
  jp: {
    timezone: "Asia/Tokyo",
    language: "ja-JP",
    platform: "Win32",
    screen: { width: 1920, height: 1080 }
  }
};

async function scrapeByRegion(url, region) {
  const fingerprint = regionFingerprints[region];

  const result = await client.get(url, {
    mode: "passive",
    sensibility: "medium",
    fingerprint: fingerprint
  });

  return result;
}

async function main() {
  const usResult = await scrapeByRegion("https://shop.example.com/prices", "us");
  const ukResult = await scrapeByRegion("https://shop.example.com/prices", "uk");
  const deResult = await scrapeByRegion("https://shop.example.com/prices", "de");

  console.log("US prices page length:", usResult.body.length);
  console.log("UK prices page length:", ukResult.body.length);
  console.log("DE prices page length:", deResult.body.length);
}

main();

Best Practices

Common Issues

Issue 1: Inconsistent Fingerprint Attributes

Solution: Either provide only the attributes you care about and let BBRE generate the rest, or ensure that all attributes you provide are mutually consistent. If you set a Windows user agent, use "Win32" as the platform. If you set a Mac user agent, use "MacIntel". The safest approach is to specify only the timezone and language, and let BBRE handle the technical attributes like user agent, platform, and WebGL.

Issue 2: Profile Data Not Available

Solution: Profile data becomes available after the first request is processed in the session. If you just created the session but have not made any requests yet, the profile will be null. Make at least one request (or navigate to a page in adaptive mode) before attempting to read the profile. Use session.hasProfile() to check availability before accessing profile data.

Issue 3: Fingerprint Not Applied to Requests

Solution: Check whether you are also passing a fingerprint at the request level. Request-level fingerprints override the default fingerprint set on the client. Also verify that the attributes you specified are valid. For example, if you set an invalid timezone string, BBRE may fall back to generating its own value. The profile in the response always shows the actual values that were used, so compare it with your input to identify which attributes were overridden.

Related Documentation

• BBRE Engine Overview - Learn about passive and adaptive modes, sensibility levels, and the overall BBRE architecture
• Quick Start Guide - Get started with your first BBRE request, including basic fingerprint usage
• Session Create API - Detailed documentation for creating sessions with custom fingerprints
• Request Create API - Documentation for the asynchronous request endpoint, including the fingerprint parameter
• Request Execute API - Documentation for the synchronous request endpoint with fingerprint support
• Hybrid Workflow Guide - Learn how to combine passive and adaptive modes, including fingerprint management across mode switches