Installing the PubSentry Tag

PubSentry installs as a single async <script> tag. There is no SDK to import, no WordPress plugin to maintain, and no build step on your side. You drop one line into your pages, point it at your site ID, and PubSentry starts scoring every visitor and blocking the invalid ones before the ad fires.

This page covers the install snippet in detail: where it goes, what it does on the page, the optional configuration attributes, how consent fits in, and how to confirm it is working.

The snippet

Paste this into the <head> of every page you want protected, replacing st_xxxx with your real site ID (you get it when you create a site at app.pubsentry.com):

<script async src="https://pubsentry.com/t.js" data-site="st_xxxx"></script>

That is the whole install. One line, once per page. You do not add a per-ad-unit snippet — PubSentry sits in front of your entire ad stack, not inside any one ad call.

The tag is served from https://pubsentry.com/t.js, is under 15KB gzipped, and loads async so it never blocks page render.

What the tag does on the page

When t.js loads, it runs a tightly bounded lifecycle, all wrapped so it can never throw into your page:

Reads its config — the data-site attribute (or a window.__PUBSENTRY__ global, see below) tells the tag which site this traffic belongs to. With no site ID, the tag silently does nothing.
Installs a honeypot and starts behavior tracking — invisible bait and lightweight interaction signals that help separate humans from automation, all fail-open via safe collectors.
Runs an early synchronous gate — before the first ad call, the tag computes a sub-5ms deterministic pre-score in the browser. This is block-before-serve: if the visitor is already obviously invalid, the ad slot never fires.
Installs enforcement across your ad stack — on a block, the tag suppresses the ad request across Google Publisher Tag (Ad Manager), AdSense / Auto Ads, Amazon apstag, and Prebid, plus a universal MutationObserver fallback that hides any ad iframe from networks without a dedicated hook (Taboola, Outbrain, Media.net, Ezoic, and so on).
Sends a beacon — once per pageview, on idle or pagehide, the tag POSTs a compact ClientBeacon to the ingest endpoint. The server enriches it (geo, ASN, datacenter detection from the IP; device from the User-Agent), scores it, updates reputation, and persists the event.
Sharpens borderline verdicts — if the local verdict is not a definite block, the tag can ask the edge for a sharper verdict using cross-site reputation and update enforcement if it comes back.

The tag only sends client-knowable fields. Raw IP and User-Agent are never sent by the tag — the server derives geo/network/device from the request, hashes the raw IP and UA with HMAC-SHA256, and then drops them. Nothing is stored in the clear.

Fail-open is a guarantee

The tag's hardest rule is that it will never break your revenue. Any error — a network hiccup, a parse failure, an unexpected ad stack — resolves to serve the ad anyway. The gate suppresses a slot only when it is actively enforcing and holding a definite block verdict. This is by design: a false positive (blocking a real human) is the worst possible failure, so when in doubt, the ad serves.

Optional configuration attributes

For most publishers, data-site is the only attribute you need. The tag also reads a few optional data-* attributes on the same <script> element if you need to override defaults:

data-beacon — override the beacon endpoint (defaults to https://pubsentry.com/v1/beacon).
data-click — override the click-tracking endpoint (defaults to the beacon URL's /v1/click).
data-verdict — set an edge verdict endpoint for sharpening borderline cases.

You generally should not set these. They exist for custom routing and self-host scenarios.

Configuring via a global instead of attributes

If your CMS makes it awkward to set data-* attributes, you can configure the tag with a window.__PUBSENTRY__ global set before t.js loads:

<script>
  window.__PUBSENTRY__ = { siteId: "st_xxxx", consent: "granted" };
</script>
<script async src="https://pubsentry.com/t.js"></script>

Values from the global take precedence over data-* attributes.

The tag accepts an initial consent state so it fits cleanly into a consent-managed page. Set it via the consent field on the window.__PUBSENTRY__ global. If you do not set it, consent defaults to unknown. Provide the value your consent management platform resolves (for example granted) so PubSentry's behavior matches your privacy posture from the first pageview.

Protection mode and the local gate

The gate's behavior is driven by your site's protection mode, which you set in the dashboard and the tag honors client-side:

Block (the default) — invalid visitors are suppressed before the ad fires.
Measure — the tag scores and beacons everything but suppresses nothing, so you can watch verdicts accumulate before letting it act.

The tag reads a cached copy of this config synchronously on boot, so the very first gate decision respects Measure mode and your safety-mode setting without waiting on the network. It then refreshes the config asynchronously; switching to Measure releases suppression immediately, and a changed safety mode applies on the next pageview.

Single-page apps

The boot path is idempotent — re-initializing the tag in a SPA is a safe no-op, so a framework that re-runs scripts on navigation will not double-fire. The tag beacons once per page load (on idle, falling back to pagehide).

Verifying the install

After the tag is live, open the Install screen for your site in the dashboard. It watches for the first beacon and confirms the loop end to end. Load a page on your real site (a deployed URL, not a local file://), and within a few seconds the screen should flip to verified. If it does not:

Confirm data-site exactly matches your site ID.
View source on the live URL and confirm the script is actually present.
Remember the free plan caps at 500 lifetime pageviews — beacons stop counting past the budget.

Once you see events in Overview and Live Feed, the tag is installed and the scoring loop is real.

Programmatic install and webhooks

Today, installation is the tag plus the dashboard. The /v1/* endpoints that power the dashboard are session-scoped to your account and back the UI, not a documented public integration. A stable, documented public API and outbound webhooks are on the roadmap (coming), not shipped. If you need programmatic provisioning or event streaming now, tell us what you are building so we can scope it honestly rather than point you at endpoints that may change.

That's the whole install

One async tag in the <head>, your site ID in data-site, 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.