Detect bots on the web

The bot detection plugin uses FingerprintJS BotD to detect automated browsers such as Selenium, PhantomJS, or headless Chrome. It attaches a client_side_bot_detection entity to every event.

This is useful when you want to identify bot traffic as early as possible, before events reach your pipeline. For a broader approach that also incorporates server-side indicators, see the bot detection enrichment.

note

The plugin is available since version 4.7 of the tracker.

The bot detection entity is automatically tracked once configured.

Install the plugin

JavaScript (tag)

Tracker Distribution	Included
sp.js	❌
sp.lite.js	❌

Download:

Download from GitHub Releases (Recommended)	Github Releases (plugins.umd.zip)
Available on jsDelivr	jsDelivr
Available on unpkg	unpkg

note

The links to the CDNs above are pinned to a specific version at the time of writing. Check the plugin's GitHub releases for newer versions, and update the pinned version when you upgrade.

javascript

window.snowplow('addPlugin',
  "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-bot-detection@4.10.2/dist/index.umd.min.js",
  ["snowplowBotDetection", "BotDetectionPlugin"]
);

Browser (npm)

• npm install @snowplow/browser-plugin-bot-detection
• yarn add @snowplow/browser-plugin-bot-detection
• pnpm add @snowplow/browser-plugin-bot-detection

javascript

import { newTracker } from '@snowplow/browser-tracker';
import { BotDetectionPlugin } from '@snowplow/browser-plugin-bot-detection';

newTracker('sp1', '{{collector_url}}', {
   appId: 'my-app-id',
   plugins: [ BotDetectionPlugin() ],
});

Output

The plugin attaches a client_side_bot_detection entity to every event.

client_side_bot_detection

Schema

Schema for bot detection entity, powered by the BotD library (https://github.com/fingerprintjs/BotD)

Schema URIiglu:com.snowplowanalytics.snowplow/client_side_bot_detection/jsonschema/1-0-0

Example data

json

{
  "bot": true,
  "kind": "headless_chrome"
}

Properties and schema

Table

Property	Description
bot boolean	Required. Whether the current browser is identified as a bot
kind string	Optional. The type of bot detected. Populated when bot is true, null or omitted otherwise. See https://github.com/fingerprintjs/BotD/blob/main/src/types.ts Must be one of: awesomium, cef, cefsharp, coachjs, electron, fminer, geb, nightmarejs, phantomas, phantomjs, rhino, selenium, sequentum, slimerjs, webdriverio, webdriver, headless_chrome, unknown,

Complete JSON schema

json

{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Schema for bot detection entity, powered by the BotD library (https://github.com/fingerprintjs/BotD)",
  "self": {
    "vendor": "com.snowplowanalytics.snowplow",
    "name": "client_side_bot_detection",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "type": "object",
  "properties": {
    "bot": {
      "description": "Whether the current browser is identified as a bot",
      "type": "boolean"
    },
    "kind": {
      "description": "The type of bot detected. Populated when bot is true, null or omitted otherwise. See https://github.com/fingerprintjs/BotD/blob/main/src/types.ts",
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "awesomium",
        "cef",
        "cefsharp",
        "coachjs",
        "electron",
        "fminer",
        "geb",
        "nightmarejs",
        "phantomas",
        "phantomjs",
        "rhino",
        "selenium",
        "sequentum",
        "slimerjs",
        "webdriverio",
        "webdriver",
        "headless_chrome",
        "unknown",
        null
      ]
    }
  },
  "required": [
    "bot"
  ],
  "additionalProperties": false
}

Asynchronous detection

Bot detection runs asynchronously. Events tracked before detection completes won't have this entity attached. In most cases, detection finishes within milliseconds, but if you need the entity on the very first event, consider deferring your initial tracking calls until the tracker is fully initialized.

The bot detection enrichment can consolidate this client-side indicator with server-side indicators from YAUAA, IAB, and ASN lookups into a single bot_detection entity.