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 (latest)
Available on unpkg	unpkg (latest)

note

The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production.

javascript

window.snowplow('addPlugin',
  "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-bot-detection@latest/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

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,

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.