AbuseZero browser SDK

The AbuseZero browser SDK, abusezero/browser, connects your pages to AbuseZero's device and automation intelligence, as described in Browser protection. On each claim it gathers browser evidence in the background, without blocking your page. It returns one value, the device token, which your server passes on with the evaluation. The SDK always resolves. When there's no browser data, such as when a visitor declines consent or a network blocks the request, the device token carries the reason instead. The evaluation still runs and reports exactly what it received.

import { init, observe, prepareBotObservation, forgetBrowser } from "abusezero/browser";

Use your publishable key (pk_…) in the browser. It can only send browser data from the sites in your site list, so it is safe to ship in your pages. Keep secret keys and the AbuseZero Node.js SDK out of your browser bundle. For a step-by-step setup, see Set up browser protection.

How the browser SDK worksCopy Anchor Link

1. Your page calls observe() or prepareBotObservation() with the claim's ID.
2. It sends the returned deviceToken to your server.
3. Your server sends the token in the evaluation as identifiers.device_token.

Use the same claim ID in the browser and on your server. The browser's claimId is the evaluation's claim_id.

initCopy Anchor Link

Call init once when your app starts.

init({ key: "pk_…" });

It reports once per page load that browser protection is installed on this site. It sends only the site's address and the SDK version, never visitor data. Developers → Browser setup, also available through GET /v1/browser-collection, shows each site where it was seen and which version it runs.

observeCopy Anchor Link

Call observe when the person submits the claim, then send the token to your server with it.

const observation = await observe({ key: "pk_…", claimId });

await fetch("/api/start-trial", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ claimId, deviceToken: observation.deviceToken }),
});

The observationCopy Anchor Link

observe never throws or rejects. It resolves to one of two shapes, and both carry deviceToken.

prepareBotObservationCopy Anchor Link

Add a bot check by calling prepareBotObservation instead of observe when the person submits the form. A benefit's automation settings decide whether the bot check is required; see Bots and AI agents. It collects the same browser data and adds the bot check, with the same options and result.

form.addEventListener("submit", async event => {
  event.preventDefault();
  const { deviceToken } = await prepareBotObservation({ key: "pk_…", claimId });

  await fetch("/api/start-trial", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ claimId, deviceToken }),
  });
});

Send its deviceToken in an evaluation within 2 minutes. AbuseZero verifies the bot check during that evaluation. When the token is too old, or a benefit that requires the bot check receives none, the evaluation returns a bot-check error, such as BOT_EVIDENCE_REQUIRED. See Add a bot check. Collect a fresh token and evaluate again. See Add a bot check.

ConsentCopy Anchor Link

Browser protection runs by default. Pass a consent callback to make it depend on your consent tool. See Respect consent.

const observation = await observe({
  key: "pk_…",
  claimId,
  consent: () => consentManager.hasConsent("security"), // Your consent tool.
});

• When consent resolves to false, nothing is collected and deviceToken is unavailable:consent_declined.
• When your consent tool keeps the SDK from loading at all, send unavailable:not_loaded as the device token.
• When a visitor withdraws consent, call forgetBrowser(). It clears what browser protection stored in this browser. Claim history already recorded in your workspace stays.

Unavailable reasonsCopy Anchor Link

When there is no browser data, reason and the device token say why. The same values appear as the evaluation's browser data status, and Troubleshooting covers each one. The token has the form unavailable:<reason>.

Developers → Browser setup shows how often each status appears across recent evaluations, and flags the ones you can fix as issues.

Your sitesCopy Anchor Link

AbuseZero accepts browser data only from HTTPS sites in your site list. Manage the list in Developers → Browser setup or through the Browser setup API.

If your site sets a Content Security Policy, copy the sources shown in Developers → Browser setup into it, as in Set up browser protection.

Standalone browser scriptCopy Anchor Link

For pages without a bundler, load the standalone script with your publishable key in its address. It runs init by itself.

<script type="module" src="https://abusezero.com/sdk/abusezero-browser-0.11.0.js?key=pk_…"></script>

To collect for a claim, import from the same address in a module script:

<script type="module">
  import { observe } from "https://abusezero.com/sdk/abusezero-browser-0.11.0.js?key=pk_…";

  const claimId = document.querySelector("#claim-id").value;
  const { deviceToken } = await observe({ key: "pk_…", claimId });
  document.querySelector("#device-token").value = deviceToken;
</script>

The address includes the version. When you upgrade, update every page to the new address.

Next stepsCopy Anchor Link