Release 4.7.0

common/changes/@snowplow/browser-plugin-bot-detection/bot-detection-plugin_2026-03-17-17-11.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Add browser-plugin-bot-detection plugin wrapping FingerprintJS BotD for client-side bot detection",
+      "type": "minor",
+      "packageName": "@snowplow/browser-plugin-bot-detection"
+    }
+  ],
+  "packageName": "@snowplow/browser-plugin-bot-detection",
+  "email": "nick.stanch@snowplowanalytics.com"
+}

common/config/rush/browser-approved-packages.json

@@ -6,6 +6,10 @@
       "name": "@ampproject/rollup-plugin-closure-compiler",
       "allowedCategories": [ "libraries", "plugins", "trackers" ]
     },
+    {
+      "name": "@fingerprintjs/botd",
+      "allowedCategories": [ "plugins" ]
+    },
     {
       "name": "@react-native-async-storage/async-storage",
       "allowedCategories": [ "trackers" ]
@@ -42,6 +46,10 @@
       "name": "@snowplow/browser-plugin-ad-tracking",
       "allowedCategories": [ "trackers" ]
     },
+    {
+      "name": "@snowplow/browser-plugin-bot-detection",
+      "allowedCategories": [ "trackers" ]
+    },
     {
       "name": "@snowplow/browser-plugin-browser-features",
       "allowedCategories": [ "trackers" ]

common/config/rush/repo-state.json

@@ -1,5 +1,5 @@
 // DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.
 {
-  "pnpmShrinkwrapHash": "1bbfee8474092dd7a04f769c89f237e4c74bfbb5",
+  "pnpmShrinkwrapHash": "d3b2991182c4ca5879833e9c94d65eb10cb6c7f1",
   "preferredVersionsHash": "bf21a9e8fbc5a3846fb05b4fa0859e0917b2202f"
 }

common/config/rush/version-policies.json

@@ -42,6 +42,6 @@
      *
      * Valid values are: "prerelease", "release", "minor", "patch", "major"
      */
-    "nextBump": "patch"
+    "nextBump": "minor"
   }
 ]

plugins/browser-plugin-bot-detection/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022 Snowplow Analytics Ltd, 2010 Anthon Pang
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plugins/browser-plugin-bot-detection/README.md

@@ -0,0 +1,59 @@
+# Snowplow Bot Detection
+
+[![npm version][npm-image]][npm-url]
+[![License][license-image]](LICENSE)
+
+Browser Plugin to be used with `@snowplow/browser-tracker`.
+
+Detects bots client-side using [FingerprintJS BotD](https://github.com/fingerprintjs/BotD) and attaches the result as a `client_side_bot_detection` context entity to all tracked events.
+
+## Maintainer quick start
+
+Part of the Snowplow JavaScript Tracker monorepo.
+Build with [Node.js](https://nodejs.org/en/) (18 - 20) and [Rush](https://rushjs.io/).
+
+### Setup repository
+
+```bash
+npm install -g @microsoft/rush
+git clone https://github.com/snowplow/snowplow-javascript-tracker.git
+rush update
+```
+
+## Package Installation
+
+With npm:
+
+```bash
+npm install @snowplow/browser-plugin-bot-detection
+```
+
+## Usage
+
+Initialize your tracker with the BotDetectionPlugin:
+
+```js
+import { newTracker } from '@snowplow/browser-tracker';
+import { BotDetectionPlugin } from '@snowplow/browser-plugin-bot-detection';
+
+newTracker('sp1', '{{collector}}', { plugins: [ BotDetectionPlugin() ] });
+```
+
+Once detection completes, a `client_side_bot_detection` context entity will be attached to all subsequent events with the following fields:
+
+- `bot` (boolean): Whether a bot was detected.
+- `kind` (string | null): The type of bot detected (e.g. `"selenium"`, `"phantomjs"`), or `null` if no bot was found.
+
+## Copyright and license
+
+Licensed and distributed under the [BSD 3-Clause License](LICENSE) ([An OSI Approved License][osi]).
+
+Copyright (c) 2022 Snowplow Analytics Ltd, 2010 Anthon Pang.
+
+All rights reserved.
+
+[npm-url]: https://www.npmjs.com/package/@snowplow/browser-plugin-bot-detection
+[npm-image]: https://img.shields.io/npm/v/@snowplow/browser-plugin-bot-detection
+[docs]: https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-tracker/
+[osi]: https://opensource.org/licenses/BSD-3-Clause
+[license-image]: https://img.shields.io/npm/l/@snowplow/browser-plugin-bot-detection

plugins/browser-plugin-bot-detection/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  preset: 'ts-jest',
+  reporters: ['jest-standard-reporter'],
+  setupFilesAfterEnv: ['../../setupTestGlobals.ts'],
+  testEnvironment: 'jest-environment-jsdom-global',
+};

plugins/browser-plugin-bot-detection/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@snowplow/browser-plugin-bot-detection",
+  "version": "4.6.9",
+  "description": "Detects bots client-side using FingerprintJS BotD and attaches the result as a context entity.",
+  "homepage": "https://github.com/snowplow/snowplow-javascript-tracker",
+  "bugs": "https://github.com/snowplow/snowplow-javascript-tracker/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snowplow/snowplow-javascript-tracker.git"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Snowplow Analytics Ltd (https://snowplow.io/)",
+  "sideEffects": false,
+  "main": "./dist/index.umd.js",
+  "module": "./dist/index.module.js",
+  "types": "./dist/index.module.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c --silent --failAfterWarnings",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@fingerprintjs/botd": "2.0.0",
+    "@snowplow/browser-tracker-core": "workspace:*",
+    "@snowplow/tracker-core": "workspace:*",
+    "tslib": "^2.3.1"
+  },
+  "devDependencies": {
+    "@ampproject/rollup-plugin-closure-compiler": "~0.27.0",
+    "@rollup/plugin-commonjs": "~21.0.2",
+    "@rollup/plugin-node-resolve": "~13.1.3",
+    "@types/jest": "~28.1.1",
+    "@types/jsdom": "~16.2.14",
+    "@typescript-eslint/eslint-plugin": "~5.15.0",
+    "@typescript-eslint/parser": "~5.15.0",
+    "eslint": "~8.11.0",
+    "jest": "~28.1.3",
+    "jest-environment-jsdom": "~28.1.3",
+    "jest-environment-jsdom-global": "~4.0.0",
+    "jest-standard-reporter": "~2.0.0",
+    "rollup": "~2.70.1",
+    "rollup-plugin-cleanup": "~3.2.1",
+    "rollup-plugin-license": "~2.6.1",
+    "rollup-plugin-terser": "~7.0.2",
+    "rollup-plugin-ts": "~2.0.5",
+    "ts-jest": "~28.0.8",
+    "typescript": "~4.6.2"
+  },
+  "peerDependencies": {
+    "@snowplow/browser-tracker": "~4.6.9"
+  }
+}

