### Complete Project Setup Example

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

A full example demonstrating how to import the library, set the service key, fetch and apply a fingerprint, launch a browser, navigate to a page, and print viewport details. This code can be copied and run directly.

```js
const { plugin } = require('playwright-with-fingerprints');

// Set the service key for the plugin (you can buy it here https://bablosoft.com/directbuy/FingerprintSwitcher/2).
// Leave an empty string to use the free version.
plugin.setServiceKey('');

(async () => {
  // Get a fingerprint from the server:
  const fingerprint = await plugin.fetch({
    tags: ['Microsoft Windows', 'Chrome'],
  });

  // Apply fingerprint:
  plugin.useFingerprint(fingerprint);

  // Launch the browser instance:
  const browser = await plugin.launch();

  // The rest of the code is the same as for a standard `playwright` library:
  const page = await browser.newPage();
  await page.goto('https://example.com');

  // Print the browser viewport size:
  console.log(
    'Viewport:',
    await page.evaluate(() => ({
      deviceScaleFactor: window.devicePixelRatio,
      width: document.documentElement.clientWidth,
      height: document.documentElement.clientHeight,
    }))
  );

  await browser.close();
})();
```

--------------------------------

### Install playwright-with-fingerprints

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Install the plugin and Playwright using npm, pnpm, or yarn.

```bash
npm i playwright-with-fingerprints playwright
# or with pnpm / yarn
pnpm i playwright-with-fingerprints playwright
yarn add playwright-with-fingerprints playwright
```

--------------------------------

### Playwright with Fingerprints Setup and Launch

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

This snippet demonstrates how to integrate `playwright-with-fingerprints`. It shows importing the plugin, setting a service key, fetching a fingerprint, applying it, and launching the browser using `plugin.launch`. This setup ensures a new fingerprint is applied on each run, leading to different test results.

```javascript
/* With fingerprints */

// Import `playwright-with-fingerprints` instead of `playwright`
// const { chromium } = require('playwright');
const { plugin } = require('playwright-with-fingerprints');

// Set the service key for the plugin (you can buy it here https://bablosoft.com/directbuy/FingerprintSwitcher/2).
// Leave an empty string to use the free version.
plugin.setServiceKey('');

(async () => {
  // Obtain a fingerprint from the server. The resulting variable contains a string - it can be stored for later use:
  const fingerprint = await plugin.fetch({
    tags: ['Microsoft Windows', 'Chrome'],
  });

  // Apply fingerprint - after calling the `useFingerprint` method, the browser will be launched with a fingerprint:
  plugin.useFingerprint(fingerprint);

  // Replace `chromium.launch` method call with `plugin.launch`:
  // const browser = await chromium.launch();
  const browser = await plugin.launch();

  // The rest of the code is the same as for the standard `playwright` library:
  const page = await browser.newPage();
  await page.goto('https://browserleaks.com/canvas', { waitUntil: 'networkidle' });

  console.log('Canvas signature:', await page.$eval('#crc', (el) => el.innerText));

  await browser.close();
})();
```

--------------------------------

### Configure Plugin Working Folder

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Sets the directory where the plugin engine will be installed. The default is './data'.

```javascript
// Set the folder where the plugin engine will be installed:
plugin.setWorkingFolder('./engine');
```

--------------------------------

### Install playwright-with-fingerprints

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Install the plugin using npm, pnpm, or yarn. The playwright or playwright-core packages must also be installed.

```bash
npm i playwright-with-fingerprints
# or
pnpm i playwright-with-fingerprints
# or
yarn add playwright-with-fingerprints
```

```bash
npm i playwright
# or
npm i playwright-core
```

--------------------------------

### plugin.launch(options?)

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Launches Playwright and a browser instance with specified arguments and options. This is the primary method for starting a browser session.

```APIDOC
## plugin.launch(options?)

### Description
Launches Playwright and launches a browser instance with given arguments and options when specified.

### Method
Not specified (likely a JavaScript function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- `options` (PluginLaunchOptions)? - Set of configurable options to set on the browser.

### Returns
- `Promise<Playwright.Browser>` - Promise which resolves to a browser instance.

### Request Example
```javascript
// Example usage (assuming plugin is imported and initialized)
// const browser = await plugin.launch({ slowMo: 50 });
```

### Response
#### Success Response (200)
- `Playwright.Browser` - A Playwright browser instance.
```

--------------------------------

### Troubleshooting Code Formatting

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Example of how to format code when reporting issues. Use markdown tags for code blocks.

```javascript
// your code
```

--------------------------------

### plugin.spawn(options?)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Starts a custom Chromium process without attaching Playwright's automation protocol. It returns a browser handle that can be used with `chromium.connect()` for advanced scenarios like remote debugging.

```APIDOC
## plugin.spawn(options?)

### Description
Starts the custom Chromium process without connecting Playwright's automation protocol. Returns a browser handle whose `.url` property can be passed to `chromium.connect()`, enabling advanced scenarios such as remote debugging or connecting an existing session to Playwright after the fact.

### Method
```javascript
plugin.spawn(options?: object): Promise<{ url: string, close: () => Promise<void> }>
```

### Parameters
#### Request Body
- **options** (object) - Optional - Configuration options for spawning the browser.
  - **headless** (boolean) - Optional - Whether to run in headless mode.
```

--------------------------------

### Standard Playwright Browser Launch

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

