Browser Extension Workflow

This page explains what the browser extension does, why it exists, and how it works. The goal is to keep the experience clear, simple, and predictable for both users and partnering sites.

The Browser Extension

The Zero Ad Network browser extension lets users browse the web normally while quietly enabling benefits on participating websites.

When the extension is active, it sends a unique identifier (the Extension Token) with each page request. A partnering website responds with its own introductory token. This exchange allows both sides to recognize each other.

Once a partnering site detects and verifies the Extension Token, it serves content based on the user’s subscription plan. Depending on that plan, the site may apply features from:

• CLEAN_WEB
• ONE_PASS
• or both.

Site and Browser Extension Feature Overlap

To clarify how features from a user’s subscription plan and a partnering site interact, the table below shows which features are actually applied.

Only features that exist in both the user’s Extension Token and the site’s enabled features are considered valid. If there is no overlap, no features are applied.

User's plan	Site features	Overlap
Clean Web (CLEAN_WEB)	CLEAN_WEB, ONE_PASS	CLEAN_WEB
Clean Web (CLEAN_WEB)	ONE_PASS	❌
One Pass (ONE_PASS)	CLEAN_WEB, ONE_PASS	ONE_PASS
One Pass (ONE_PASS)	ONE_PASS	ONE_PASS
One Pass (ONE_PASS)	CLEAN_WEB	❌
Freedom (CLEAN_WEB and ONE_PASS)	CLEAN_WEB	CLEAN_WEB
Freedom (CLEAN_WEB and ONE_PASS)	ONE_PASS	ONE_PASS
Freedom (CLEAN_WEB and ONE_PASS)	CLEAN_WEB, ONE_PASS	CLEAN_WEB, ONE_PASS

In short, a partnering site only applies the subset of features that are supported by both the site and the user’s subscription plan.

How It Works

At a high level, the workflow is straightforward. A partnering site integrates the Zero Ad Network module (referred to below as the module) for the following reasons:

1. Site identification
   • The site sends a valid "X-Better-Web-Welcome" HTTP response header or an equivalent HTML meta tag.
   • This header contains:
     • The site’s unique Client ID
     • A list of features the site supports for Zero Ad Network users
   • This allows the browser extension to detect when a user visits a partnering site.
2. Feature negotiation
   • The browser extension injects an "X-Better-Web-Hello" HTTP request header into the main page request.
   • The site’s module verifies that this header is authentic.
   • Based on the verified token, the module determines which features should apply to that specific request.
   • Only features supported by both the partnering site and the browser extension are applied and delivered by the partnering site.
3. Content delivery
   • Using the resolved feature flags, the site tailors its HTTP response.
   • The delivered content matches the user’s subscription entitlements.

The Extension Token

After a user purchases a subscription and installs the browser extension (available for Google Chrome, Mozilla Firefox, and Microsoft Edge), we generate a digitally signed user token called the Extension Token.

The token is signed using the ED25519 algorithm. Any backend that supports ED25519 can verify the token using our official public key.

The Extension Token contains:

• Protocol version
• Expiration date
• ED25519 signature for the token
• A list of granted features the extension may request from partnering sites, such as:
  1. Removing advertisements
  2. Removing cookie-consent screens and enabling full opt-out of non-functional trackers
  3. Removing marketing dialogs and popups
  4. Providing free access to content behind a site's paywall
  5. Providing free access to the site's base subscription plan

Telemetry Data Collection

Telemetry data is collected only for partnering sites.

The extension tracks how often and how long users interact with participating websites. This data is periodically sent to the Zero Ad Network platform.

At the end of each calendar month:

• Data is aggregated for each active and unbanned participating site
• User subscription plans and pricing rules are applied
• Payouts are calculated for each site based on actual usage

This process ensures transparent and usage-based compensation for partnering sites.

For a detailed explanation of how payouts for partnering sites are calculated, see the Site Monetization Guidelines.