plugins/browser-plugin-bot-detection/rollup.config.js

@@ -0,0 +1,37 @@
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import ts from 'rollup-plugin-ts'; // Preferred over @rollup/plugin-typescript as it bundles .d.ts files
+import { banner } from '../../banner';
+import compiler from '@ampproject/rollup-plugin-closure-compiler';
+import { terser } from 'rollup-plugin-terser';
+import cleanup from 'rollup-plugin-cleanup';
+import pkg from './package.json';
+import { builtinModules } from 'module';
+
+const umdPlugins = [nodeResolve({ browser: true }), commonjs(), ts()];
+const umdName = 'snowplowBotDetection';
+
+export default [
+  // CommonJS (for Node) and ES module (for bundlers) build.
+  {
+    input: './src/index.ts',
+    plugins: [...umdPlugins, banner()],
+    treeshake: { moduleSideEffects: ['sha1'] },
+    output: [{ file: pkg.main, format: 'umd', sourcemap: true, name: umdName }],
+  },
+  {
+    input: './src/index.ts',
+    plugins: [...umdPlugins, compiler(), terser(), cleanup({ comments: 'none' }), banner()],
+    treeshake: { moduleSideEffects: ['sha1'] },
+    output: [{ file: pkg.main.replace('.js', '.min.js'), format: 'umd', sourcemap: true, name: umdName }],
+  },
+  {
+    input: './src/index.ts',
+    external: [...builtinModules, ...Object.keys(pkg.dependencies), ...Object.keys(pkg.devDependencies)],
+    plugins: [
+      ts(), // so Rollup can convert TypeScript to JavaScript
+      banner(),
+    ],
+    output: [{ file: pkg.module, format: 'es', sourcemap: true }],
+  },
+];

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

@@ -0,0 +1,32 @@
+import { BrowserPlugin } from '@snowplow/browser-tracker-core';
+import { LOG } from '@snowplow/tracker-core';
+import { load } from '@fingerprintjs/botd';
+import { CLIENT_SIDE_BOT_DETECTION_SCHEMA } from './schemata';
+import { BotDetectionContextData } from './types';
+
+export { BotDetectionContextData, BotKind } from './types';
+
+let contextData: BotDetectionContextData | undefined;
+let detectionStarted = false;
+
+export function BotDetectionPlugin(): BrowserPlugin {
+  return {
+    activateBrowserPlugin: () => {
+      if (!detectionStarted) {
+        detectionStarted = true;
+        load()
+          .then((detector) => detector.detect())
+          .then((result) => {
+            contextData = result.bot ? { bot: true, kind: result.botKind } : { bot: false, kind: null };
+          })
+          .catch((err) => LOG.error('BotDetectionPlugin: BotD load/detect failed', err));
+      }
+    },
+    contexts: () => {
+      if (contextData) {
+        return [{ schema: CLIENT_SIDE_BOT_DETECTION_SCHEMA, data: contextData }];
+      }
+      return [];
+    },
+  };
+}

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

@@ -0,0 +1,2 @@
+export const CLIENT_SIDE_BOT_DETECTION_SCHEMA =
+  'iglu:com.snowplowanalytics.snowplow/client_side_bot_detection/jsonschema/1-0-0';