This is a standard Playwright setup for launching a browser and verifying canvas signature. Results remain consistent across runs on the same machine.

```javascript
/* Without fingerprints */
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();

  const page = await browser.newPage();
  await page.goto('https://browserleaks.com/canvas', { waitUntil: 'networkidle' });

  console.log('Canvas signature:', await page.$eval('#crc', (el) => el.innerText));

  await browser.close();
})();
```

--------------------------------

### Get Browser Versions with plugin.versions

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Retrieve available browser versions using `plugin.versions`. The 'extended' format provides additional metadata. Versions are always sorted in descending order.

```javascript
const { plugin } = require('playwright-with-fingerprints');

(async () => {
  // Simple list
  const simple = await plugin.versions();
  console.log('Latest:', simple[0]);
  // Expected: '128.0.6613.85' (or whichever is newest)

  // Extended list — pick the version that matches a fingerprint tag
  const extended = await plugin.versions('extended');
  extended.forEach(({ browser_version, ...meta }) => {
    console.log(browser_version, meta);
  });

  // Use the newest version
  plugin.useBrowserVersion(simple[0]);
})();
```

--------------------------------

### Configure Plugin Engine Timeout

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Sets the timeout for installing or downloading the engine. The default is 600000 milliseconds.

```javascript
// Set the timeout used when installing/downloading engine:
plugin.setEngineTimeout(10 * 60000);
```

--------------------------------

### Fingerprint Usage Example

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

This snippet demonstrates how to configure Playwright with fingerprinting options. Note that 'PerfectCanvas' technology and other advanced features are not available in the free version.

```javascript
const { chromium } = require('playwright-extra');
const pluginStealth = require('playwright-extra-plugin-stealth');

chromium.use(pluginStealth());

(async () => {
  const browser = await chromium.launch({
    headless: false,
    // minBrowserVersion: 132,
  });
  const page = await browser.newPage();
  await page.goto('https://bot.sannysoft.com/');
  await page.screenshot({ path: 'bot.png', fullPage: true });
  await browser.close();
})();
```

--------------------------------

### Spawn Custom Chromium with plugin.spawn

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Use `plugin.spawn` to start a custom Chromium process without attaching Playwright's automation protocol. The returned handle's `.url` can be used with `chromium.connect` for advanced scenarios like remote debugging.

```javascript
const { chromium } = require('playwright');
const { plugin } = require('playwright-with-fingerprints');

plugin.setServiceKey('');

(async () => {
  const fingerprint = await plugin.fetch({ tags: ['Microsoft Windows', 'Chrome'] });
  plugin.useFingerprint(fingerprint);

  // Start the process without attaching automation
  const chrome = await plugin.spawn({ headless: false });

  // Connect via standard Playwright API
  const browser = await chromium.connect(chrome.url);

  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log('Title:', await page.title());

  await browser.close();
  await chrome.close();
})();
```

--------------------------------

### plugin.spawn(options?)

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Launches a browser instance with given arguments and options when specified. This method is suitable for creating isolated browser sessions.

```APIDOC
## plugin.spawn(options?)

### Description
Launches a browser instance with given arguments and options when specified.

### Method
Not specified (likely a JavaScript function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- `options` (Options)? - Launcher options that only apply to the browser when using the `spawn` method.

### Returns
- `Promise<Browser>` - Promise which resolves to a browser instance.

### Request Example
```javascript
// Example usage (assuming plugin is imported and initialized)
// const browser = await plugin.spawn({ headless: false });
```

### Response
#### Success Response (200)
- `Browser` - A browser instance.
```

--------------------------------

### Launch Browser with Proxy Argument

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Configure a proxy directly through launch arguments using the `--proxy-server` option. This method is less flexible than `useProxy` as it does not support additional options like timezone or geolocation changes.

```javascript
const { plugin } = require('playwright-with-fingerprints');

const browser = await plugin.launch({
  // The syntax for specifying an argument value
  // is exactly the same as for using a separate method.
  args: ['--proxy-server=https://127.0.0.1:8080'],
});
```

--------------------------------

### Configure Proxy with Options

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Use `useProxy` to set up a proxy server and apply additional browser options such as changing the timezone and geolocation according to the proxy settings. Ensure the proxy type (https or socks5) is specified.

```javascript
const { plugin } = require('playwright-with-fingerprints');

plugin.useProxy('127.0.0.1:8080', {
  // Change browser timezone according to proxy:
  changeTimezone: true,
  // Replace browser geolocation according to proxy:
  changeGeolocation: true,
});
```

--------------------------------

### plugin.launchPersistentContext(userDataDir, options?)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Launches the browser with a persistent profile stored at `userDataDir`. This is the preferred method — `launch()` is a convenience alias that calls it with an empty directory string. Returns `Promise<BrowserContext>`.

```APIDOC
## plugin.launchPersistentContext(userDataDir, options?)

### Description
Launches the browser with a persistent profile stored at `userDataDir`. This is the preferred method — `launch()` is a convenience alias that calls it with an empty directory string.

### Method
`plugin.launchPersistentContext(userDataDir, options?)

### Parameters
#### Path Parameters
- **userDataDir** (string) - Required - The directory path where the persistent profile is stored.

#### Options
- `options` (object) - Optional. Configuration options for launching the browser context.

### Returns
`Promise<BrowserContext>`

