fix(browser-plugin-bot-detection): exclude BotD's spurious plugins-length detector

BotD's `detectPluginsLengthInconsistency` reports any non-Android Chromium
browser with `navigator.plugins.length === 0` as headless Chrome. Chrome's
`--headless=new` mode now reports plugins like a headed browser, while
privacy-focused browsers legitimately report none, so the check only yields
false positives.

Rather than patch the dependency, compose BotD's exported `collect`/`detect`
with our own detector set. A pnpm patch would only reach the UMD build, since
the ESM build keeps `@fingerprintjs/botd` external and npm consumers would
resolve their own unpatched copy.

Mirrors fingerprintjs/BotD#194, which is approved
upstream but unmerged and so absent from botd 2.0.0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: stanch

common/changes/@snowplow/browser-plugin-bot-detection/bot-d-patch_2026-08-14-11-03.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Exclude BotD's spurious plugins-length headless Chrome detector",
+      "type": "none",
+      "packageName": "@snowplow/browser-plugin-bot-detection"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-bot-detection",
+  "email": "nick.stanch@snowplowanalytics.com"
+}

plugins/browser-plugin-bot-detection/src/detectors.ts

@@ -0,0 +1,13 @@
+import { detectors } from '@fingerprintjs/botd';
+
+type Detector = (typeof detectors)[keyof typeof detectors];
+
+/**
+ * BotD's default detectors, minus `detectPluginsLengthInconsistency`.
+ *
+ * This detector is considered spurious, see https://github.com/fingerprintjs/BotD/pull/194.
+ *
+ * TODO: remove once the PR is merged upstream.
+ */
+export const activeDetectors: Record<string, Detector> = { ...detectors };
+delete activeDetectors.detectPluginsLengthInconsistency;

plugins/browser-plugin-bot-detection/src/index.ts

@@ -1,7 +1,8 @@
 import { BrowserPlugin } from '@snowplow/browser-tracker-core';
 import { LOG } from '@snowplow/tracker-core';
-import { load } from '@fingerprintjs/botd';
+import { collect, detect, sources } from '@fingerprintjs/botd';
 import { CLIENT_SIDE_BOT_DETECTION_SCHEMA } from './schemata';
+import { activeDetectors } from './detectors';
 import { BotDetectionContextData } from './types';
 
 export { BotDetectionContextData, BotKind } from './types';
@@ -14,12 +15,14 @@ export function BotDetectionPlugin(): BrowserPlugin {
     activateBrowserPlugin: () => {
       if (!detectionStarted) {
         detectionStarted = true;
-        load()
-          .then((detector) => detector.detect())
+        // Equivalent to BotD's `load().then((d) => d.detect())`,
+        // but with our own detector set (see `./detectors`)
+        collect(sources)
+          .then((components) => detect(components, activeDetectors)[1])
           .then((result) => {
             contextData = result.bot ? { bot: true, kind: result.botKind } : { bot: false, kind: null };
           })
-          .catch((err) => LOG.error('BotDetectionPlugin: BotD load/detect failed', err));
+          .catch((err) => LOG.error('BotDetectionPlugin: BotD collect/detect failed', err));
       }
     },
     contexts: () => {

plugins/browser-plugin-bot-detection/test/bot-detection.test.ts

@@ -5,31 +5,31 @@ import { setImmediate } from 'timers';
 const flushPromises = () => new Promise(setImmediate);
 
 let mockDetectResult: any = { bot: false };
-let mockLoadReject: Error | null = null;
-let mockDetectReject: Error | null = null;
+let mockCollectReject: Error | null = null;
+let mockDetectThrow: Error | null = null;
 
 jest.mock('@fingerprintjs/botd', () => ({
-  load: () => {
-    if (mockLoadReject) {
-      return Promise.reject(mockLoadReject);
+  ...jest.requireActual('@fingerprintjs/botd'),
+  collect: () => {
+    if (mockCollectReject) {
+      return Promise.reject(mockCollectReject);
     }
-    return Promise.resolve({
-      detect: () => {
-        if (mockDetectReject) {
-          return Promise.reject(mockDetectReject);
-        }
-        return Promise.resolve(mockDetectResult);
-      },
-    });
+    return Promise.resolve({});
+  },
+  detect: () => {
+    if (mockDetectThrow) {
+      throw mockDetectThrow;
+    }
+    return [{}, mockDetectResult];
   },
 }));
 
 describe('BotDetectionPlugin', () => {
   beforeEach(() => {
     jest.resetModules();
     mockDetectResult = { bot: false };
-    mockLoadReject = null;
-    mockDetectReject = null;
+    mockCollectReject = null;
+    mockDetectThrow = null;
   });
 
   it('attaches bot context when a bot is detected', async () => {
@@ -107,8 +107,8 @@ describe('BotDetectionPlugin', () => {
     core.track(buildLinkClick({ targetUrl: 'https://example.com' }));
   });
 
-  it('returns empty contexts when load() fails', async () => {
-    mockLoadReject = new Error('load failed');
+  it('returns empty contexts when collect() fails', async () => {
+    mockCollectReject = new Error('collect failed');
 
     const { BotDetectionPlugin } = require('../src');
     const plugin = BotDetectionPlugin();
@@ -128,7 +128,7 @@ describe('BotDetectionPlugin', () => {
   });
 
   it('returns empty contexts when detect() fails', async () => {
-    mockDetectReject = new Error('detect failed');
+    mockDetectThrow = new Error('detect failed');
 
     const { BotDetectionPlugin } = require('../src');
     const plugin = BotDetectionPlugin();