Introduction
Score live traffic and protect forms with one beacon and a server-side report endpoint
FormShield protects web forms and scores live traffic. Embed one beacon (formshield.js) and it records every scored pageview by default; add the same beacon’s form mode to attach signals to submissions; or report traffic server-side to catch crawlers and AI bots that never run JavaScript.
Every hit becomes a typed observation with a risk score from 0.0 to 1.0 and an allow / review / block decision. Observations land in a real-time dashboard with IP profiles, filtering, named bot detection, and a feedback loop.
How it fits together
You integrate FormShield in one or both of two ways. They share one publishable key and feed the same observation stream.
One <script> tag records scored pageviews and, in form mode, attaches signals to submissions. Sees only clients that run JavaScript.
POST /v1/report from a Cloudflare Worker, edge middleware, or any backend captures pure crawlers — including declared AI agents that never run scripts.
The beacon is the fastest start; server reporting closes the gap on non-JS traffic. Most sites run both.
The beacon embed
A single async <script> tag with your publishable key. It auto-initializes and records one scored pageview on load.
<script
async
src="https://api.formshield.dev/js/formshield.js"
data-fs-project-key="fs_pub_live_…"
data-fs-action="pageview"
data-fs-mode="pageload"
></script>Paste it, load a page, and the observation appears in the dashboard Logs. See the Quickstart for the full walkthrough and the pageview tracking reference for every attribute.
What FormShield checks
Each observation is scored from these signals.
VPN, proxy, datacenter, and scanner detection plus country and ASN, from a reputation database.
Names AI crawlers (GPTBot, ClaudeBot, PerplexityBot) and search crawlers (Googlebot, Bingbot), and IP-verifies the ones whose operators publish ranges — so a forged “Googlebot” from the wrong IP is flagged as spoofed.
Browser fingerprint flags webdriver and headless automation — a strong tell that pushes a hit toward review or block.
Form-interaction telemetry on submissions. Pageviews have no form to interact with, so behavioral signals apply to form mode only.
Disposable-domain, deliverability, and domain-age checks for submitted email addresses.
LLM-based content scoring for form submissions to catch spam that rules miss.
Scoring model
Every observation carries a score, a decision, and a list of reasons.
| Field | Type | Meaning |
|---|---|---|
score | float 0.0–1.0 | Risk probability. 0.0 is a clean human; 1.0 is almost certainly a bot. |
decision | allow | review | block | Derived from score against per-project thresholds. |
reasons | string array | Rules that fired, e.g. bot:ai_crawler, automation_detected, ip_datacenter. |
Pageview thresholds:
| Decision | Score range |
|---|---|
allow | below 0.45 |
review | 0.45 to below 0.8 |
block | 0.8 and above |
The review and block cutoffs are per-project: set them in the project’s Settings → Thresholds to tune how aggressive scoring is for your traffic. Automation tells (webdriver, headless) and a declared AI-crawler user agent are strong signals that push a hit to review or block. FormShield also detects and IP-verifies bots, so a confirmed search crawler defaults to allow while a spoofed one scores high.
Key concepts
Project resource path A site or app you track. Observations, keys, and thresholds belong to a project. Create projects in the dashboard.
Observation resource path One scored hit — a pageview, a form submission, or a server-reported request. Carries the score, decision, reasons, IP profile, and user-agent classification.
Publishable key string path Prefixed fs_pub_live_…. Safe to expose in the browser. The beacon embeds it, and /v1/report authenticates with it. Create one in the project’s Settings.
Secret key string path Server-side only. Used for the manual lookup and check APIs. Never expose a secret key in client code.
Next steps
Get scored pageviews flowing in minutes.
The full beacon reference — modes, attributes, and observation shape.
Capture crawlers and AI bots from your origin with /v1/report.
Name and IP-verify crawlers, and allow or block them per project.
Integrate in Next.js, React, or TanStack Start.