### Request Example
```javascript
const path = require('path');
const { plugin } = require('playwright-with-fingerprints');

(async () => {
  const profileDir = path.resolve('./my-profile');

  const context = await plugin.launchPersistentContext(profileDir, {
    headless: false,
  });

  const page = await context.newPage();
  await page.goto('chrome://version');

  const el = await page.waitForSelector('#profile_path');
  console.log('Profile path:', await el.evaluate((e) => e.textContent));

  await context.close(); // also closes the browser
})();
```
```

--------------------------------

### plugin.useProxy(value?, options?)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Stages a proxy for the next browser launch. Supports `https` / `socks5` proxies with or without credentials. Additional options can automatically adjust the browser's timezone and geolocation to match the proxy's exit node. Returns `this` for chaining. Calling this overrides any `--proxy-server` argument passed to `launch()`.

```APIDOC
## plugin.useProxy(value?, options?)

### Description
Stages a proxy for the next browser launch. Supports `https` / `socks5` proxies with or without credentials. Additional options can automatically adjust the browser's timezone and geolocation to match the proxy's exit node.

### Method
`plugin.useProxy(value?, options?)

### Parameters
#### Value
- `value` (string) - Optional. The proxy server address. Many address formats are accepted, e.g., '127.0.0.1:8080', 'https://127.0.0.1:8080', 'socks5://127.0.0.1:9762', 'username:password@127.0.0.1:8080'. If an empty string is provided, the proxy is reset.

#### Options
- `options` (object) - Optional. Additional configuration for the proxy.
  - `detectExternalIP` (boolean) - Skip IP detection request at startup.
  - `changeTimezone` (boolean) - Sync browser timezone to proxy country.
  - `changeGeolocation` (boolean) - Sync `navigator.geolocation` to proxy location.

### Returns
`this` for chaining.

### Request Example
```javascript
const { plugin } = require('playwright-with-fingerprints');

plugin.useProxy('socks5://127.0.0.1:9762', {
  detectExternalIP: false,
  changeTimezone: true,
  changeGeolocation: true,
});

const browser = await plugin.launch();
const page = await browser.newPage();
await page.goto('https://canhazip.com/', { waitUntil: 'domcontentloaded' });

console.log('External IP:', await page.evaluate(() => document.body.innerText.trim()));

await browser.close();

// Reset proxy for subsequent launches
plugin.useProxy('');
```
```

--------------------------------

### Launch Browser with Fingerprints

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Launches a new browser instance with specified arguments and headless mode. Use this for standard browser automation with fingerprinting capabilities.

```javascript
const { plugin } = require('playwright-with-fingerprints');

const browser = await plugin.launch({
  args: ['--mute-audio'],
  headless: true,
});
```

--------------------------------

### Configure Proxy and Fingerprint for Browser Launch

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Use `useProxy` and `useFingerprint` before launching a browser to set custom configurations. These settings only affect the next browser launch and can be chained.

```javascript
const { plugin } = require('playwright-with-fingerprints');

// Set the service key for the plugin (you can buy it here https://bablosoft.com/directbuy/FingerprintSwitcher/2).
// Leave an empty string to use the free version.
plugin.setServiceKey('');

const fingerprint = await plugin.fetch({
  tags: ['Microsoft Windows', 'Chrome'],
});

plugin.useProxy('127.0.0.1:8080').useFingerprint(fingerprint);
```

--------------------------------

### plugin.launch(options?)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Launches a Chromium browser with the currently staged fingerprint and proxy settings. Internally delegates to `launchPersistentContext()`. Accepts the same options as Playwright's native `BrowserType.launch()` with the exception of `proxy`, `channel`, and `firefoxUserPrefs` (which throw). Returns `Promise<BrowserContext>`.

```APIDOC
## plugin.launch(options?)

### Description
Launches a Chromium browser with the currently staged fingerprint and proxy settings. Internally delegates to `launchPersistentContext()`.

### Method
`plugin.launch(options?)`

### Parameters
#### Options
- `options` (object) - Optional. Accepts the same options as Playwright's native `BrowserType.launch()` with the exception of `proxy`, `channel`, and `firefoxUserPrefs` (which throw).

### Returns
`Promise<BrowserContext>`

### Request Example
```javascript
const { plugin } = require('playwright-with-fingerprints');

plugin.setServiceKey('');

(async () => {
  const fingerprint = await plugin.fetch({ tags: ['Microsoft Windows', 'Chrome'] });

  const browser = await plugin.useFingerprint(fingerprint).launch({
    headless: false,
    args: ['--mute-audio'],
  });

  const page = await browser.newPage();
  await page.goto('https://httpbin.org/headers', { waitUntil: 'domcontentloaded' });

  const { headers } = JSON.parse(await page.$eval('pre', (el) => el.innerText));
  console.log('User-Agent :', headers['User-Agent']);
  console.log('Accept-Lang:', headers['Accept-Language']);

  await browser.close();
})();
```
```

--------------------------------

### Parallel / multi-browser launches

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Demonstrates how multiple browser instances with different fingerprints can run concurrently. Each `fetch()` and `launch()` call is independent, and the plugin automatically serializes internal engine operations.

```APIDOC
## Parallel / multi-browser launches

### Description
Multiple browser instances with different fingerprints can run concurrently. Each `fetch()` + `launch()` call is independent; the plugin serialises internal engine operations automatically.

### Usage Example
```javascript
const { plugin } = require('playwright-with-fingerprints');

