Skip to content
Botscent

A script tag

Add the page half of Botscent to any page with one script tag and check the install.

Add the page half of Botscent to any HTML page with a script tag. The script runs in the browser and needs no build step. The server half runs in the server for your pages or your API.

Before you start

You need:

  • Node.js 22.12 or later, to install the package and run the check.
  • A server that serves static files from your own origin.

1. Install the package

Install botscent from npm.

Terminal
npm install botscent

With pnpm, yarn or bun, use their add command.

2. Add the page half

Copy node_modules/botscent/dist/botscent.js to the folder that your server serves as static files. This example uses public.

Terminal
cp node_modules/botscent/dist/botscent.js public/botscent.js

In the <head> of each page, add a deferred script tag for /botscent.js.

index.html
<script defer src="/botscent.js"></script>

The script now starts itself on each page.

3. Add the server half

The script tag adds only the page half. Add the server half to the server for your pages or your API. Use the page for that server:

4. Read the verdict

The script exposes window.botscent with verdict, subscribe, reportHeaders, diagnostics, start and VERSION.

On every change of the page verdict, the script dispatches a botscent event on window. The event's detail is the new verdict. A listener for the first botscent event can already call window.botscent.

In a page script, call botscent.verdict to show the page verdict. Listen for the botscent event to show each change.

index.html
<pre id="verdict"></pre>
<script>
  const show = () => (document.getElementById('verdict').textContent = JSON.stringify(botscent.verdict()))
  addEventListener('DOMContentLoaded', show)
  addEventListener('botscent', show)
</script>

In a normal browser, the page shows {"type":"human","reasons":[]}.

Warning: Do not use the page verdict to allow access. The visitor's browser computes the page verdict. On your server, use isVerified on the request's own verdict, as The trust model describes.

5. Check the install

Serve the page. Then run the check against its URL.

Terminal
npx botscent check https://your-site.example/

The page-script check prints pass, and the command exits with code 0.

Without a server half that sends the request's own verdict to the page, the server-half check prints unknown. If a check fails, see Verify your install.

Debug output

To log the page half's decisions, add data-debug to the script tag.

index.html
<script defer src="/botscent.js" data-debug></script>

The browser console now shows one line for each decision, with the prefix [botscent].

Content Security Policy

The script has no inline code and no eval. Under a strict Content Security Policy, script-src must allow the script's origin. When you serve the script yourself, that origin is 'self'.

As an alternative, put a nonce on the script tag and add 'strict-dynamic' to script-src. If the policy blocks the script, the csp check of npx botscent check fails.

Next steps