URL: /introduction

---
title: Introduction
description: 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.

<CardGroup cols={2}>
  <Card title="Beacon (in the browser)" icon="code">
    One `<script>` tag records scored pageviews and, in form mode, attaches signals to submissions. Sees only clients that run JavaScript.
  </Card>
  <Card title="Server reporting (from your origin)" icon="server">
    `POST /v1/report` from a Cloudflare Worker, edge middleware, or any backend captures pure crawlers — including declared AI agents that never run scripts.
  </Card>
</CardGroup>

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.

```html
<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](/quickstart) for the full walkthrough and the [pageview tracking reference](/guides/pageview-tracking) for every attribute.

## What FormShield checks

Each observation is scored from these signals.

<CardGroup cols={2}>
  <Card title="IP intelligence" icon="globe">
    VPN, proxy, datacenter, and scanner detection plus country and ASN, from a reputation database.
  </Card>
  <Card title="Bot detection" icon="bot">
    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.
  </Card>
  <Card title="Automation detection" icon="bug">
    Browser fingerprint flags webdriver and headless automation — a strong tell that pushes a hit toward review or block.
  </Card>
  <Card title="Behavioral signals" icon="clock">
    Form-interaction telemetry on submissions. Pageviews have no form to interact with, so behavioral signals apply to form mode only.
  </Card>
  <Card title="Email reputation" icon="envelope">
    Disposable-domain, deliverability, and domain-age checks for submitted email addresses.
  </Card>
  <Card title="AI content analysis" icon="brain">
    LLM-based content scoring for form submissions to catch spam that rules miss.
  </Card>
</CardGroup>

## 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](/guides/bot-detection), so a confirmed search crawler defaults to `allow` while a spoofed one scores high.

<Note>
  Server reporting stores the score on the observation. It returns an acknowledgement, not a verdict — the dashboard is the source of truth for what each hit scored and why.
</Note>

## Key concepts

<ParamField path="Project" type="resource">
  A site or app you track. Observations, keys, and thresholds belong to a project. Create projects in the dashboard.
</ParamField>

<ParamField path="Observation" type="resource">
  One scored hit — a pageview, a form submission, or a server-reported request. Carries the score, decision, reasons, IP profile, and user-agent classification.
</ParamField>

<ParamField path="Publishable key" type="string">
  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.
</ParamField>

<ParamField path="Secret key" type="string">
  Server-side only. Used for the manual lookup and check APIs. Never expose a secret key in client code.
</ParamField>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get scored pageviews flowing in minutes.
  </Card>
  <Card title="Pageview tracking" icon="chart-line" href="/guides/pageview-tracking">
    The full beacon reference — modes, attributes, and observation shape.
  </Card>
  <Card title="Server reporting" icon="server" href="/guides/server-reporting">
    Capture crawlers and AI bots from your origin with `/v1/report`.
  </Card>
  <Card title="Bot detection" icon="bot" href="/guides/bot-detection">
    Name and IP-verify crawlers, and allow or block them per project.
  </Card>
  <Card title="Framework guides" icon="layers" href="/guides/nextjs">
    Integrate in Next.js, React, or TanStack Start.
  </Card>
</CardGroup>