plugin.setServiceKey('');

async function launchSession(index) {
  const fingerprint = await plugin.fetch({ tags: ['Microsoft Windows', 'Chrome'] });
  const browser = await plugin.useFingerprint(fingerprint).launch();

  const page = await browser.newPage();
  await page.goto('https://httpbin.org/headers', { waitUntil: 'domcontentloaded' });

  const { headers } = JSON.parse(await page.$eval('pre', (el) => el.innerText));
  console.log(`Session ${index + 1}:`, {
    userAgent: headers['User-Agent'],
    acceptLanguage: headers['Accept-Language'],
    viewport: await page.evaluate(() => ({ width: innerWidth, height: innerHeight }))
  });

  await browser.close();
}

// Launch 3 independent sessions in parallel
Promise.all([...Array(3).keys()].map(launchSession)).then(() => console.log('All done.'));
```
```

--------------------------------

### UNSUPPORTED_OPTIONS

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

An exported read-only array listing the `launch()` option names that are incompatible with the plugin. Passing any of these will result in an error at call time.

```APIDOC
## UNSUPPORTED_OPTIONS

### Description
An exported read-only array listing the `launch()` option names that are incompatible with the plugin (`['proxy', 'channel', 'firefoxUserPrefs']`). Passing any of these throws at call time.

### Usage Example
```javascript
const { plugin, UNSUPPORTED_OPTIONS } = require('playwright-with-fingerprints');

console.log('Unsupported options:', UNSUPPORTED_OPTIONS);
// Expected: [ 'proxy', 'channel', 'firefoxUserPrefs' ]

// Validate your options object before launching
function safeLaunch(options = {}) {
  const bad = Object.keys(options).filter((k) => UNSUPPORTED_OPTIONS.includes(k));
  if (bad.length) throw new Error(`Unsupported options: ${bad.join(', ')}`);
  return plugin.launch(options);
}

(async () => {
  const browser = await safeLaunch({ headless: true, args: ['--mute-audio'] });
  await browser.close();
})();
```
```

--------------------------------

### Check for Unsupported Launch Options

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

The `UNSUPPORTED_OPTIONS` array lists launch options incompatible with the plugin. Validate your options object against this list before launching to prevent errors.

```javascript
const { plugin, UNSUPPORTED_OPTIONS } = require('playwright-with-fingerprints');

console.log('Unsupported options:', UNSUPPORTED_OPTIONS);
// Expected: [ 'proxy', 'channel', 'firefoxUserPrefs' ]

// Validate your options object before launching
function safeLaunch(options = {}) {
  const bad = Object.keys(options).filter((k) => UNSUPPORTED_OPTIONS.includes(k));
  if (bad.length) throw new Error(`Unsupported options: ${bad.join(', ')}`);
  return plugin.launch(options);
}

(async () => {
  const browser = await safeLaunch({ headless: true, args: ['--mute-audio'] });
  await browser.close();
})();
```

--------------------------------

### Set Browser Version with useBrowserVersion

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Configure the browser version for the next launch using `useBrowserVersion`. Specify a specific version string or 'default' for the latest. An invalid version will cause an error on launch.

```javascript
const { plugin } = require('playwright-with-fingerprints');

// Use a specific version:
plugin.useBrowserVersion('128.0.6613.85');

// Use the latest available version:
plugin.useBrowserVersion('default');
```

--------------------------------

### Apply Fingerprint Before Launch

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Use `useFingerprint` before `launch` to apply a fetched fingerprint. Configure options like `safeElementSize` and `safeBattery`.

```javascript
const { plugin } = require('playwright-with-fingerprints');

// Set the service key for the plugin (you can buy it here https://bablosoft.com/directbuy/FingerprintSwitcher/2).
// Leave an empty string to use the free version.
plugin.setServiceKey('');

const fingerprint = await plugin.fetch({
  tags: ['Microsoft Windows', 'Chrome'],
});

plugin.useFingerprint(fingerprint, {
  // It's disabled by default.
  safeElementSize: true,
  // It's enabled by default.
  safeBattery: false,
});
```

--------------------------------

### plugin.launchPersistentContext(userDataDir, options?)

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Returns a persistent browser context instance. This method launches a browser that uses persistent storage and returns its single context. Closing the context automatically closes the browser.

```APIDOC
## plugin.launchPersistentContext(userDataDir, options?)

### Description
Returns the persistent browser context instance. Launches browser that uses persistent storage located at `userDataDir` and returns the only context. Closing this context will automatically close the browser.

### Method
Not specified (likely a JavaScript function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- `userDataDir` (string)? - Path to a user data directory, which stores browser session data like cookies and local storage.
- `options` (PluginLaunchOptions)? - Set of configurable options to set on the browser.

### Returns
- `Promise<Playwright.BrowserContext>` - Promise which resolves to a context instance.

### Request Example
```javascript
// Example usage (assuming plugin is imported and initialized)
// const context = await plugin.launchPersistentContext('./my-user-data-dir', { viewport: { width: 1920, height: 1080 } });
```

### Response
#### Success Response (200)
- `Playwright.BrowserContext` - A Playwright browser context instance.
```

--------------------------------

### Set Working Folder with plugin.setWorkingFolder

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Configure the directory for engine binaries and temporary profiles using `plugin.setWorkingFolder`. This should be called once at application startup before other plugin operations. Defaults to './data'.

