Migrating BotD v0 to v2

This guide shows how to migrate your code from BotD version 0 to version 2.

The API has changed, and you need to update your code.

In the new version, we have implemented detection logic on the client side, meaning we don't make requests to our servers. Also you don't need to generate any API keys anymore.

CDN

<script>
    // Initialize an agent at application startup.
-   const botdPromise = import('https://openfpcdn.io/botd/v0.1').then((BotD) =>
-       BotD.load({ publicKey: '<your-public-key>' }),
-   )
+   const botdPromise = import('https://openfpcdn.io/botd/v2').then((BotD) =>
+       BotD.load(),
+   )
    // Get the bot detection result when you need it.
-   // Result will contain the `requestId` property, that you can securely verify on the server.
    botdPromise
        .then((botd) => botd.detect())
        .then((result) => console.log(result))
        .catch((error) => console.error(error))
</script>

NPM

- import BotD from '@fpjs-incubator/botd-agent';
+ import BotD from '@fingerprintjs/botd';

// Initialize an agent at application startup.
- const botdPromise = BotD.load({ publicKey: '<your-public-key>' });
+ const botdPromise = BotD.load();

(async () => {
  // Get the bot detection result when you need it.
- // Result will contain the `requestId` property, that you can securely verify on the server.
  const botd = await botdPromise;
  const result = await botd.detect();
  console.log(result);
})();

The new response is now an object containing property "bot" indicating whether the user is a bot or not. And if "bot" is true, then we additionaly provide a property "botKind" as described in our API docs.

{
    "bot": "<boolean>",
    "botKind": "<BotKind | undefined>"
}

JavaScript output and browser support

Updated compilation target

The distributed bundles are now compiled to ES2018 instead of ES5. Modern build tools already handle this target, but any pipeline that assumed ES5 output (for example, older minifiers or ES5-only runtime environments) may require updates to accept or transpile ES2018 syntax.

Supported browsers

The minimum browser versions officially supported by BotD are listed in the browser support list. Confirm that the browsers you rely on meet or exceed these versions before deploying v2

Transpiling to ES5 when required

If you must keep ES5-compatible artifacts—for example, when embedding BotD into legacy applications—you now need to run that transpilation yourself. A typical setup using Babel might look like:

// babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "ie": "11"
        },
        "useBuiltIns": "usage",
        "corejs": "3.38"
      }
    ]
  ]
}

Or, if you compile with TypeScript, adjust your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES5",
    "downlevelIteration": true
  }
}

Make sure that your bundler (Webpack, Rollup, Vite, etc.) picks up these settings so that the BotD package is transpiled along with your application code. For Webpack with babel-loader, explicitly include the library so it is processed despite the default node_modules exclusion:

// webpack.config.js
module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.m?js$/,
        exclude: /node_modules\/(?!@fingerprintjs\/botd)/, // this will transpile BotD
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              [
                '@babel/preset-env',
                {
                  targets: { ie: '11' },
                  useBuiltIns: 'usage',
                  corejs: '3.38'
                }
              ]
            ]
          }
        }
      }
    ]
  }
}

If you use TypeScript, ensure that the bundler reads your tsconfig.json (for example via ts-loader or babel-loader with @babel/preset-typescript) so that the downlevel settings apply to both your code and BotD.