Control device metrics, screen dimensions, and input capabilities for consistent fingerprint protection across sessions.
- BotBrowser binary installed. See INSTALLATION.md.
- A profile file (
.encor.json).
Device metrics are a core part of browser fingerprinting. Screen resolution, window dimensions, device pixel ratio, touch support, and device memory all contribute to a device's fingerprint. BotBrowser gives you full control over these values through profile settings and CLI flags.
Two key flags control the primary display metrics:
--bot-config-window: Controls window dimensions, position, and device pixel ratio.--bot-config-screen: Controls screen resolution, available area, and color depth.
chromium-browser \
--bot-profile="/path/to/profile.enc" \
--headlessIn headless mode, BotBrowser defaults to profile for both window and screen settings.
chromium-browser \
--bot-profile="/path/to/profile.enc" \
--bot-config-window=1920x1080 \
--bot-config-screen=2560x1440| Value | Behavior |
|---|---|
profile |
Use the profile's window dimensions. Default for headless and Android profiles. |
real |
Use the host system's actual window dimensions. Default for desktop headful mode. |
WxH |
Set innerWidth and innerHeight directly (e.g., 1920x1080). outerWidth and outerHeight are auto-derived from the profile's window border sizes. |
| JSON | Full control over all window properties. |
JSON format example:
--bot-config-window='{"innerWidth":1920,"innerHeight":1080,"outerWidth":1936,"outerHeight":1152,"screenX":0,"screenY":0,"devicePixelRatio":2}'| Value | Behavior |
|---|---|
profile |
Use the profile's screen metrics. Default for headless and Android profiles. |
real |
Use the host system's actual screen metrics. Default for desktop headful mode. |
WxH |
Set width and height directly (e.g., 2560x1440). availWidth and availHeight are auto-derived from the profile. |
| JSON | Full control over all screen properties. |
JSON format example:
--bot-config-screen='{"width":2560,"height":1440,"availWidth":2560,"availHeight":1400,"colorDepth":24,"pixelDepth":24}'Device pixel ratio (DPR) is set through the window configuration. Common values:
| Device Type | Typical DPR |
|---|---|
| Standard desktop monitor | 1 |
| Some high-DPI Windows displays | 1.5 |
| macOS Retina | 2 |
| Modern mobile phones | 2 or 3 |
DPR affects the DPR Client Hints header and window.devicePixelRatio.
For mobile profiles, touch events are automatically enabled. The profile defines the touch point count, touch event availability, and primary pointer type.
Use --bot-mobile-force-touch to explicitly enable or disable touch events:
# Force touch events on
chromium-browser \
--bot-profile="/path/to/android-profile.enc" \
--bot-mobile-force-touch| Mode | Window Default | Screen Default |
|---|---|---|
| Headless | profile |
profile |
| Headful (desktop) | real |
real |
| Android profile | profile |
profile |
To apply profile dimensions in headful mode, explicitly set both flags:
chromium-browser \
--bot-profile="/path/to/profile.enc" \
--bot-config-window=profile \
--bot-config-screen=profileimport { chromium } from "playwright-core";
const browser = await chromium.launch({
executablePath: process.env.BOTBROWSER_EXEC_PATH,
headless: true,
args: [
"--bot-profile=/path/to/profile.enc",
"--bot-config-window=1920x1080",
"--bot-config-screen=2560x1440",
],
});
const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();const browser = await chromium.launch({
executablePath: process.env.BOTBROWSER_EXEC_PATH,
headless: true,
args: [
"--bot-profile=/path/to/android-profile.enc",
'--bot-config-window={"innerWidth":412,"innerHeight":915,"devicePixelRatio":2.625}',
'--bot-config-screen={"width":412,"height":915,"colorDepth":24}',
"--bot-mobile-force-touch",
],
});// Puppeteer: browser-level CDP session (required for BotBrowser.* commands)
const client = await browser.target().createCDPSession();
// Create a new browser context BEFORE setting flags
const context = await browser.createBrowserContext();
// Set per-context flags BEFORE creating any page
await client.send("BotBrowser.setBrowserContextFlags", {
browserContextId: context._contextId,
botbrowserFlags: [
"--bot-profile=/path/to/profile.enc",
"--bot-config-window=1366x768",
"--bot-config-screen=1920x1080",
],
});
// NOW create a page. The renderer will start with the correct flags.
const page = await context.newPage();
await page.goto("https://example.com");
// Visit a fingerprint testing site to verify device metrics
// match the profile's configuration, not the host machine
await page.goto("https://browserleaks.com/");To verify device emulation is working correctly:
- Launch BotBrowser with your device profile and visit BrowserLeaks or CreepJS.
- Confirm that screen dimensions, DPR, touch support, and hardware values match the profile's target device.
- Run the same profile on a different host machine and verify identical results.
| Problem | Solution |
|---|---|
| Window size does not match profile | In headful mode, window defaults to real. Set --bot-config-window=profile explicitly. |
| Screen dimensions show host values | In headful mode, screen defaults to real. Set --bot-config-screen=profile explicitly. |
| DPR is wrong | Set DPR via the JSON format of --bot-config-window (include devicePixelRatio in the JSON object). |
| Playwright overrides dimensions | Do not set explicit viewport options in Playwright. Let the profile control viewport dimensions. |
| Touch events not available | Use --bot-mobile-force-touch or ensure the profile is an Android/mobile profile. |
- Android Emulation. Mobile device emulation with touch support.
- Cross-Platform Profiles. Consistent device metrics across hosts.
- Multi-Account Isolation. Different device metrics per context.
- CLI Flags Reference. All display and input flags.
Related documentation: CLI Flags Reference | Profile Configuration | Advanced Features
Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.