```javascript
const { plugin } = require('playwright-with-fingerprints');

// Store engine outside the project directory
plugin.setWorkingFolder('../shared-engine');

(async () => {
  const fingerprint = await plugin.fetch({ tags: ['Microsoft Windows', 'Chrome'] });
  const browser = await plugin.useFingerprint(fingerprint).launch();
  // Engine binary is installed/read from ../shared-engine
  await browser.close();
})();
```

--------------------------------

### Launch Browser Instance

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Launch a browser instance using the configured fingerprint. The launch parameters are identical to Playwright's launch method.

```js
const browser = await plugin.launch();
```

--------------------------------

### Configure Proxy Settings

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Stages a proxy for the next browser launch, supporting various formats and optional credentials. Can automatically adjust timezone and geolocation to match the proxy's exit node.

```javascript
const { plugin } = require('playwright-with-fingerprints');

(async () => {
  // Many address formats are accepted:
  //   '127.0.0.1:8080'
  //   'https://127.0.0.1:8080'
  //   'socks5://127.0.0.1:9762'
  //   'username:password@127.0.0.1:8080'
  plugin.useProxy('socks5://127.0.0.1:9762', {
    detectExternalIP: false,    // skip IP detection request at startup
    changeTimezone: true,       // sync browser TZ to proxy country
    changeGeolocation: true,    // sync navigator.geolocation to proxy location
  });

  const browser = await plugin.launch();
  const page = await browser.newPage();
  await page.goto('https://canhazip.com/', { waitUntil: 'domcontentloaded' });

  console.log('External IP:', await page.evaluate(() => document.body.innerText.trim()));
  // Expected: the proxy's public IP address

  await browser.close();

  // Reset proxy for subsequent launches
  plugin.useProxy('');
})();
```

--------------------------------

### plugin.fetch(options?)

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Obtains a browser fingerprint using the specified service key and additional options. This method is useful for generating unique browser fingerprints.

```APIDOC
## plugin.fetch(options?)

### Description
Obtain a fingerprint using the specified service key and additional options.

### Method
Not specified (likely a JavaScript function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- `options` (FetchOptions)? - Set of configurable options for getting a browser fingerprint.

### Returns
- `Promise<string>` - Promise which resolves to a fingerprint string.

### Request Example
```javascript
// Example usage (assuming plugin is imported and initialized)
// const fingerprint = await plugin.fetch({ service: 'some-service-key' });
```

### Response
#### Success Response (200)
- `string` - A fingerprint string.
```

--------------------------------

### plugin.useFingerprint(value?, options?)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Stages a fingerprint for the next browser launch. This method must be called before `launch()` or `launchPersistentContext()`. It accepts optional parameters to control API patching.

```APIDOC
## plugin.useFingerprint(value?, options?)

### Description
Stages a fingerprint for the next browser launch. Must be called before `launch()` or `launchPersistentContext()`. Accepts optional fine-grained options to control which APIs are safely patched. Returns `this` for chaining.

### Method
`plugin.useFingerprint(value?: string, options?: { safeElementSize?: boolean, safeBattery?: boolean })`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const { plugin } = require('playwright-with-fingerprints');

plugin.setServiceKey('');

const fingerprint = await plugin.fetch({ tags: ['Microsoft Windows', 'Chrome'] });

// Apply with default options
plugin.useFingerprint(fingerprint);

// Apply with explicit overrides
plugin.useFingerprint(fingerprint, {
  safeElementSize: true,   // default: false — safely replaces element-size APIs
  safeBattery: false,      // default: true  — disable safe BatteryAPI patching
});

const browser = await plugin.launch();
const page = await browser.newPage();
await page.goto('https://browserleaks.com/canvas');
await page.screenshot({ path: 'canvas-check.png', fullPage: true });
await browser.close();
```

### Response
None

### Response Example
None
```

--------------------------------

### plugin.useProxy(value?, options?)

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Sets the proxy settings using the specified proxy as a string and additional options when specified. This enables network traffic routing through a proxy.

```APIDOC
## plugin.useProxy(value?, options?)

### Description
Set the proxy settings using the specified proxy as a string and additional options when specified.

