Device Emulation

Control device metrics, screen dimensions, and input capabilities for consistent fingerprint protection across sessions.

Prerequisites

BotBrowser binary installed. See INSTALLATION.md.
A profile file (.enc or .json).

Overview

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.

Quick Start

Use profile defaults (recommended for headless)


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --headless

In headless mode, BotBrowser defaults to profile for both window and screen settings.

Custom dimensions


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-config-window=1920x1080 \
  --bot-config-screen=2560x1440

How It Works

Window Dimensions (`--bot-config-window`)

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}'

Screen Dimensions (`--bot-config-screen`)

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

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.

Touch Emulation

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

Headful vs. Headless Defaults

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=profile

Common Scenarios

Fixed viewport for consistent screenshots


import { 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();

Mobile dimensions with high DPR


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",
  ],
});

Per-context device metrics (ENT Tier3)


// 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/");

Verify device consistency

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.

Troubleshooting / FAQ

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.

Next Steps

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.