api.md

BotD API Reference

Migration guide from 0.1

Installation

Browser ECMAScript module

<script>
    // Initialize the agent at application startup.
    const botdPromise = import('https://openfpcdn.io/botd/v1').then((Botd) => Botd.load())
    // Get detection results when you need them.
    botdPromise
        .then((botd) => botd.detect())
        .then((result) => console.log(result))
        .catch((error) => console.error(error))
</script>

Run this code

For browsers that don't support import see the browser support guide.

Webpack/Rollup/NPM/Yarn

# Install the package first:
npm i @fingerprintjs/botd
# or
yarn add @fingerprintjs/botd

import { load } from '@fingerprintjs/botd'

// Initialize an agent at application startup.
load()
    .then((botd) => botd.detect())
    .then((result) => console.log(result))
    .catch((error) => console.error(error))

Run this code

When you run BotD installed with NPM or Yarn, the library will send AJAX requests to FingerprintJS servers to collect usage statistics. When the load function runs, there is a 0.1% chance of sending a request. The requests are sent at most once a week from one browser instance (unless the browser cache was cleared). A request includes the following information:

• The library version
• The HTTP headers that the client sends, including the origin and the referrer of the page where the library runs
• The IP of the client

You can turn off these requests by using the monitoring option:

const botdPromise = BotD.load({
+ monitoring: false
})

💡 Scripts downloaded from our CDN (https://openfpcdn.io) have monitoring disabled by default.

CommonJS syntax:

const { load } = require('@fingerprintjs/botd')

// Initialize an agent at application startup.
load()
    .then((botd) => botd.detect())
    .then((result) => console.log(result))
    .catch((error) => console.error(error))

API

BotD.load({ monitoring?: boolean }): Promise<BotDetector>

Builds an instance of BotDetector. We recommend calling it as early as possible, ideally during application startup. It returns a promise which you can chain on to call BotDetector methods later.

It's needed only once per page/app. Then you can get detection results when you need them.

botDetector.collect(): Promise<AbstractSourceDict>

Performs data collection. Returns a promise which resolves to a dictionary of collected sources.

You should not call this method directly if you called BotD.load previously.

botDetector.detect(): Promise<BotDetectionResult>

Performs bot detection. Returns an object that contains information if it's a bot and it's name.

If you used BotD.load previously, you can call this method directly, otherwise you should call botDetector.collect first.

type BotDetectionResult =
    | {
          bot: true
          botKind: BotKind
      }
    | {
          bot: false
      }

enum BotKind {
    Unknown = 'unknown',
    HeadlessChrome = 'headless_chrome',
    PhantomJS = 'phantomjs',
    Nightmare = 'nightmare',
    Selenium = 'selenium',
    Electron = 'electron',
    NodeJS = 'nodejs',
    Rhino = 'rhino',
    CouchJS = 'couchjs',
    Sequentum = 'sequentum',
    SlimerJS = 'slimerjs',
    CefSharp = 'cefsharp',
}

Error handling

You should always call both load and detect with a .catch function where you should handle possible errors, e.g.

load()
    .then((botd) => botd.detect())
    .then((result) => console.log(result))
    .catch((error) => console.error(error)) // <==== Add this