playwright-with-fingerprints

The playwright-with-fingerprints plugin uses the FingerprintSwitcher service to retrieve fingerprints collected from real devices. These fingerprints are applied to the browser using custom configuration files and a custom-patched browser.

Key Architectural Details:

• Custom Browser: To ensure correct fingerprint substitution, the plugin uses a custom-patched Chrome browser. This browser is downloaded and installed automatically the first time API methods are called.
• Engine Limitation: You cannot use standard engines or other browsers (like Chromium or Firefox). The plugin is locked to the bundled Chrome executable.
• OS Requirement: This package only works on Windows. It relies on Windows-only dependencies and will error on other platforms.
• Fingerprint Source: Fingerprints are downloaded from a service rather than being generated locally, which improves anonymity and property substitution quality.

To migrate an existing Playwright project to use fingerprints, perform the following modifications:

1. Change the import: Replace require('playwright') or require('playwright-core') with const { plugin } = require('playwright-with-fingerprints');.
2. Configure the service: Call plugin.setServiceKey('') to set your API key.
3. Fetch and apply identity: Before launching the browser, call await plugin.fetch({ tags: [...] }) to get a fingerprint and then call plugin.useFingerprint(fingerprint).
4. Update the launch call: Replace your existing browser launch call (e.g., await chromium.launch()) with await plugin.launch().

The rest of your automation logic (creating pages, navigating, interacting with elements) remains unchanged as plugin.launch() returns a standard Playwright Browser object.

/* Before: Standard Playwright */
const { chromium } = require('playwright');
const browser = await chromium.launch();

/* After: With Fingerprints */
const { plugin } = require('playwright-with-fingerprints');
plugin.setServiceKey('');

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

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

To obtain a fingerprint, use the fetch method. This requires a service key (set via setServiceKey).

Free Version Limitations:

• You can only use default tags.
• You cannot use certain filters like minBrowserVersion or maxBrowserVersion.
• PerfectCanvas technology is unavailable.
• Request limits apply.

Fetch Options:

• tags: Array of strings (e.g., ['Microsoft Windows', 'Chrome']). Custom tags require a premium key.
• minBrowserVersion: Minimum version number.
• maxBrowserVersion: Maximum version number.
• timeLimit: Filter by how recently the fingerprint was collected (e.g., '15 days').
• current: A special value to filter fingerprints by the version currently installed in the plugin.

Fingerprint Reuse: You can save a fingerprint to a file or database and reload it later using useFingerprint to avoid repeated API calls.

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

plugin.setServiceKey('');

// 1. Fetch and Save
const fingerprint = await plugin.fetch({
  tags: ['Microsoft Windows', 'Chrome'],
  minBrowserVersion: 130,
  maxBrowserVersion: 132,
  timeLimit: '15 days',
});
await writeFile('fingerprint.json', fingerprint);

// 2. Load and Use
const savedFingerprint = await readFile('fingerprint.json', 'utf8');
plugin.useFingerprint(savedFingerprint);

await plugin.launch();

To start a new project using fingerprints, follow these steps:

1. Import plugin from playwright-with-fingerprints.
2. Set your service key using plugin.setServiceKey('') (use an empty string for the free version).
3. Fetch a fingerprint from the server using plugin.fetch({ tags: [...] }).
4. Apply the fingerprint using plugin.useFingerprint(fingerprint).
5. Launch the browser using plugin.launch().

Note: The plugin.launch() method accepts the same parameters as the standard Playwright browserType.launch() method and returns a standard Playwright Browser instance.

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

// Set the service key (empty string for free version)
plugin.setServiceKey('');

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

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

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

  // 4. Use standard Playwright API
  const page = await browser.newPage();
  await page.goto('https://example.com');

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

You can configure global settings for the plugin instance. These settings affect all plugin methods and all instances of the plugin.

Available configuration methods:

• setServiceKey(key): Sets the fingerprint service key. An empty string (default) uses the free version of the service.
• setWorkingFolder(path): Sets the directory where the plugin engine is installed. Defaults to ./data.
• setRequestTimeout(ms): Sets the timeout for requests to the engine (e.g., fetching fingerprints). Defaults to 300000 ms.
• setEngineTimeout(ms): Sets the timeout for installing or downloading the engine.

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

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

// Set the timeout used when fetching fingerprints and so on:
plugin.setRequestTimeout(5 * 60000);

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