HideGuardDocumentation

Start · Getting started

How it works

The path of one visit: browser, ingest, scoring, verdict.

A visit passes through four stages. Knowing which stage does what is the quickest way to read an unexpected number on the dashboard.

The browser measures#

The SDK runs as the page loads. It reads the things a real browser finds hard to fake all at once: canvas, WebGL, audio, fonts, text geometry, time zone, language, screen, input devices.

What matters is not each value on its own but whether they agree with each other. A browser claiming macOS while rasterising text the way Windows does has contradicted itself, and the contradiction is the hard part to stage.

When a measurement cannot run, an API blocked, a context refused. It is recorded as unmeasured. It is never rounded to normal.

The collector scores it#

The browser posts to POST /api/v1/collect. The server:

  1. Derives a visitor ID from the stable measurements. The IP is not an input. See Visitor ID.
  2. Looks the address up in reputation databases held on disk: proxy, VPN, Tor, datacenter, abuse history.
  3. Runs each rule. A rule that fires produces a reason with a code, a severity and a weight.
  4. Sums the weights into a score, compares it to the thresholds, and answers.
  5. Stores the raw signals: never the verdict.

The reply is signed with Ed25519, so your backend can tell our answer from one the visitor wrote. See Verifying replies.

The page receives the verdict#

The SDK dispatches fpc:verdict, and draws the interstitial if data-block is on. This layer is for showing a real person what is happening; it is not the protection.

Your server asks again#

Before accepting anything important, your backend calls POST /api/v1/verdict. Two cases:

  • This browser is known, the stored visit answers, with the operator blocklist applied on top. The reply says source: "visit".
  • It is not: judged from the user agent, the address and whatever headers you forwarded. Far less to go on, and enough to stop curl. The reply says source: "request".

No outbound IP lookup happens at this step. Address reputation is read off the visit we already stored, because putting a third party in the path of your checkout puts their downtime in your revenue.

What runs afterwards#

  • Heartbeat, the page beats back every 15 seconds so the dashboard can count how many pages are open. It is not a visit and is never scored.
  • Behaviour: pointer, clicks, scroll, focus changes, held in memory and attached to the collect that was happening anyway. It adds no request while the visitor is on the page.
  • Webhooks: if you register one, every recorded visit is delivered to your endpoint.