How It Works
When a Zero Ad Network subscriber visits your site, the browser extension and your server exchange two tokens. This handshake takes milliseconds, requires no external network call, and determines exactly what the subscriber is entitled to on your site.
The handshake
Step 1 - Your site identifies itself
Every page response from your server includes a signed token in a custom HTTP header:
X-Better-Web-Welcome: Z2CclA8oXIT1e0QmqTWF8w^1^3
This token encodes your site's unique clientId and the features your site supports (CLEAN_WEB, ONE_PASS, or both). The browser extension reads this header on every page load and recognizes your site as a partner.
Step 2 - The extension identifies the subscriber
If the visitor is an active subscriber, the extension injects a signed token into the page request:
X-Better-Web-Hello: Aav2IXRoh0oKBw==.2yZfC2/pM9DW...
This token carries the subscriber's enabled features and expiration date. It contains no personal information - only what the subscriber is entitled to access.
If the visitor is not a subscriber, no token is sent. Your server sees a normal request.
Step 3 - Your server decides what to serve
If you've integrated the server-side module, it verifies the incoming token against Zero Ad Network's public ED25519 key (locally - no network call) and resolves a set of feature flags:
{
HIDE_ADVERTISEMENTS: true,
HIDE_COOKIE_CONSENT_SCREEN: true,
HIDE_MARKETING_DIALOGS: true,
DISABLE_NON_FUNCTIONAL_TRACKING: true,
DISABLE_CONTENT_PAYWALL: false,
ENABLE_SUBSCRIPTION_ACCESS: false,
}
Your server uses these flags to tailor the response: hiding ads, suppressing cookie banners, or granting paywall access. Non-subscribers receive the site as normal.
Feature matching
Only features that exist in both the subscriber's plan and your site's declared features take effect. If there's no overlap, no features are applied and the visit is recorded as non-subscriber.
| Subscriber plan | Your site features | What applies |
|---|---|---|
| Clean Web | Clean Web | Clean Web |
| Clean Web | One Pass | Nothing |
| One Pass | One Pass | One Pass |
| One Pass | Clean Web | Nothing |
| Freedom | Clean Web | Clean Web |
| Freedom | One Pass | One Pass |
| Freedom | Clean Web + One Pass | Both |
Telemetry
The browser extension tracks time spent on partner sites and reports it to the Zero Ad Network platform daily. This data drives the monthly payout calculation.
Telemetry is anonymous - the platform receives time-on-site metrics with no personally identifiable visitor information.
Token reference
Server header (X-Better-Web-Welcome) - generated once at startup from your clientId and declared features. Static per deployment.
Client token (X-Better-Web-Hello) - issued by the platform when a user purchases a subscription. Signed with ED25519. Contains:
- Protocol version
- Expiration date
- Granted features
Verification is purely local: your server computes the signature check against Zero Ad Network's public key. It adds roughly 0.06-0.6 ms per request (measured on M1 MacBook Pro). An expired token is treated the same as no token - all feature flags resolve to false.
The @zeroad.network/token library (npm) and zeroad.network/token Composer package handle both header generation and token verification. You don't need to implement the cryptography yourself.