### Method
Not specified (likely a JavaScript function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- `value` (string)? - Proxy value as a string.
- `options` (ProxyOptions)? - Set of configurable options for applying a proxy.

### Returns
- `this` - The same plugin instance with an updated settings (for optional chaining).

### Request Example
```javascript
// Example usage (assuming plugin is imported and initialized)
// plugin.useProxy('http://user:password@proxyserver:port', { username: 'user', password: 'password' });
```

### Response
#### Success Response (200)
- `this` - The plugin instance.
```

--------------------------------

### Spawn Browser and Connect

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Spawns a browser process without connecting and then manually connects to it. This is useful for more advanced scenarios where you need to manage the connection separately.

```javascript
const { chromium } = require('playwright');
const { plugin } = require('playwright-with-fingerprints');

const chrome = await plugin.spawn({ headless: true });

const browser = await chromium.connect(chrome.url);

await browser.close();
await chrome.close();
```

--------------------------------

### plugin.fetch(options?)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Fetches a fingerprint string from the FingerprintSwitcher service. The returned string can be cached and reused. Filter options require a paid service key.

```APIDOC
## plugin.fetch(options?)

### Description
Fetches a fingerprint string from the FingerprintSwitcher service. The returned string can be saved to disk and reused to avoid redundant network requests. All filter options (`minBrowserVersion`, `maxBrowserVersion`, `timeLimit`, custom `tags`) require a paid service key. Returns `Promise<string>`.

### Method
`plugin.fetch(options?: { tags?: string[], minBrowserVersion?: number | 'current', maxBrowserVersion?: number, timeLimit?: string })`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const { readFile, writeFile } = require('fs/promises');
const { plugin } = require('playwright-with-fingerprints');

plugin.setServiceKey('');

// ── Fetch once and cache to disk ──────────────────────────────────────────────
const CACHE = './fingerprint.json';

let fingerprint;
try {
  fingerprint = await readFile(CACHE, 'utf8');
  console.log('Loaded fingerprint from cache.');
} catch {
  fingerprint = await plugin.fetch({
    tags: ['Microsoft Windows', 'Chrome'],
  });
  await writeFile(CACHE, fingerprint);
  console.log('Fetched and cached new fingerprint.');
}

// ── Fetch with version & time filters (paid key required) ────────────────────
const filteredFingerprint = await plugin.fetch({
  tags: ['Microsoft Windows', 'Chrome'],
  minBrowserVersion: 130,
  maxBrowserVersion: 132,
  timeLimit: '15 days',  // only fingerprints collected in the last 15 days
});

// ── Fetch matching the currently installed engine version ─────────────────────
const matchedFingerprint = await plugin.fetch({
  tags: ['Microsoft Windows', 'Chrome'],
  minBrowserVersion: 'current',
});
```

### Response
#### Success Response (200)
- **fingerprint** (string) - The fetched fingerprint string.

### Response Example
```json
{
  "fingerprint": "{\"navigator\":{\"userAgent\":\"...\"}, \"webgl\":{\"renderer\":\"...\"}}"
}
```
```

--------------------------------

### Create Isolated Plugin Instances with createPlugin

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Use `createPlugin` to create independent plugin instances, useful for managing multiple independent configurations or wrappers within the same process. Ensure the provided launcher exposes a `launch` function.

```javascript
const { chromium } = require('playwright');
const { createPlugin } = require('playwright-with-fingerprints');

// Create two independent instances with separate state
const plugin1 = createPlugin(chromium);
const plugin2 = createPlugin({
  launch: (options) => chromium.launch(options),
  launchPersistentContext: (dir, options) => chromium.launchPersistentContext(dir, options),
});

plugin1.setServiceKey('KEY_FOR_ACCOUNT_1');
plugin2.setServiceKey('KEY_FOR_ACCOUNT_2');

(async () => {
  const [ fp1, fp2 ] = await Promise.all([
    plugin1.fetch({ tags: ['Microsoft Windows', 'Chrome'] }),
    plugin2.fetch({ tags: ['Microsoft Windows', 'Chrome'] }),
  ]);

  const [ b1, b2 ] = await Promise.all([
    plugin1.useFingerprint(fp1).launch(),
    plugin2.useFingerprint(fp2).launch(),
  ]);

  const [ p1, p2 ] = await Promise.all([b1.newPage(), b2.newPage()]);
  await Promise.all([p1.goto('https://example.com'), p2.goto('https://example.com')]);

  console.log('Instance 1 UA:', await p1.evaluate(() => navigator.userAgent));
  console.log('Instance 2 UA:', await p2.evaluate(() => navigator.userAgent));
  // Expected: two different user-agent strings from two distinct fingerprints

  await Promise.all([b1.close(), b2.close()]);
})();
```

--------------------------------

### plugin.useProfile(value?, options?)

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Sets the profile settings using the specified profile as a string and additional options when specified. This allows for custom browser profile configurations.

```APIDOC
## plugin.useProfile(value?, options?)

### Description
Set the profile settings using the specified profile as a string and additional options when specified.

### Method
Not specified (likely a JavaScript function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- `value` (string)? - Profile value as a string.
- `options` (ProfileOptions)? - Set of configurable options for applying a profile.

### Returns
- `this` - The same plugin instance with an updated settings (for optional chaining).

### Request Example
```javascript
// Example usage (assuming plugin is imported and initialized)
// plugin.useProfile('my-custom-profile', { delete: true });
```

### Response
#### Success Response (200)
- `this` - The plugin instance.
```

--------------------------------

### Fetch and Apply Fingerprint

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Set the service key (empty string for free version), fetch a fingerprint based on tags, and apply it for browser instance. Fetching may be slow on first run due to browser download.

```js
// Set the service key for the plugin (you can buy it here https://bablosoft.com/directbuy/FingerprintSwitcher/2).
// Leave an empty string to use the free version.
plugin.setServiceKey('');

const fingerprint = await plugin.fetch({
  tags: ['Microsoft Windows', 'Chrome'],
});

plugin.useFingerprint(fingerprint);
```

--------------------------------

### Fetch and Use Specific Browser Version

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Retrieve a list of available browser versions using `plugin.versions('extended')` and then set a specific version using `plugin.useBrowserVersion`. The list is sorted in descending order.

```javascript
const { plugin } = require('playwright-with-fingerprints');

// The list of versions is always sorted in descending order:
await plugin.versions('extended').then((versions) => {
  // The latest available browser version will be used:
  plugin.useBrowserVersion(versions[0]['browser_version']);
});
```

--------------------------------

### Set Fingerprint Service Key and Proxy via Environment Variables

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/examples/README.md

Configure the fingerprint service key and proxy settings using environment variables. These can be set directly or via a .env file.

```shell
FINGERPRINT_KEY="SERVICE_KEY"
FINGERPRINT_PROXY="socks5://127.0.0.1:9762"
```

--------------------------------

### Select Browser Version with plugin.useBrowserVersion

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Use `plugin.useBrowserVersion` to select a specific Chromium build for the next launch. 'default' selects the latest available build. This setting affects only the current plugin instance.

```javascript
const { plugin } = require('playwright-with-fingerprints');

(async () => {
  // List all available builds (descending order)
  const versions = await plugin.versions('extended');
  console.log('Available versions:', versions.map((v) => v.browser_version));

  // Pin to the latest build explicitly
  plugin.useBrowserVersion(versions[0].browser_version);

  // Or just use the default (same effect)
  plugin.useBrowserVersion('default');

  const browser = await plugin.launch();
  const page = await browser.newPage();
  await page.goto('about:blank');
  console.log('Browser version:', await browser.version?.() ?? 'n/a');
  await browser.close();
})();
```

--------------------------------

### plugin.versions(format?)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Retrieves an array of available browser version strings. The 'extended' format returns objects with additional metadata, while the default format returns simple version strings. Versions are sorted in descending order.

```APIDOC
## plugin.versions(format?)

### Description
Returns an array of browser version strings (`format` omitted or `'simple'`) or an array of objects with extended metadata (`format = 'extended'`). Versions are always sorted descending. Returns `Promise<string[] | Version[]>`. 

### Method
```javascript
plugin.versions(format?: 'simple' | 'extended'): Promise<string[] | Version[]>
```

### Parameters
#### Query Parameters
- **format** (string) - Optional - Specifies the output format. Can be `'simple'` (default) or `'extended'`.
```

--------------------------------

### Launch Browser with Persistent Context

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Launches a browser with a persistent profile stored at a specified directory. This allows session data like cookies and localStorage to persist across runs.

```javascript
const path = require('path');
const { plugin } = require('playwright-with-fingerprints');

(async () => {
  const profileDir = path.resolve('./my-profile');

  // Browser session (cookies, localStorage, etc.) survives across runs
  const context = await plugin.launchPersistentContext(profileDir, {
    headless: false,
  });

  const page = await context.newPage();
  await page.goto('chrome://version');

  const el = await page.waitForSelector('#profile_path');
  console.log('Profile path:', await el.evaluate((e) => e.textContent));
  // Expected: .../my-profile/Default

  await context.close(); // also closes the browser
})();
```

--------------------------------

### plugin.setWorkingFolder(folder)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Sets the directory where the engine binary and temporary profiles are stored. The default directory is './data'. This function should be called once at the application startup before any other plugin operations.

```APIDOC
## plugin.setWorkingFolder(folder)

### Description
Sets the directory where the engine binary and temporary profiles are stored. Defaults to `./data`. Call this once at application startup before any other plugin operations.

### Method
```javascript
plugin.setWorkingFolder(folder: string)
```

### Parameters
#### Path Parameters
- **folder** (string) - Required - The path to the directory for storing engine data.
```

--------------------------------

### plugin.versions

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Retrieves a list of all available browser versions supported by the plugin. The format of the returned data can be specified.

```APIDOC
## plugin.versions(format?)

### Description
Get a list of all available browser versions.

### Parameters
#### Query Parameters
- `format` (string)? - Optional - The output format of the returned result.

### Returns
- `Promise<Version[]|string[]>` - The list of objects with detailed version information, or a list of strings.
```

--------------------------------

### plugin.useBrowserVersion(version)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Selects a specific Chromium build to use for the next browser launch. The 'default' option picks the latest available build. This setting affects only the current plugin instance.

```APIDOC
## plugin.useBrowserVersion(version)

### Description
Selects which Chromium build (shipped with the engine) to use for the next launch. `'default'` always picks the latest available build. Throws at launch time if the version string is not present in the engine. Affects only the specific plugin instance, not the shared singleton. Returns `this`.

### Method
```javascript
plugin.useBrowserVersion(version: string)
```

### Parameters
#### Path Parameters
- **version** (string) - Required - The browser version string or 'default' to use the latest available build.
```

--------------------------------

### plugin.setServiceKey(key)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Sets the global FingerprintSwitcher service key. This is required for fetching fingerprints and launching browsers. An empty string uses the free tier with limitations, while a paid key unlocks full features.

```APIDOC
## plugin.setServiceKey(key)

### Description
Sets the global FingerprintSwitcher service key used by all subsequent `fetch()` and browser-launch calls. Pass an empty string to use the free tier (limited to `['Microsoft Windows', 'Chrome']` tags, no advanced filters, no PerfectCanvas). A paid key unlocks custom tags, version filters, time filters, and higher request rates.

### Method
`plugin.setServiceKey(key: string)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const { plugin } = require('playwright-with-fingerprints');

// Free tier — limited tags and no advanced filters
plugin.setServiceKey('');

// Paid key — full feature access
plugin.setServiceKey('YOUR_SERVICE_KEY_HERE');
```

### Response
None

### Response Example
None
```

--------------------------------

### Set FingerprintSwitcher Service Key

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Configure the global FingerprintSwitcher service key. Use an empty string for the free tier or your paid key for full features.

```javascript
const { plugin } = require('playwright-with-fingerprints');

// Free tier — limited tags and no advanced filters
plugin.setServiceKey('');

// Paid key — full feature access
plugin.setServiceKey('YOUR_SERVICE_KEY_HERE');
```

--------------------------------

### Create Custom Plugin Instance

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Create a standalone plugin instance using `createPlugin` when needing multiple instances with different settings or if using a wrapper library. This requires providing a Playwright compatible launcher object.

```javascript
const { chromium } = require('playwright');
const { createPlugin } = require('playwright-with-fingerprints');

const plugin1 = createPlugin({
  // This method is required, must return the same
  // type and take the same parameters as the built-in.
  launch: (options) => chromium.launch(options),
});

// The default instance is created in the same way.
const plugin2 = createPlugin(chromium);
```

--------------------------------

### Fetch Fingerprints with Filters

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Use the `fetch` method to retrieve fingerprints. Filters like `minBrowserVersion`, `maxBrowserVersion`, and `timeLimit` can be applied. Premium keys are often required for advanced filters and tags.

```javascript
const { plugin } = require('playwright-with-fingerprints');

// Set the service key for the plugin (you can buy it here https://bablosoft.com/directbuy/FingerprintSwitcher/2).
// Leave an empty string to use the free version.
plugin.setServiceKey('');

const fingerprint = await plugin.fetch({
  tags: ['Microsoft Windows', 'Chrome'],
  // Fetch fingerprints only with a browser version higher than 130:
  minBrowserVersion: 130,
  // Fetch fingerprints only with a browser version lower than 132:
  maxBrowserVersion: 132,
  // Fetch fingerprints only collected in the last 15 days:
  timeLimit: '15 days',
});
```

--------------------------------

### plugin.useProfile(value?, options?)

Source: https://context7.com/bablosoft/playwright-with-fingerprints/llms.txt

Stages a browser profile path. By default the plugin stores and loads fingerprint and proxy data from the profile folder between sessions. This behaviour can be suppressed via the `loadFingerprint` / `loadProxy` options. Returns `this` for chaining.

```APIDOC
## plugin.useProfile(value?, options?)

### Description
Stages a browser profile path. By default the plugin stores and loads fingerprint and proxy data from the profile folder between sessions. This behaviour can be suppressed via the `loadFingerprint` / `loadProxy` options.

### Method
`plugin.useProfile(value?, options?)

### Parameters
#### Value
- `value` (string) - Optional. The path to the browser profile directory.

#### Options
- `options` (object) - Optional. Configuration options for profile usage.
  - `loadFingerprint` (boolean) - Whether to load fingerprint data from the profile. Defaults to true.
  - `loadProxy` (boolean) - Whether to load proxy data from the profile. Defaults to true.

### Returns
`this` for chaining.

### Request Example
```javascript
const path = require('path');
const { plugin } = require('playwright-with-fingerprints');

plugin.setServiceKey('');

(async () => {
  const fingerprint = await plugin.fetch({ tags: ['Microsoft Windows', 'Chrome'] });

  plugin
    .useFingerprint(fingerprint)
    .useProfile(path.resolve('./session-profile'), {
      loadFingerprint: false, // always use the freshly fetched fingerprint
      loadProxy: false,       // ignore any proxy stored in the profile
    });

  const browser = await plugin.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');

  console.log('Title:', await page.title());

  await browser.close();
})();
```
```

--------------------------------

### Save and Load Fingerprints

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Persist fetched fingerprints to a file using `writeFile` and load them on subsequent runs with `readFile` and `useFingerprint` to speed up browser launches.

```javascript
const { readFile, writeFile } = require('fs/promises');
const { plugin } = require('playwright-with-fingerprints');

// Set the service key for the plugin (you can buy it here https://bablosoft.com/directbuy/FingerprintSwitcher/2).
// Leave an empty string to use the free version.
plugin.setServiceKey('');

// Save the fingerprint to a file:
const fingerprint = await plugin.fetch({
  tags: ['Microsoft Windows', 'Chrome'],
});
await writeFile('fingerprint.json', fingerprint);

// Load fingerprint from file at next run:
plugin.useFingerprint(await readFile('fingerprint.json', 'utf8'));
```

--------------------------------

### Set Plugin Working Folder

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Configures the working directory for the plugin engine. Accepts a string representing the folder path.

```javascript
plugin.setWorkingFolder("path/to/folder");
```

--------------------------------

### Free Version Fingerprint Fetch

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Demonstrates fetching fingerprints using the free version of the service. Only default tags like 'Microsoft Windows' and 'Chrome' are supported, and certain filters are unavailable.

```javascript
// Set the service key for the plugin (you can buy it here https://bablosoft.com/directbuy/FingerprintSwitcher/2).
// Leave an empty string to use the free version.
plugin.setServiceKey('');

const fingerprint = await plugin.fetch({
  // You can only use these tags with the free version:
  tags: ['Microsoft Windows', 'Chrome'],
  // You also cannot use such filters in the free version:

```

--------------------------------

### Configure Plugin Service Key

Source: https://github.com/bablosoft/playwright-with-fingerprints/blob/master/README.md

Sets the service key globally for all plugin methods that require it. An empty string uses the free version.

```javascript
// Set the fingerprint service key for all plugin methods that require it.
plugin.setServiceKey('SERVICE_KEY');
```