PubSentry is the AI Security Engineer for ad publishers: it scores every visitor in real time and blocks the invalid ones before the ad fires — protecting both your ad revenue and your AdSense/ad-network account from invalid-traffic penalties. There is no SDK, no WordPress plugin, and no build step on your side. You add one async <script> tag, point it at your site ID, and you are live.
This guide takes you from zero to a protected page in a few minutes, then explains what to do next.
1. Create an account and a site
Sign in at app.pubsentry.com and create your first site. A site is a single property (one domain) that PubSentry scores independently — its own config, its own rules, its own analytics. When you create one, you get a site ID that looks like st_8c193ddda799c7745b. That ID is what the tag uses to attribute traffic to your account.
Every new account starts on the free plan: 500 lifetime pageviews. That is enough to install, verify the loop end to end, and watch real verdicts land in your dashboard before you decide on a paid plan. It is not a time-limited trial — it is a hard pageview budget. Paid plans (Starter, Growth, Scale) differ only by volume — pageviews, number of sites, and history retention. Every detection and DEFEND feature is on every plan, including free; only the Enterprise contractual set (SSO, SOC 2 DPA, data residency, SLA) is gated.
2. Install the tag
Paste this into the <head> of every page you want protected, replacing st_xxxx with your real site ID:
<script async src="https://pubsentry.com/t.js" data-site="st_xxxx"></script>That is the entire install. A few things worth knowing about what that one line does:
- It is async and fail-open. The tag is under 15KB gzipped and never blocks page render. If anything goes wrong — a network hiccup, a parse error, an unexpected ad stack — the tag's hard rule is to serve the ad anyway. It will never throw into your page or delay an impression. Failing open is a design principle, not a fallback.
- It runs a local gate first. Before any ad call, the tag runs a sub-5ms verdict in the browser ("block-before-serve"). On a block it suppresses the ad request across Google Publisher Tag, AdSense, Amazon apstag, and Prebid, plus a universal
MutationObserverfallback for anything else. The ad slot simply never fires for that visitor. - It is ad-network-agnostic. PubSentry sits in front of your ad stack, not inside any one network's SDK. The same tag protects AdSense, Ad Manager, and header-bidding setups.
Put the tag on the page once. You do not need a per-ad-unit snippet.
3. Verify your first beacon
After the tag loads, it sends a beacon to the ingest service for every pageview. On the server side, ingest enriches the request (geo, ASN, datacenter detection from the IP; device from the User-Agent), scores it, updates reputation, and persists the event. Raw IP and User-Agent are hashed server-side with HMAC-SHA256 and then dropped — they are never stored in the clear.
In the dashboard, open Install for your site. It watches for the first beacon and confirms the loop is working end to end. Load a page on your real site (not a local file), and within a few seconds the dashboard should flip to "verified." If it does not:
- Confirm the
data-sitevalue exactly matches your site ID. - Confirm the script is actually on the page (view source on the live URL).
- Remember the free plan caps at 500 lifetime pageviews — beacons stop counting once you hit the budget.
Once you see live events in the Overview and Live Feed screens, the loop is real.
4. Choose a protection mode
Each site has a protection mode that the tag honors client-side:
- Block (the default) — invalid visitors are stopped before the ad fires. This is block-before-serve doing its job.
- Measure — PubSentry scores and records everything but suppresses nothing. Use this for a few days if you want to watch verdicts accumulate before you let it act. It is the safe way to build confidence.
There is also a safety mode dial — conservative, balanced (the default), or aggressive — that tunes how strict the thresholds are. The defaults are deliberately conservative because of the project's first principle: a false positive (blocking a real human) is the worst possible failure. Start at balanced and only move toward aggressive if you have a specific abuse pattern and have watched the blast-radius preview.
5. What you'll actually catch
Be honest with yourself about the detection boundary, because PubSentry is. The deterministic engine catches obvious, general invalid traffic (GIVT) — known bots, datacenter IPs, automation tells, declared crawlers — at near-100% recall with zero false positives. That is the bulk of the junk hitting most publishers, and it is gone the moment you switch to Block mode.
Sophisticated invalid traffic (SIVT) — bots running from residential IPs with no behavioral tells — is harder, and today only a fraction is caught by design. Blocking that traffic aggressively would risk blocking real humans, which violates the FPR-zero principle. That gap closes as the reputation network and the ML moat accumulate real traffic. PubSentry will never claim "100%" — anyone who does is selling you false positives.
6. Go further with DEFEND and BRIEFING
Once traffic is flowing, the dashboard gives you more than charts:
- Rules & IP management — write your own block/allow rules with a retroactive blast-radius preview so you can see exactly who a rule would have affected before you ship it.
- Alerts — get notified on threshold breaches; backtest and test-fire an alert before arming it.
- Today / Recommendations — the AI agent sweeps your data, narrates what changed, and proposes rules. You approve a recommendation and it becomes a real, enforced rule. The AI narrates; it never invents a number and never decides a verdict on the hot path.
- Ad Policy & Click Abuse — surface policy-risk content and click patterns that put your ad-network account at risk.
A note on APIs and webhooks
PubSentry exposes read and DEFEND endpoints under /v1/* that power the dashboard (overview, timeseries, rules, alerts, agent). These are session-scoped to your account today — they back the UI, not a documented public integration. A stable, documented public API and outbound webhooks are on the roadmap (coming), not shipped. If your workflow needs programmatic access now, tell us what you're building so we can scope it honestly rather than point you at endpoints that may change.
You're protected
That's the whole path: create a site, drop in one async tag, verify the first beacon, and leave it in Block mode. From there, PubSentry scores every visitor, stops the invalid ones before the impression fires, and explains every decision — without ever risking a real reader.