Scripts

Optional browser script that adds browser-side signals and establishes a session up front.

Overview

The Centinel collector script is an optional addition to your site. It runs in the browser, sets the _centinel cookie, and feeds browser-side signals back to the validator.

Server-only validation works without it, on a smaller signal set. The script adds the browser and network signals that no amount of server-side data can reveal, which is what catches automation driving a real browser. The _centinel cookie it sets gives the validator a session key before the first challenge.

The interstitial challenge does not need this script. The validator injects its own copy into the interstitial it serves, so challenges work on a server-only install too.

Add the script

Drop this in your page <head> and replace SITE_KEY with your site key (from the Dashboard).

<html>
  <head>
    <script src="https://collector.centinelanalytica.com/script.js?site_key=SITE_KEY" defer></script>
    <!-- Rest of the head -->
  </head>
  <body>
    <!-- Page content -->
  </body>
</html>

Keep the defer. Several signals read the DOM, so a script that runs before <body> exists collects less and weakens detection. defer also keeps the parser from blocking on the download.

Where to install it

Add the script to any page where a protected action can be triggered:

Login forms (or any page hosting a login modal)
Signup and password-reset flows
Checkout and payment pages
Gated content: premium articles, paid downloads, members-only areas
Comment, review, and other user-generated-content submission

Single-page apps

Install the script once in the global layout, not per route, to avoid double-loading. It collects once per full document load and deliberately does not hook client-side navigation, so a route change does not re-run collection. That is fine: the session it established on first load carries across routes.

Verify

Load a page and check three things in your browser's dev tools:

The request to collector.centinelanalytica.com/script.js returns 200. A 401 means the site_key is missing or wrong, and no signals are collected.
A POST to the collector origin carries the payload.
A first-party _centinel cookie is set.

In code, check window.cen.initialized to confirm the script finished. If it is not ready yet, wait for the CentinelInitialized event.

The event fires only after the payload upload succeeds, and a failed upload is not retried. Always pair the wait with a timeout, or a visitor on a flaky network can never complete the action you gated behind it.

function whenCentinelReady(cb, timeoutMs = 2000) {
  if (window.cen && window.cen.initialized) {
    cb();
    return;
  }

  let done = false;
  const run = () => {
    if (done) return;
    done = true;
    window.removeEventListener('CentinelInitialized', run);
    cb();
  };

  window.addEventListener('CentinelInitialized', run);
  setTimeout(run, timeoutMs); // never block the action on the script
}

whenCentinelReady(() => {
  login();
});

Next steps

Whether you added the script or chose to skip it, your backend needs to call /validate on every protected request.

Validation

Wire the /validate API into your backend.