No requests sent to data collection services contain any personally identifiable information. To learn about eyeometry, view User Counting.

Obligatory arguments

You must provide special gn arguments before building your product in order to enable user counting.

• eyeo_telemetry_client_id

• eyeo_telemetry_activeping_auth_token

eyeo will provide the argument values upon contact.

To set the arguments, generate project build files like the following:

gn gen --args='eyeo_telemetry_client_id="mycompany" eyeo_telemetry_activeping_auth_token="peyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" ...' ...

If you don't set these arguments, eyeo will not correctly attribute users to your product, although your application will still build and run.

User counting doesn't transfer any PII or other identifiable data to eyeo, nor does it allow tracking or profiling of users by eyeo.

Optional arguments

You may additionally provide values for application and application_version by setting the following gn arguments:

• eyeo_application_name

• eyeo_application_version

For example:

gn gen --args='eyeo_telemetry_client_id="mycompany" eyeo_telemetry_activeping_auth_token="peyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" eyeo_application_name="My great browser" eyeo_application_version="111.24.0.1" ...' ...

In absence of these values, the eyeo Browser Ad-Filtering Solution will fall back to version_info::GetProductName() and version_info::GetVersionNumber() from version_info.h

About eyeo

eyeo is dedicated to building technology that supports a fair and sustainable online value exchange between users, publishers and advertisers.

eyeo Ad-Filtering Solutions offer customizable options to enhance your mobile and desktop products with minimal technical effort.

Ad-filtering solutions

eyeo offers several ad-filtering solutions for your development projects across different platforms and browsers. Jump right in with the Browser Ad-Filtering Solution or the Web Extension Ad-Filtering Solution.

If you need help with another eyeo product or you're interested in becoming a tech partner, reach out to the eyeo team.

Working with snippets

eyeo uses snippets to fight ad-filtering circumvention. eyeo's snippets documentation explains what snippets are, which snippets you can use, and examples for putting them into practice.

In this guide, you'll learn about the different ways you can integrate the eyeo Browser Ad-Filtering Solution into your own Chromium-based browser project.

Integration strategies

You can integrate eyeo's changes into your own Chromium project in three ways:

• Strategy 1: Base your product on top of eyeo's changes

• Strategy 2: Download modules and apply them to your source code

• Strategy 3: Create a patch with changes and apply it to your source code

• Strategy 4: Copy eyeo's functionality into your adapation

In the following sections, you'll learn the advantages of each strategy.

$ git diff 113.0.5672.76 eyeo-release-113.0.5672.76-v1 > ../eyeo-release-113.0.5672.76-v1.diff

$ git apply ../eyeo-release-113.0.5672.76-v1.diff

About automation

If you decide to automate the steps to copy eyeo's functionality into your adaptation, remember to:

• Write the script files that automate the steps.

• Update the scripts when branch/tag naming agreements are changed or the release flow is changed.

As with any automated, consider whether the time saved will compensate for the efforts to write and test the automation scripts. eyeo can help you decide, so reach out to us with any questions.

eyeo's versioning scheme

For an example Chromium release tag of 113.0.5672.76, eyeo's release tag would be eyeo-release-113.0.5672.76-v1.diff. This tag would contain all Solution-related changes, based on top of the corresponding Chromium release.

Because eyeo hosts the Browser Ad-Filtering Solution in remote Git repositories, you can find the Solution release for each version:

$ git ls-remote --tags https://gitlab.com/eyeo/adblockplus/chromium-sdk
$ git tag | grep release-103
eyeo-release-113.0.5672.76-v1

Usually, one release tag is available for each major Chromium version. Patch releases may also be available if eyeo finds a critical bug in the release.

About the eyeo Browser Ad-Filtering Solution

eyeo's Browser Ad-Filtering Solution is a software development kit that you can use to integrate eyeo's ad-filtering technology into Chromium-based browsers.

Maintained as a set of patches added to the Chromium project, the Solution lets you incorporate eyeo's ad-filtering functionality and filter lists into your own browser.

By the end of this quickstart guide, you'll have cloned the Solution's project and built Chromium with ad blocking for Linux.

Install depot_tools

Follow these steps to set up depot_tools:

1. Clone the repository:

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

1. Add depot_tools to your PATH:

export PATH="$PATH:/path/to/depot_tools"

When cloning depot_tools to your home directory do not use ~ on PATH, otherwise gclient runhooks will fail to run. Rather, you should use either $HOME or the absolute path:

export PATH="$PATH:${HOME}/depot_tools"

Warning: It is a good idea at this point to make sure that the gn command is pointing to depot_tools, as it is sometimes possible that a different instance of gn is present on the system:

whereis gn

The output of this command should only show:

gn: /path/to/depot_tools/gn

If there are any others listed in the output, delete them.

Get the eyeo Browser Ad-Filtering Solution code

Clone the eyeo Browser Ad-Filtering Solution repository using the following command:

mkdir chromium && cd chromium
git clone https://gitlab.com/eyeo/adblockplus/chromium-sdk src/

Expect the command to take 30 minutes on even a fast connection, and many hours on slower ones.

Update dependencies and build

1. Create a .gclient configuration file relevant for your development platform:

Put one of these .gclient files into chromium/ (not chromium/src/):

solutions = [
  {
    "url": "https://chromium.googlesource.com/chromium/src.git",
    "managed": False,
    "name": "src",
    "deps_file": ".DEPS.git",
    "custom_deps": {},
  },
]

solutions = [
  {
    "url": "https://chromium.googlesource.com/chromium/src.git",
    "managed": False,
    "name": "src",
    "deps_file": ".DEPS.git",
    "custom_deps": {},
  },
]
target_os = ["android"]

solutions = [
  {
    "url": "https://chromium.googlesource.com/chromium/src.git",
    "managed": False,
    "name": "src",
    "deps_file": ".DEPS.git",
    "custom_deps": {},
  },
]
target_os = ["win"]

1. Run gclient sync to update the third party dependencies of Chromium:

This steps downloads and sets up dependencies, in accordance with the .gclient file you created in the previous step.

gclient sync --force --reset --delete_unversioned_trees --no-history

1. Set up the build:

Chromium uses Ninja as its main build tool along with a tool called GN to generate .ninja files. You can create any number of build directories with different configurations. To create a build directory, run:

cd src/
gn gen out/Default

1. Build chromium with unit tests:

The following command builds chrome and unit tests:

autoninja -j X -C out/Default chrome components_unittests

where X should be an integer to represent how many jobs should be triggered on the build cluster, to ensure that your system is not overloaded with too many jobs running locally.

Depending on your hardware the build might take several hours to complete.

Run unit tests

You can run ad-filtering unit tests with the following command:

./out/Default/components_unittests --gtest_filter="*Adblock*"

For a more detailed build description and for building for other platforms follow Chromium's standard instructions.

Next up

In this quickstart guide, you cloned and built the eyeo Browser Ad-Filtering Solution and unit tests.

To test the ad-filtering capabilities of the browser see Testing

Check out the eyeo Browser Ad-Filtering Solution Features documentation to learn how the Solution handles common ad-filtering use cases.

To improve eyeo's understanding of cross-platform usage and versioning, the eyeo Browser Ad-Filtering Solution collects some user data.

Because one of eyeo's driving principles is to respect user privacy, no requests sent to data collection services contain any personally identifiable information (PII).

This page contains information on how and why eyeo implements user counting in its ad-filtering solutions.

Why eyeo count users

eyeo count users who have both ad-filtering and Acceptable Ads scheme enabled, as well as those who only have ad-filtering enabled. eyeo does this for the following reasons:

• Understanding user distribution across Chromium and Solution versions helps eyeo decide which versions to maintain and which to deprecate.

• Understanding user distribution across operating systems and platforms helps eyeo prioritize quality assurance and automation efforts on the most popular platforms and OS versions.

• Understanding how users perceive Acceptable Ads, which eyeo determines from user opt-out rate. eyeo wants to ensure that ads that users see don't negatively impact user experience.

• Establishing the basis of payouts to partners who monetize their Acceptable Ads users.

How user counting works

A ping request is sent automatically by the Solution to eyeo's dedicated service at least twice per day, if the browser is in use (including in the background) and ad-filtering is enabled. These contain no personally identifiable information.

Ping request payload

To track active clients while maintaining user privacy, the server combines the values of ping timestamps with a randomly-generated tag. Dates are truncated to further protect privacy.

The following table outlines the parameters sent with the ping:

Update the Solution

Overview

You can use eyeo's interdiffs script to generate interdiffs between different releases of the eyeo Browser Ad-Filtering Solution. These interdiffs show the changes made between two specific releases, and the resulting diff files are saved in the eyeo_modules/interdiffs/ directory, which will be created if it doesn't exist. The script leverages git diff functionality to generate the interdiffs.

Module interdiffs are supported from version 115 of the eyeo Browser Ad-Filtering Solution.

Usage

./tools/adblock/generate_interdiffs.sh <eyeo-release-tag> <eyeo-release-tag> <options>

You can get the necessary tags for the revision ranges from release announcements.

Options

The script accepts several options to customize the generation of interdiffs:

--full-sdk: Generates a single diff file that includes changes for the entire eyeo Browser Ad-blocking Solution, including testing and CI (Continuous Integration) files.

--all-modules: Generates individual diff files for each module within the Solution, including base, chrome, webview, android-api, android-settings, and extension-api.

--base: Generates a diff file for changes in the base module.

--chrome: Generates a diff file for changes in the Chrome Integration module.

--webview: Generates a diff file for changes in the Android Webview Integration module.

--android-api: Generates a diff file for changes in the Android API module.

--android-settings: Generates a diff file for changes in the Android UI module.

--extension-api: Generates a diff file for changes in the Extension API module.

Example Usage

Generate an interdiff between two eyeo Browser Ad-Filtering Solution releases with the base, chrome, and android-api modules:

./tools/adblock/generate_interdiffs.sh eyeo-release-111.0.5563.58-6.0-v1 eyeo-release-113.0.5672.76-v1 --base --chrome --android-api

Generate an interdiff for the entire eyeo Browser Ad-Filtering Solution between two specific releases:

./tools/adblock/generate_interdiffs.sh eyeo-release-111.0.5563.58-6.0-v1 eyeo-release-113.0.5672.76-v1 --full-sdk

Available APIs

You can control the ad-filtering behavior via any of these entry points:

• The C++ class FilteringConfiguration,

• The Java class org.chromium.components.adblock.FilteringConfiguration

• The Browser Extension API defined and documented in chrome/common/extensions/api/eyeo_filtering_private.idl

API requirements

Capabilities

Toggle ad filtering

To toggle ad filtering call setEnabled with the appropriate bool value:

To query if ad filtering is enabled call isEnabled.

The following example disables ad filtering:

import org.chromium.components.adblock.FilteringConfiguration;

// Creates "adblock" configuration if does not exist yet, returns a valid handle.
FilteringConfiguration adblockConfiguration = FilteringConfiguration.createConfiguration("adblock", browserContextHandle);

adblockConfiguration.isEnabled();  // true
adblockConfiguration.setEnabled(false);
adblockConfiguration.isEnabled();  // false

chrome.eyeoFilteringPrivate.isEnabled("adblock");  // true
chrome.eyeoFilteringPrivate.setEnabled("adblock", false);
chrome.eyeoFilteringPrivate.isEnabled("adblock");  // false

#include "components/adblock/content/browser/factories/subscription_service_factory.h"
#include "components/adblock/core/subscription/subscription_config.h"
#include "components/adblock/core/subscription/subscription_service.h"
#include "components/adblock/core/configuration/filtering_configuration.h"

  auto* subscription_service =
      adblock::SubscriptionServiceFactory::GetForBrowserContext(context);
  auto configuration = subscription_service->GetFilteringConfiguration("adblock");
  configuration->isEnabled(); // true
  configuration->SetEnabled(false);
  configuration->isEnabled(); // false

Toggle Acceptable Ads

You can toggle Acceptable Ads by adding or removing a filter list with the Acceptable Ads URL. The following example:

1. checks whether Acceptable Ads are enabled

2. disables them

3. verifies that Acceptable Ads are disabled

import org.chromium.components.adblock.FilteringConfiguration;

// Creates "adblock" configuration if does not exist yet, returns a valid handle.
FilteringConfiguration adblockConfiguration = FilteringConfiguration.createConfiguration("adblock", browserContextHandle);

adblockConfiguration.getFilterLists().contains(FilteringConfiguration.getAcceptableAdsUrl());  // true
adblockConfiguration.removeFilterList(FilteringConfiguration.getAcceptableAdsUrl());
adblockConfiguration.getFilterLists().contains(FilteringConfiguration.getAcceptableAdsUrl());  // false

let aa_url;
chrome.eyeoFilteringPrivate.getAcceptableAdsUrl()
    .then(url => aa_url = url)
    .then(() => chrome.eyeoFilteringPrivate.getFilterLists("adblock"))
    .then(list => list.includes(aa_url))  // true
    .then(() => chrome.eyeoFilteringPrivate.removeFilterList("adblock", aa_url))
    .then(() => chrome.eyeoFilteringPrivate.getFilterLists("adblock"))
    .then(list => list.includes(aa_url)); // false

#include "components/adblock/content/browser/factories/subscription_service_factory.h"
#include "components/adblock/core/subscription/subscription_config.h"
#include "components/adblock/core/subscription/subscription_service.h"
#include "components/adblock/core/configuration/filtering_configuration.h"

  auto* subscription_service =
      adblock::SubscriptionServiceFactory::GetForBrowserContext(context);
  auto configuration = subscription_service->GetFilteringConfiguration("adblock");
  configuration->IsFilterListPresent(AcceptableAdsUrl()); // true
  configuration->RemoveFilterList(AcceptableAdsUrl());
  configuration->IsFilterListPresent(AcceptableAdsUrl()); // false

Add/Remove filter lists

Filter lists are uniquely identified by URLs from which they're downloaded.

Use addFilterList to add and removeFilterList to remove a filter list.

To get the list of installed subscriptions use getFilterLists.

The following code snippet installs http://example.com/example_list.txt:

import org.chromium.components.adblock.FilteringConfiguration;

// Creates "adblock" configuration if does not exist yet, returns a valid handle.
FilteringConfiguration adblockConfiguration = FilteringConfiguration.createConfiguration("adblock", browserContextHandle);
URL exampleFilterList = new URL("http://example.com/example_list.txt");

adblockConfiguration.addFilterList(exampleFilterList);
adblockConfiguration.getFilterLists();  // ["http://example.com/example_list.txt", ...]

var exampleFilterList = new URL("http://example.com/example_list.txt");
chrome.eyeoFilteringPrivate.addFilterList("adblock", exampleFilterList.href);
chrome.eyeoFilteringPrivate.getFilterLists("adblock");  // ["http://example.com/example_list.txt", ...]

#include "components/adblock/content/browser/factories/subscription_service_factory.h"
#include "components/adblock/core/subscription/subscription_config.h"
#include "components/adblock/core/subscription/subscription_service.h"
#include "components/adblock/core/configuration/filtering_configuration.h"

const GURL example_filter_list("http://example.com/example_list.txt");
auto* subscription_service =
    adblock::SubscriptionServiceFactory::GetForBrowserContext(context);
auto configuration = subscription_service->GetFilteringConfiguration("adblock");
configuration->AddFilterList(example_filter_list);
configuration->GetFilterLists(); // ["http://example.com/example_list.txt", ...]

Enable/Disable ad filtering on a specific domain

Use addAllowedDomain to stop filtering ads on a specific domain, and removeAllowedDomain to resume.

getAllowedDomains returns a list of allowed domains.

import org.chromium.components.adblock.FilteringConfiguration;

// Creates "adblock" configuration if does not exist yet, returns a valid handle.
FilteringConfiguration adblockConfiguration = FilteringConfiguration.createConfiguration("adblock", browserContextHandle);

adblockConfiguration.addAllowedDomain("example.com");
adblockConfiguration.getAllowedDomains();  // ["example.com"]
adblockConfiguration.removeAllowedDomain("example.com");
adblockConfiguration.getAllowedDomains();  // []

chrome.eyeoFilteringPrivate.addAllowedDomain("adblock", "example.com");
chrome.eyeoFilteringPrivate.getAllowedDomains("adblock");  // ["example.com"]
chrome.eyeoFilteringPrivate.removeAllowedDomain("adblock", "example.com");
chrome.eyeoFilteringPrivate.getAllowedDomains("adblock");  // []

#include "components/adblock/content/browser/factories/subscription_service_factory.h"
#include "components/adblock/core/subscription/subscription_config.h"
#include "components/adblock/core/subscription/subscription_service.h"
#include "components/adblock/core/configuration/filtering_configuration.h"

const GURL example_filter_list("http://example.com/example_list.txt");
auto* subscription_service =
    adblock::SubscriptionServiceFactory::GetForBrowserContext(context);
auto configuration = subscription_service->GetFilteringConfiguration("adblock");
configuration->AddAllowedDomain("example.com");
configuration->GetAllowedDomains(); // ["example.com"]
configuration->RemoveAllowedDomain("example.com");
configuration->GetAllowedDomains(); // []

Note: Pass a domain ('example.com') as an argument, not a URL ('http://www.example.com/page.html').

Add/Remove custom filters

Use addCustomFilter to add and removeCustomFilter to remove a single filter.

To get the list of custom filters added use getCustomFilters.

The following code snippet installs a new filter:

import org.chromium.components.adblock.FilteringConfiguration;

// Creates "adblock" configuration if does not exist yet, returns a valid handle.
FilteringConfiguration adblockConfiguration = FilteringConfiguration.createConfiguration("adblock", browserContextHandle);

adblockConfiguration.addCustomFilter("example_domain##.example_selector");
adblockConfiguration.getCustomFilters();  // ["example_domain##.example_selector"]
adblockConfiguration.removeCustomFilter("example_domain##.example_selector");
adblockConfiguration.getCustomFilters();  // []

chrome.eyeoFilteringPrivate.addCustomFilter("adblock", "example_domain##.example_selector");
chrome.eyeoFilteringPrivate.getCustomFilters("adblock");  // ["example_domain##.example_selector"]
chrome.eyeoFilteringPrivate.removeCustomFilter("adblock", "example_domain##.example_selector");
chrome.eyeoFilteringPrivate.getCustomFilters("adblock");  // []

#include "components/adblock/content/browser/factories/subscription_service_factory.h"
#include "components/adblock/core/subscription/subscription_config.h"
#include "components/adblock/core/subscription/subscription_service.h"
#include "components/adblock/core/configuration/filtering_configuration.h"

const GURL example_filter_list("http://example.com/example_list.txt");
auto* subscription_service =
    adblock::SubscriptionServiceFactory::GetForBrowserContext(context);
auto configuration = subscription_service->GetFilteringConfiguration("adblock");
configuration->AddCustomFilter("example_domain##.example_selector");
configuration->GetCustomFilters(); // ["example_domain##.example_selector"]
configuration->RemoveCustomFilter("example_domain##.example_selector");
configuration->GetCustomFilters(); // []

Subscribe for resource blocked or allowed events

There is an option to receive events when some resource is blocked or allowed. Typically, this is needed to implement a counter in the UI. Please do not subscribe if you are not going to consume these notifications, as it has a small performance penalty.

import org.chromium.components.adblock.ResourceClassificationNotifier;

ResourceClassificationNotifier.getInstance().addOnAdBlockedObserver(new ResourceClassificationNotifier.ResourceFilteringObserver{
    @Override
    public void onRequestAllowed(ResourceFilteringCounters.ResourceInfo info) {
        // ...
    }
    @Override
    public void onRequestBlocked(ResourceFilteringCounters.ResourceInfo info) {
        // ...
    }
    @Override
    public void onPageAllowed(ResourceFilteringCounters.ResourceInfo info) {
        // ...
    }
    @Override
    public void onPopupAllowed(ResourceFilteringCounters.ResourceInfo info) {
        // ...
    }
    @Override
    public void onPopupBlocked(ResourceFilteringCounters.ResourceInfo info) {
        // ...
    }
});

chrome.eyeoFilteringPrivate.onRequestAllowed.addListener(function(info) {
    // ...
});
chrome.eyeoFilteringPrivate.onRequestBlocked.addListener(function(info) {
    // ...
});

#include "components/adblock/content/browser/factories/resource_classification_runner_factory.h"
#include "components/adblock/content/browser/resource_classification_runner.h"

class MyObserver : public adblock::ResourceClassificationRunner::Observer {
 public:
  void OnRequestMatched(const GURL& url,
                        adblock::FilterMatchResult match_result,
                        const std::vector<GURL>& parent_frame_urls,
                        adblock::ContentType content_type,
                        content::RenderFrameHost* render_frame_host,
                        const GURL& subscription,
                        const std::string& configuration_name) override {
    // ...
  }
  void OnPageAllowed(const GURL& url,
                     content::RenderFrameHost* render_frame_host,
                     const GURL& subscription,
                     const std::string& configuration_name) override {
    // ...
  }
  void OnPopupMatched(const GURL& url,
                      adblock::FilterMatchResult match_result,
                      const GURL& opener_url,
                      content::RenderFrameHost* render_frame_host,
                      const GURL& subscription,
                      const std::string& configuration_name) override {
    // ...
  }
};

MyObserver observer;

adblock::ResourceClassificationRunnerFactory::GetForBrowserContext(context)
    ->AddObserver(&observer);

The filtering engine is flexible

In the previous section, you've learned how to configure ad-filtering. But the underlying filtering engine is more capable.

It could, for example:

• block intrusive trackers,

• block age-sensitive material,

• filter geo-limited content,

• remove arbitrary unwanted content from the user's browsing experience

As long as you can express the filtering demands via the filtering language, you can probably use the Browser Ad-Filtering Solution to implement the behavior.

This section describes how to introduce new aspects of content filtering independently of ad-filtering.

Filtering configuration

A filtering configuration is a named, independent set of filtering options that are applied to network requests and website content.

Each filtering configuration has the following parameters:

These settings are stored persistently in Preferences.

The default, ad-filtering configuration

These parameters are very similar to the ones you encountered in the previous section. In fact, the ad-filtering settings are implemented as a filtering configuration - with the name adblock. It is created by default in the Solution.

Multiple filtering configurations

Filtering configurations are independent, meaning each can be enabled, disabled or reconfigured separately from the others. Each maintains its own list of installed filter lists, custom filters and allowed domains.

Interactions between filtering configurations

What happens when one filtering configuration classifies a resource as blocked while another classifies it as allowed?

The blocking decision always wins.

This is a design decision. An example to rationalize it:

• Perhaps filtering configuration adblock is an ad-filtering configuration and has a blanket rule to block every URL with an ad substring.

• However, the user has allowlisted example.com by adding it to adblock's allowed domains, therefore filtering configuration adblock classifies https://example.com/ad.png as an allowed resource.

• Filtering configuration sfw is an age-restricting configuration and it has a blocking filter for https://example.com/ad.png - not because it's an ad, but because it contains inappropriate content.

• The blocking decision from filtering configuration sfw "wins", the inappropriate ad is blocked.

Creating a filtering configuration

Each filtering configuration must be installed on each browser start.

The configuration's settings are persistent and will be loaded upon installation.

import org.chromium.components.adblock.FilteringConfiguration;

// Creates "adblock" configuration if does not exist yet, returns a valid handle.
FilteringConfiguration myConfiguration = FilteringConfiguration.createConfiguration("my_configuration", browserContextHandle);

// No-op if configuration already exists.
chrome.eyeoFilteringPrivate.createConfiguration("my_configuration")

#include "chrome/browser/adblock/subscription_service_factory.h"
#include "components/adblock/core/configuration/persistent_filtering_configuration.h"
#include "components/adblock/core/subscription/subscription_service.h"

auto my_configuration =
    std::make_unique<PersistentFilteringConfiguration>(profile()->GetPrefs(),
                                                       "my_configuration");
SubscriptionServiceFactory::GetForBrowserContext(profile())
    ->InstallFilteringConfiguration(std::move(configuration));

Getting installed filtering configurations

List<FilteringConfiguration> configs = FilteringConfiguration.getConfigurations();

// Without promises:
chrome.eyeoFilteringPrivate.getConfigurations(function(configs) {
  // configs = ['adblock', 'my_configuration']
  // 'adblock' installed by default.
  // 'my_configuration' installed by previous example.
});

// With promises:
await chrome.eyeoFilteringPrivate.getConfigurations().then(
    configs => {
        // configs = ['adblock', 'my_configuration']
    });

#include "chrome/browser/adblock/subscription_service_factory.h"
#include "components/adblock/core/configuration/filtering_configuration.h"
#include "components/adblock/core/subscription/subscription_service.h"

SubscriptionService* subscription_service =
    SubscriptionServiceFactory::GetForBrowserContext(profile());
const std::vector<FilteringConfiguration*> configurations =
    subscription_service->GetInstalledFilteringConfigurations();

// "adblock" installed by default.
// "my_configuration" installed by previous example.
configurations[0]->GetName();  // "adblock"
configurations[1]->GetName();  // "my_configuration"

Removing a filtering configuration

You can remove filtering configuration if it is not needed. This means all associated preferences data will be removed.

FilteringConfiguration.removeConfiguration("my_configuration");

chrome.eyeoFilteringPrivate.removeConfiguration("my_configuration")

#include "chrome/browser/adblock/subscription_service_factory.h"
#include "components/adblock/core/subscription/subscription_service.h"

SubscriptionServiceFactory::GetForBrowserContext(profile())
    ->UninstallFilteringConfiguration("my_configuration");

Enabling and disabling a configuration

By default, each configuration starts as enabled. If you disable it, the state persists and the configuration starts as disabled next time the browser runs.

The following example disables my_configuraion:

import org.chromium.components.adblock.FilteringConfiguration;

// myConfiguration created by previous example.

myConfiguration.isEnabled();  // true
myConfiguration.setEnabled(false);
myConfiguration.isEnabled();  // false

// "my_configuration" created by previous example.

// Without promises:
chrome.eyeoFilteringPrivate.isEnabled('my_configuration', function(enabled) {
  // enabled == true
});
// With promises:
chrome.eyeoFilteringPrivate.setEnabled('my_configuration', false)
    .then(
        () => {chrome.eyeoFilteringPrivate.isEnabled('my_configuration')
                   .then(
                       enabled => {
                           // enabled == false;
                       })});

#include "components/adblock/core/configuration/filtering_configuration.h"

FilteringConfiguration* my_configuration =
    ...;                        // Created or retrieved by previous examples.
my_configuration->IsEnabled();  // true
my_configuration->SetEnabled(false);
my_configuration->IsEnabled();  // false

Add/Remove filter lists

Filtering configurations allow dynamic management of filter lists identified by their URLs. To see implementation details for managing filter lists, refer to the Configure SDK Settings guide.

Observe filter list installation progress

When you add a filter list to a configuration, the configuration is updated instantly but the download and installation may take several seconds. If you want to be notified when an installation completes, you can register an observer.

import org.chromium.components.adblock.FilteringConfiguration;

public class MySubscriptionUpdateObserver
        implements FilteringConfiguration.SubscriptionUpdateObserver {
    @Override
    public void onSubscriptionDownloaded(final URL url) {
        // url == "http://filters.com/list.txt"
    }
}

MySubscriptionUpdateObserver observer = new MySubscriptionUpdateObserver();

// myConfiguration created by previous example.
myConfiguration.addSubscriptionUpdateObserver(observer);

URL filterList = new URL("http://filters.com/list.txt");
myConfiguration.addFilterList(filterList);

// Wait until download completes
// observer.onSubscriptionDownloaded("http://filters.com/list.txt") is called

// "my_configuration" created by previous example.
const filterList = 'http://filters.com/list.txt';

chrome.eyeoFilteringPrivate.onSubscriptionUpdated.addListener(function(url) {
  // url == 'http://filters.com/list.txt'
});

await chrome.eyeoFilteringPrivate.subscribeToFilterList(
    'my_configuration', filterList);

// Wait until download completes
// the listener is called

#include "components/adblock/core/configuration/filtering_configuration.h"
#include "components/adblock/core/subscription/subscription_service.h"

class Observer : public SubscriptionService::SubscriptionObserver {
 public:
  void OnSubscriptionInstalled(const GURL& subscription_url) override {
    // subscription_url == "http://filters.com/list.txt"
  }
};

FilteringConfiguration* my_configuration =
    ...;  // Created or retrieved by previous examples.

Observer observer;
SubscriptionServiceFactory::GetForBrowserContext(profile())->AddObserver(
    &observer);

const GURL filter_list("http://filters.com/list.txt");
my_configuration->AddFilterList(filter_list);

// Wait until download completes
// Observer::OnSubscriptionInstalled is called

The Solution will also trigger this notification every time it successfully installs an update to the filter list, for example as a result of a scheduled, periodic update check.

Exempt a domain from filtering

To effectively disable all content filtering on a specific domain, add an allowed domain.

Remember, this allows all content on the domain, not from the domain. Adding trusted.org will let ads appear while the user is browsing https://www.trusted.org. But when the user is browsing https://example.com which attempts to load https://www.trusted.org/ads.js, the filtering still applies and the script might be blocked.

If you need to allow all content from a domain, see Add/Remove custom filters.

import org.chromium.components.adblock.FilteringConfiguration;

String allowedDomain = "trusted.org";

// myConfiguration created by previous example.
myConfiguration.addAllowedDomain(allowedDomain);

List<String> allowedDomains = myConfiguration.getAllowedDomains();
// allowedDomains = ["trusted.org"]

// The Solution will not filter any content on trusted.org.

// "my_configuration" created by previous example.
const allowed_domain = 'trusted.org';

chrome.eyeoFilteringPrivate.addAllowedDomain(
    'my_configuration', allowed_domain);
chrome.eyeoFilteringPrivate.getAllowedDomains(
    'my_configuration', function(domains) {
      // domains == ['trusted.org']
    });

// The Solution will not filter any content on trusted.org.

#include "components/adblock/core/configuration/filtering_configuration.h"

FilteringConfiguration* my_configuration =
    ...;  // Created or retrieved by previous examples.

const std::string allowed_domain = "trusted.org";
my_configuration->AddAllowedDomain(allowed_domain);

std::vector<std::string> allowed_domains =
    my_configuration->GetAllowedDomains();
// allowed_domains = ["trusted.org"]

// The Solution will not filter any content on trusted.org.

Add/Remove custom filters

Custom filters allow fine-tuning of filtering behavior by adding individual filters. For details on adding or removing custom filters, refer to the Configure SDK Settings guide.

Subscribe to configuration change events

If you'd like to be notified when some piece of code changes a filtering configuration, you may register an observer:

import org.chromium.components.adblock.FilteringConfiguration;

public class MyConfigurationChangeObserver
        implements FilteringConfiguration.ConfigurationChangeObserver {
    @Override
    public void onEnabledStateChanged() {
        // runs when someone calls setEnabled() to set a new state
    }
    @Override
    public void onFilterListsChanged() {
        // runs when someone adds or removes filter lists
    }
    @Override
    public void onAllowedDomainsChanged() {
        // runs when someone adds or removes allowed domains
    }
    @Override
    public void onCustomFiltersChanged() {
        // runs when someone adds or removes custom filters
    }
}

MyConfigurationChangeObserver observer = new MyConfigurationChangeObserver();

// myConfiguration created by previous example.
myConfiguration.addObserver(observer);

URL filterList = new URL("http://filters.com/list.txt");
myConfiguration.addFilterList(filterList);

// observer.onFilterListsChanged() is called

// "my_configuration" created by previous example.
chrome.eyeoFilteringPrivate.onEnabledStateChanged.addListener(
    'my_configuration', function() {
      // runs when someone calls setEnabled() to set a new state
    });

chrome.eyeoFilteringPrivate.onFilterListsChanged.addListener(
    'my_configuration', function() {
      // runs when someone adds or removes filter lists
    });

chrome.eyeoFilteringPrivate.onAllowedDomainsChanged.addListener(
    'my_configuration', function() {
      // runs when someone adds or removes allowed domains
    });

chrome.eyeoFilteringPrivate.onCustomFiltersChanged.addListener(
    'my_configuration', function() {
      // runs when someone adds or removes custom filters
    });


const filterList = 'http://filters.com/list.txt';
await chrome.eyeoFilteringPrivate.subscribeToFilterList(
    'my_configuration', filterList);

// the second listener is called

#include "components/adblock/core/configuration/filtering_configuration.h"

class Observer : public FilteringConfiguration::Observer {
 public:
  void OnEnabledStateChanged(FilteringConfiguration* config) override {
    // runs when someone calls SetEnabled() to set a new state
  }
  void OnFilterListsChanged(FilteringConfiguration* config) override {
    // runs when someone adds or removes filter lists
  }
  void OnAllowedDomainsChanged(FilteringConfiguration* config) override {
    // runs when someone adds or removes allowed domains
  }
  void OnCustomFiltersChanged(FilteringConfiguration* config) override {
    // runs when someone adds or removes custom filters
  }
};

FilteringConfiguration* my_configuration =
    ...;  // Created or retrieved by previous examples.

Observer observer;
my_configuration->AddObserver(&observer);

const GURL filter_list("http://filters.com/list.txt");
my_configuration->AddFilterList(filter_list);

// Observer::OnFilterListsChanged is called

Observe resource classification

If you wish to be notified when network resources are blocked or allowed, register as an observer.

You don't observe a single filtering configuration because all installed filtering configurations take part in classification - see Interactions between filtering configurations.

import org.chromium.components.adblock.ResourceClassificationNotifier;

public class MyClassificationObserver implements ResourceClassificationNotifier.AdBlockedObserver {
    @Override
    public void onAdAllowed(AdblockCounters.ResourceInfo info) {
        // Runs when a resource is specifically allowed by an
        // allowing filter from a filtering configuration
        // and isn't blocked by other filtering configurations.
    }
    @Override
    public void onAdBlocked(AdblockCounters.ResourceInfo info) {
        // Runs when a resource is blocked by a blocking filter
        // from at least one enabled filtering configuration.
    }
    @Override
    public void onPageAllowed(AdblockCounters.ResourceInfo info) {
        // Runs when every enabled filtering configuration exempts
        // this domain from filtering via allowed domains.
    }
    @Override
    public void onPopupAllowed(AdblockCounters.ResourceInfo info) {
        // Runs when a popup window is specifically allowed by an
        // allowing filter from a filtering configuration
        // and isn't blocked by other filtering configurations.
    }
    @Override
    public void onPopupBlocked(AdblockCounters.ResourceInfo info) {
        // Runs when a popup window is blocked by a blocking filter
        // from at least one enabled filtering configuration.
    }
}

MyClassificationObserver observer = new MyClassificationObserver();

ResourceClassificationNotifier.getInstance().addOnAdBlockedObserver(observer);

chrome.eyeoFilteringPrivate.onRequestAllowed.addListener(function(info) {
  // Runs when a resource is specifically allowed by an
  // allowing filter from a filtering configuration
  // and isn't blocked by other filtering configurations.
});
chrome.eyeoFilteringPrivate.onRequestBlocked.addListener(function(info) {
  // Runs when a resource is blocked by a blocking filter
  // from at least one enabled filtering configuration.
});
chrome.eyeoFilteringPrivate.onPageAllowed.addListener(function(info) {
  // Runs when every enabled filtering configuration exempts
  // this domain from filtering via allowed domains.
});
chrome.eyeoFilteringPrivate.onPopupAllowed.addListener(function(info) {
  // Runs when a popup window is specifically allowed by an
  // allowing filter from a filtering configuration
  // and isn't blocked by other filtering configurations.
});
chrome.eyeoFilteringPrivate.onPopupBlocked.addListener(function(info) {
  // Runs when a popup window is blocked by a blocking filter
  // from at least one enabled filtering configuration.
});

#include "chrome/browser/adblock/resource_classification_runner_factory.h"
#include "components/adblock/content/browser/resource_classification_runner.h"

class MyClassificationObserver : public ResourceClassificationRunner::Observer {
 public:
  void void OnAdMatched(const GURL& url,
                        FilterMatchResult match_result,
                        const std::vector<GURL>& parent_frame_urls,
                        ContentType content_type,
                        content::RenderFrameHost* render_frame_host,
                        const GURL& subscription) override {
    if (match_result == FilterMatchResult::kAllowRule) {
      // Runs when a resource is specifically allowed by an
      // allowing filter from a filtering configuration
      // and isn't blocked by other filtering configurations.
    }
    if (match_result == FilterMatchResult::kBlockRule) {
      // Runs when a resource is blocked by a blocking filter
      // from at least one enabled filtering configuration.
    }
  }
  void void OnPageAllowed(const GURL& url,
                          content::RenderFrameHost* render_frame_host,
                          const GURL& subscription) override {
    // Runs when every enabled filtering configuration exempts
    // this domain from filtering via allowed domains.
  }
  void void OnPopupMatched(const GURL& url,
                           FilterMatchResult match_result,
                           const GURL& opener_url,
                           content::RenderFrameHost* render_frame_host,
                           const GURL& subscription) override {
    if (match_result == FilterMatchResult::kAllowRule) {
      // Runs when a popup window is specifically allowed by an
      // allowing filter from a filtering configuration
      // and isn't blocked by other filtering configurations.
    }
    if (match_result == FilterMatchResult::kBlockRule) {
      // Runs when a popup window is blocked by a blocking filter
      // from at least one enabled filtering configuration.
    }
  }
};

MyClassificationObserver observer;
ResourceClassificationRunnerFactory::GetForBrowserContext(profile())
    ->AddObserver(&observer);

Integrating the eyeo Browser Ad-Filtering Solution provides a browsing experience that benefits users. On this page, you'll learn about the solution's main features and services.

About the eyeo Browser Ad-Filtering Solution

Advertisements frustrate users, as they take up valuable screen space and can slow page load time. By integrating a proven, widely used ad-filtering solution directly into the browser, your users will no longer need to install and configure ad-filtering extensions manually.

With the eyeo Browser Ad-Filtering Solution, ad filtering is automatically enabled, giving users an immediate improvement in browsing speed and aesthetics.

The eyeo Browser Ad-Filtering Solution enables partners with Chromium-based browsers to introduce ad filtering and related features to their browsers across multiple platforms. As a result, Chromium-enforced limitations on desktop extensions (like Manifest V3) no longer apply.

Features

The feature-rich solution works alongside other services offered to all partners. In this section, you'll learn about the benefits and capabilities of integrating an ad-filtering solution into a browser.

Basic ad filtering

Ad filtering is the core feature of the solution, which uses two approaches to remove ads:

• Network blocking, which blocks ads from being requested and downloaded. This approach saves data and helps web pages loader faster.

• Element hiding, which hides ads. Element hiding also hides white spaces left from hidden ads, improving the user experience even after removing ads.

Partners can access an API to introduce an on/off switch for ad filtering features in the UI.

Anti-circumvention and snippets

An advanced feature of the solution, anti-circumvention, depends on JavaScript snippets that execute within the context of a website to stop publishers from circumventing ad blockers.

Snippets are built into the browser as a library, rather then being downloaded from the Internet, to avoid running untrusted code. Partners can update the snippets library on their own as part of their release pipeline. Snippets are enabled by default but can be disabled if needed.

For more on snippets, view Snippets Overview.

Acceptable Ads

Acceptable Ads gives users the option to support content creators and contribute to a fair online ecosystem. Users who enable Acceptable Ads see non-intrusive advertising that respects the online user experience. In so doing, they help reward content creators for their free content.

Keep the following in mind when configuring Acceptable Ads for your project:

• This feature is powered by exception rules, a proprietary eyeo filter list. eyeo recommends all partners enable this filter list by default.

• Inform users about Acceptable Ads during onboarding so that they can opt out if they wish.

• Make sure that Acceptable Ads has a dedicated on/off switch in the browser settings.

To turn this feature off, you'll need to disable (that is, unsubscribe from) the exception rules filter list through the Subscription API.

Filter lists

Filter lists power ad filtering. The Browser Ad-filtering Solution downloads the following filter lists by default:

• EasyList, the standard for filtering ad content online, is the default filter list enabled in the ad filtering solution.

• Language-specific versions of EasyList:

  • During the first run a list is automatically selected and downloaded based on the user's device language.

  • Later "temporary" lists are downloaded based on geolocation and will be deleted if the geolocation has changed and the list remains unrecommended for a period of 14 days.

• A proprietary list to enable Acceptable Ads.

• Anti-circumvention list to stop publishers from circumventing ad blockers.

Adding and removing filter lists

Using the Subscription API, browser partners can add and remove custom filter lists during browser runtime. You can also expose this option to your end users.

For more information, view adding and removing filter lists.

Automatic filter list updates

The Browser Ad-Filtering Solution updates all installed filter lists automatically, according to their expiration time.

Browser partners can add an expiration value to their filter lists by setting special headers in the filter list content.

Reporting ad filtering statistics

With this feature enabled, you can count how many ad requests were blocked or allowed. The Browser Ad-Filtering Solution sends a notification for each blocked request, which the browser can then count and display to users in their UI.

Depending on your project, you can also use a global counter to engage users who reach a specific milestone of blocked ads.

For more information, view receiving notifications about blocked or allowed network requests.

Privacy-preserving user counting

User counting helps browser partners and eyeo count the following:

• How many users are using the eyeo Browser Ad-Filtering Solution

• How many users support content creators via the Acceptable Ads program

eyeo counts users in a way that preserves privacy. The Solution sends regular, anonymous ping requests to eyeo servers. These requests let eyeo apply formulas and identify unique, active users without knowing any personal information about the user.

For more information, view user counting.

Adding and removing domains to and from allowlists

Browser partners can add or remove domains to and from a local allowlist during runtime.

With this feature, your end users can disable ad filtering for specific websites. This lets users support certain websites, or turn ad filtering off for websites with ad blocker walls or websites that break when ads are blocked.

By providing this feature to users, you give them the option to keep ad filtering enabled for all other websites, resulting in a low opt-out rate for ad filtering.

You can also let some users manage their local allowlist. Adding and removing domains to the local allowlist is done through the custom allowlist API.

Adding and removing custom filters to and from local block lists

Partners or users can add and remove individual filters that follow the Adblock Plus syntax.

eyeo recommends to reserve this capability for power users or developers.

Multi-platform support

Partners only need to integrate the ad-filtering solution into their Chromium codebase once. The Solution supports the following platforms:

• Windows

• MacOS

• Linux

• Android

In addition to platform dimension, the following targets are supported:

• Chromium app

• WebView (Android system component to display HTML)

• Monochrome (combined app and WebView)

• Content Shell (minimal browser code base, can be used for Smart TV platforms)

Example UI

Examples can help you implement a user interface to control ad filtering.

Next up

Now that you're familiar with the features of the eyeo Browser Ad-Filtering Solution, jump right in and follow the Quickstart guide to begin building.

This page contains the eyeo Browser Ad-Filtering Solution architectural decision records (ADRs), which summarize the most important software design choices made during the development of the Solution.

These decisions address functional and non-functional requirements that eyeo finds architecturally significant.

Implementing ad-filtering from scratch

Chromium contains some ad-filtering functionality in the form of the subresource filter. The Chromium subresource filter, however, doesn't support CSS element-hiding, JavaScript element hiding emulation, or snippets.

Patching these limitations requires significant tradeoffs, some of which include the following:

• More conflicts to solve after Chromium updates

• Less flexibility to introduce new features and optimizations

• Irreconcilably different objectives between eyeo and Chrome's authors

Chromium authors control subresource filter development. As a result, they may have different (ad-related) business objectives that could take subresource filtering in a direction that doesn't fit with eyeo's vision.

For these reasons, the eyeo team chose not to build on top of the subresource filter, opting for an implementation with ad-filtering capabilities built from scratch.

Using full or minified filter lists

In previous implementations of our ad-filtering core, eyeo used minified filter lists to reduce memory consumption for mobile users. More recent implementations achieved this reduction by adopting FlatButters as a filter list file format and by moving from V8 to a native implementation.

eyeo now uses full filter lists, which allow for more filter rules. This improves user experience and blocks a greater number of intrusive ads. More Acceptable Ads are also allowed, which increases for publishers who adhere to the Acceptable Ads standard.

Storing filter lists in FlatBuffer format

Filter lists aren't consumed in plain text format right after download. Instead, they are converted from plain text into the FlatBuffers format, which offers the following advantages:

• Reduced memory consumption, down to approximately 15 MB

• Reduced startup time, from seconds down to milliseconds

• No negative impact on page load time, except for sites with long URLs

• Facilities for multi-threading and synchronous popup blocking

• No required deserialization, because FlatBuffers is already in a binary format

• FlatBuffers can be memory-mapped and accessed as memory directly from disk.

• Accessing data in a flatbuffer is as fast as dereferencing pointers to memory.

A FlatBuffers file contains only one filter list, for the following reasons:

• Filter lists updated at different times can be downloaded independently.

• Less time consumed in conversion than if all selected filter lists are combined in one file

• For long-term distribution of FlatBuffers files, having to provide a file containing all selected filter lists would cause excessive combinations.

Moving user counting to a dedicated service

Coupling the user counting service with filter lists downloads gives eyeo insight into Solution usage across Chromium, OS, and platform versions.

As a dedicated service, it also allows eyeo to monitor Acceptable Ads opt-out rate, while enabling partners to serve and monetize filter lists from their own servers.

For more information, view the user counting documentation.

What are snippets?

Snippets are pieces of JavaScript code, injected by the Ad-Filtering Solution, that execute within the context of a website and combat advanced ads that circumvent ordinary blocking.

How snippets work

A snippet is typically a JavaScript function. It may optionally take arguments.

Snippets are stored in a snippet library and selected for execution based on the content of a filter list. The filter list also specifies any arguments passed to snippets on a given website.

Multiple snippets with various arguments may be executed on a single website. For more on snippet functionality, view the Snippets Overview.

Requirements for using snippets

In order to execute snippets on websites, the following are required:

• the snippet library of a sufficiently recent version must be built into the browser

• the Anti-CV filter list must be subscribed

Verify the Anti-CV filter subscription

The Anti-CV filter list is subscribed by default.

If it isn't in your configuration, you can subscribe to it the same way as you subscribe to any other filter list, through FilteringConfiguration or any of the platform-specific APIs.

Keeping the snippets library up to date

The version of the snippets library built into the Browser Ad-Filtering Solution is defined in the DEPS file.

The snippet library may sometimes be updated separately from the remainder of the Solution by changing the tagged version.

Some changes to the snippets library may require alignment of the Solution. Consult the following compatibility matrix to see if a Solution version is compatible with a snippet library version:

Update the snippets library

1. Set the new desired version in the DEPS file.

2. Run gclient sync to pull the new version of the library to your local repository.

3. Rebuild the browser (ninja -C out/...)

Remember to consult the compatibility matrix to avoid mismatches between the snippets library content and the Solution's expectations.

Anatomy of a filter list

A filter list is a text file that contains, in this order:

• An [Adblock Plus] header line, to identify itself as following the Adblock Plus syntax

• A collection of optional special comments, one per line

• A collection of filters or normal comments, one per line

The header line

The header line must be the first line of the file.

It should say [Adblock Plus]. It might also contain a version number, for example [Adblock Plus 2.0], but the version is ignored by the eyeo Browser Ad-Filtering Solution.

Special comments

Special comments are a single block of consecutive comments that start from an exclamation mark (!) and follow a key:value semantic.

The Browser Ad-Filtering Solution interprets the following special comments:

There are other special comments that may be interpreted by other eyeo Ad-Filtering Solution, for example:

• Homepage

• License

• Checksum

Parsing of the special comments block stops after encountering a line that isn't a ! key : value. All further comments are treated as not special and ignored.

Filters and normal comments

This is probably the most important block of a filter list - the actual filters.

You can write one filter rule per line, as described in Adblock Plus syntax.

Comment lines start from an exclamation mark (!) and are skipped during parsing.

The filters are parsed until the end of file.

Examples

[Adblock Plus]
! Version: 202306020710
! Title: My list
! Expires: 2 days

! Allow loading all resources on mysite.net
@@||mysite.net^$document,domain=mysite.net

! Unhide banner element on example.com
example.com#@#.banner

For a big working example, consider https://easylist-downloads.adblockplus.org/easylist.txt

For a more minimal example, compare the filter list used for test pages: https://abptestpages.org/en/abp-testcase-subscription.txt

Hosting

For safety, the Browser Ad-Filtering Solution will only download filter lists from HTTPS servers, HTTP is not allowed.

An exception is localhost - the Solution will download a filter list from http://localhost/any/path.txt to facilitate local development and testing.

Updating

The eyeo Browser Ad-Filtering Solution will periodically download filter list updates. It will respect the interval specified in ! Expires or revert to the default period of 5 days.

The update check interval is clamped between 1 hour and 14 days.

If a new version of the filter list fails to download or parse correctly, the SDK will retain the old version and retry the update in an hour.

Limitations

Snippet filters and header filters will be ignored. They are only allowed on ABP Filters.

You can still add snippet and header filters as individual custom filters, as explained here.

A sitekey is a special identifier that a server may attach to a resource. Sitekeys enable additional filters that determine whether to block or allow the resource.

Sitekeys are typically used to allowlist resources coming from a particular server that may serve many different domains.

How sitekeys work

Suppose a user visits two sites: https://catstoys.com and https://dogstoys.com. A single sitekey server handles both sites.

The network responses headers for both sites will contain x-adblock-key. The sitekey is encoded within that header.

How sitekeys get computed on the server side

The sitekey server gets the following information:

• The path with query of the URL requested by the client, for example, /page.html?param-value

• The host that the client contacted, for example, catstoys.com

• The client's user agent, like Mozilla/5.0 (X11; Linux x86_64), Chrome/92.0.4515.107 Safari/537.36, and so on.

These three strings are connected into a single line of text, separated by null (\0) symbols, as in the following example:

/page.html?param-value\0catstoys.com\0Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.107 Safari/537.36

This becomes the input to the encryption algorithm. This input is different for every URL that the browser requests.

The sitekey server holds a secret private key that is only generated once and never changes. Using this private key, the sitekey server encrypts the input text and generates a unique signature, or a hash. The hash would look something like this:

nLH8Vbc1rzmy0Q+Xg+bvm43IEO42h8rq5D9C0WCn/Y3ykgAoV4npzm7eMlqBSwZBLA/0DuuVsfTJT9MOVaurcA==

The sitekey server then returns the following:

• The signature, that is, is the encrypted output. This signature changes for every request.

• A sitekey, which is the public key to the server's internal, secret private key. The public key never changes.

The sitekey and signature are glued together with the underscore (_) as the separator, as in sitekey_signature. In the example scenario, the string would look like this:

MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANnylWw2vLY4hUn9w06zQKbhKBfvjFUCsdFlb6TdQhxb9RXWXuI4t31c+o8fYOv/s8q1LGPga3DE1L/tHU4LENMCAwEAAQ_nLH8Vbc1rzmy0Q+Xg+bvm43IEO42h8rq5D9C0WCn/Y3ykgAoV4npzm7eMlqBSwZBLA/0DuuVsfTJT9MOVaurcA=

The sitekey server then sends this string back to the browser in the x-adblock-keyheader.

The following diagram illustrates the process in its entirety:

Sitekey on the browser side

When the browser receives an HTTP response whose header contains x-adblock-key, it splits the string back into a separate sitekey and signature.

Because the browser knows the signature's three parameters (host, URL, UserAgent) and it has the public key, it can verify that the sender has the private key that corresponds to the sitekey that the browser received. In other words, the browser now knows that the server is a legitimate provider of the MFwwDQYJKoZIhvcNAQ... sitekey. This is because the server successfully encrypted inputs given by the browser in a way that's verifiable with that sitekey.

As a result, in the example, filter list allowing can now be applied on https://catstoys.com:

@@$document,sitekey=MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANnylWw2vLY4hUn9w06zQKbhKBfvjFUCsdFlb6TdQhxb9RXWXuI4t31c+o8fYOv/s8q1LGPga3DE1L/tHU4LENMCAwEAAQ

The following diagram illustrates the browser-side sitekey process:

Other resources

The filter used in the example on this page allows all resources to load and disables element hiding on any page with the specified sitekey. For more on filter language, see How to write filters.

Controlling ad filtering

Smoke testing

You may use these scenarios for quickly checking if ad-filtering works in your browser.

Scenario 1: Verify ads are blocked when ad filtering is ON and Acceptable Ads are OFF.

Scenario 2: Verify ads are blocked when ad filtering is ON and Acceptable Ads are ON.

Scenario 3: Verify ads are displayed when ad filtering is OFF.

Scenario 4: Verify allowlisting feature is working properly.

Testing on ABP testpages

ABP testpages are designed to test the ad-filtering code against various types of html elements in a controlled environment.

You need to enable More Blocking Options in order to run these tests.

Scenario 1 : Testing ABP testpages using custom filter lists

1. On the More blocking options screen, select the option of Custom Filter lists.

2. Enter the URL https://abptestpages.org/en/abp-testcase-subscription.txt in the text field and tap on the + icon.

4. Verify that you see green boxes, according to the descriptions of the test cases

Scenario 2 : Testing ABP testpages using custom filters

Alternatively, you can try adding custom filters rather than a custom filter list. This takes more effort but avoids unexpected interplay between filters defined for different test cases.

2. Copy the filter mentioned on the testpage corresponding to the scenario under test.

3. On the More blocking options screen, select the option of Custom Filters.

4. Paste the filter to the custom filter field and refresh the page under test.

5. Verify the test state matches the test case description, typically by showing a green box.

Filter lists

The eyeo Browser Ad-Filtering Solution needs filter lists in order to filter ads. Filter lists define which web resources should be blocked or hidden.

Default filter lists

On first run, the browser will attempt to download and install the following default filter lists:

It will take a couple of seconds to download and install these lists. The user is free to browse the web while this is happening, and the Solution falls back to built-in, preloaded variants of the default lists to provide some level of ad-filtering.

Downloading a filter list

The Solution downloads filter lists when:

• The browser starts for the first time and the default lists are installed

• The user selects a new list in the Language Filters menu

• The user adds a new custom filter list in the More Blocking Options menu

• A filter list expires and needs to be updated

Every filter list download is a GET request to the URL of the filter list with a set of extra GET parameters.

GET parameters

The Solution reports some information to eyeo via GET parameters added to the URL of each filter list.

This information is designed to preserve the user's anonymity and is used to:

• Count how many active users your browser attributes to the Acceptable Ads program

• Collect insights about what platforms eyeo should focus development efforts on

An example:

Periodic pings of Acceptable Ads filter list

To not lose track of users that have disabled Acceptable Ads, the SDK performs periodic pings .

A ping is a HEAD-type filter list download request, very similar to ordinary filter list download requests. Because it's a HEAD (and not GET) request, the server will not respond with filter list content and the browser will not download Acceptable Ads. However the server will be made aware of the user's existence.

Pings are sent every 24 hours while Acceptable Ads is disabled. They are visible as HEAD requests to:

Periodic updates

The browser updates the filter lists according to their expiry times - typically every 24 hours. In order to check if filter lists are updated upon expiration, do the following:

1. Let all the default filter lists download successfully.

2. On Android, force stop the application

3. Navigate to phone settings to advance the time by 25 hours.

4. Launch the application.

5. Filter lists download requests should be sent to the server with an increased downloadCount in request parameter.

6. If you have enabled VLOGs, you should see relevant logs in the system console, for example:

Verifying Eyeometery

To learn about Eyeometry refer to: user counting

1. The browser sends an Eyeometry ping every 12 hours. You should see it in browser logs if you have enabled VLOGs

1. If you see this line in the logs, your product wasn't built with a valid client id

1. If you see this line in the logs, your product wasn't built with a valid auth token

Logging

eyeo Chromium SDK uses the following levels of logging:

1. LOG(INFO/WARNING/ERROR) - these logs appear in all builds. These are emitted relatively rarely, to avoid clutter.

2. DLOG(INFO/WARNING/ERROR) - these logs appear in debug build only

3. VLOG(1/2/3/...) - these logs appear in all builds if vmodule flag is set

4. DVLOG(1/2/3/...) - same as VLOG but only in debug builds

The browser writes these logs to the system console, also known as standard output. Do not confuse this with the Developer Tools console within the Inspector window.

Steps to enable VLOG/DVLOG

Frame hierarchy is a term coined by eyeo. It represents a list of URLs where each element is embedded by the next one.

As an example, consider:

• A website's main page is https://example.com

• This website embeds an <iframe> with src = https://iframe.com/content.html

• This iframe contains an ad - an image with src = https://ads.com/ad.png

In this example, the image https://ads.com/ad.png has a frame hierarchy of:

• https://iframe.com/content.html

• https://example.com

By convention, the first element on the frame hierarchy is the immediate parent frame of the resource.

Purpose

The Browser Ad-Filtering Solution uses the frame hierarchy to establish whether allowing filters exist for parents of a resource.

Consider a blocking filter: ||ads.com/ad.png

This filter matches the URL of the ad image. When a website loads, a resource classifier will mark the image as an ad and stop the request from leaving the browser.

Now consider an allowing filter: @@||example.com^$document

This filter allows everything on the example.com domain, it overrides any blocking filters.

If both filters are present, the resource classifier should allow the ad from this particular frame hierarchy to load. But the same ad loaded from a different frame hierarchy might still be blocked.

The resource classifier searches not only for blocking and allowing filters that match https://ads.com/ad.png, but also for $document-type allowing filters that match https://iframe.com/content.html and https://example.com.

This is critical for correctly implementing the Acceptable Ads allowlists.

Implementation

The frame hierarchy can be assembled by recursively following content::RenderFrameHost::GetParent() results.

See: FrameHierarchyBuilder

The abort-on-iframe-property-write snippet patches a list of properties on the iframe's window object that aborts execution when the property is written.

You can use this snippet to prevent CV providers from overwriting properties inside an iframe.

Parameters

Filter examples

The following table lists examples that use the abort-on-iframe-property-write snippet:

Debugging

The following table contains messages you'll find useful during debugging:

This page lists the services and classes important to the eyeo Browser Ad-Filtering Solution, as well as the role each plays in the Solution's implementation.

Services

The Solution consists of the following main KeyedService services:

• FilteringConfiguration; allows the control of resource filtering settings

• SubscriptionService; maintains a state of available subscriptions and synchronizes it with persistent storage.

• ResourceClassificationRunner; decides whether to block or allow network requests.

• ElementHider; applies element hiding scripts and stylesheets on web pages.

• AdblockTelemetryService; reports anonymous usage statistics to eyeo.

• SitekeyStorage; extracts, validates, and stores SiteKeys from response headers.

Important Chromium classes

The following Chromium classes play an important role in the Solution's implementation:

• RenderFrameHost; allows finding the frame hierarchy and executes element hiding CSS and JavaScript.

• WebContentsObserver; receives page load events and injects element hiding; extended by AdblockWebContentsObserver.

• ChromeContentBrowserClient ; extended by AdblockChromeContentBrowserClient in order to set up an internal proxy for inspecting network requests.

Mapping to Chromium processes and threads

The Solution's logic executes primarily in the Browser process. The only exception is code under third_party/blink/renderer/core/exported/web_document.cc that injects element hiding stylesheets into the website - this runs in a Renderer process.

In the Browser process, code that might take a long time to execute runs asynchronously in the ThreadPool. Examples of such code:

• Classification of network requests

• Preparing element hiding selectors

• Conversion/serialization of filter lists

• Loading installed filter lists from disk

This snippet aborts the execution of an inline script when a property is either read or written.

Parameters

Filter examples

The following table lists examples that use the abort-current-inline-script filter:

Tradeoffs

Keep the following tradeoffs in mind when you use the abort-current-inline-scriptfilter:

• The snippet is executed after all of a page's inline scripts. As a result, you should only attach properties read inside of a callback, which can be executed after the script.

• You can only attach this snippet to global properties, or properties of the window object.

The abort-on-property-read snippet patches a property on the window object that aborts execution when the property is read. No error gets printed to the console.

You can use this snippet to abort the execution of inline scripts.

Parameters

Filter examples

The following table lists examples that use the abort-on-property-read snippet:

Debugging

The following table contains error messages you'll find useful during debugging:

Tradeoffs

Keep the following tradeoffs in mind when you use the abort-on-property-readsnippet:

• The snippet is executed after all a page's inline scripts. As a result, you should only attach properties read inside of a callback, which can be executed after the script.

• You can only attach this snippet to global properties, or properties of the window object.

On this page, you’ll learn what snippets are, why they’re useful, and ways you can include them in your development workflow.

Snippet basics

A snippet is a small piece of code intended to solve one problem:

function greetings() {
print("Hello there!");
}

eyeo uses snippets to fight ad-filtering circumvention. The following is the first snippet ever written for Adblock Plus:

function log(...args)
{
  console.log(...args);
}

This snippet prints its arguments to the developer tools console for the tab on which it’s executed.

The eyeo snippets library contains dozens of snippets to hide elements, find text, or block malicious code. Each snippet is exposed to the SDK that integrates thew snippets library. As a result, you can use filters to execute snippets for a given page.

Snippet filter structure

A snippet filter contains several parts:

• a domain

• the snippet marker

• a function name

• parameters

Consider the following example, which prints Hello, world! to the console:

example.com#$#log Hello ', world' 

In this snippet, example.com is the domain, #$# is the snippet market, and log is the function. The snippet takes two parameters, Hello and , world, both separated by white space.

How snippets work

The way a snippet works depends on if the snippet is injected or isolated.

Injected and isolated snippets

• Injected JavaScript snippets are inserted into a page and interrupt, modify, terminate, or otherwise change the behavior of other JavaScript functions

• An isolated snippet, on the other hand, has access to, reads, and manipulates the DOM.

Injected snippets are executed as inline scripts, whereas isolated snippets are executed as content scripts. For example, an injected snippet could interrupt the loading of JSON data that contains information about what ads should be shown.

Understanding the difference between injected and isolated scripts especially matters if you work in an isolated environment. For example, in browser extensions, all DOM-related operations can run more securely in a sandboxed extension context where they cannot be accessed by the page itself.

The following table compares injected and isolated snippets:

Types of snippets

In addition to classifying snippets by their functionality, you can also categorize snippets into the following types:

• Behavioral Snippets, which change a page’s normal execution behavior

• Conditional Hiding Snippets, which are responsible for hiding page content based on conditions like matching text, style, image hash

• Debugging Snippets, which you can use in debugging tasks

• Performance snippets, which reduce the performance overhead caused by other snippets

Refer to Behavioral Snippets, Conditional Hiding Snippets, and Performance Snippets for a comprehensive snippets list.

Working with snippets

When you use a snippet, you can efficiently interfere with ad display code and locate elements you want to hide in ways CSS or advanced selectors don't allow.

Snippets help you solve problems by working directly with the JavaScript environment, giving you a better ad-filtering solution and your users a better experience.

Invoking snippets

Invoking a snippet requires two steps:

1. Write a snippet filter.

2. Deploy the filter to the ABP anti-circumvention filter list.

You can test the snippet filter on Adblock Plus or Adblock by adding the filter to the My filter list field on the extension's settings page.

Combining snippets on a single website

Like Unix commands, multiple snippets may be combined in a filter to achieve a certain outcome.

The following filter, for example, blocks any inline script containing the string tracker while enabling all style sheets in the document:

example.com#$#abort-on-property-read Object.prototype.loadImage; hide-if-contains-visible-text 'Sponsored'; prevent-listener beforeunload ();

The small and targeted approach

Snippets need to be as efficient and fast as possible. When you add a snippet to a website, in particular, you only want to inject what's strictly necessary to suppress ads.

Injected scripts race against others already embedded in a site. As a result, you should aim for an unchanged user experience in terms of performance. Choosing a small, targeted snippets lets you maximize performance.

Where you can use snippets

eyeo supports snippets on the following platforms:

• Web Extensions on Manifest V2 (WebRequest and Background Pages)

• Web Extensions on Manifest V3 (Declarative NetRequest and Service Workers)

• Chromium based browsers (on Desktop and Android)

• Apple WebKit (on iOS, but potentially also on Mac OS)

FAQs

Are snippets designed for specific websites?

No. Snippets are generalized and reusable.

Do snippets work with Manifest V3?

Yes.

Can snippets take any type of arguments?

From an interface perspective, any argument to a snippet always is picked as a string.

A snippet may interpret a string in any way, though. For example, some snippets interpret arguments surrounded by forward slashes (/) as regular expressions.

Are snippets injected into frames?

They should be, especially if you're using an eyeo SDK.

Whether or not a snippet is injected into a web document has nothing to do with whether the document is loaded into the top-level frame or lower-level frames. Injection depends only on the domain of the document.

One exception to this is data URI frames, which have a unique origin by design.

Do snippets share any data?

Snippets run through the extension and share the same environment as each page that uses snippets. They share nothing, though, with other snippets injected in the browser.

Injected snippets share the same private scope. As a result, it's possible to declare and reuse variables and helpers that each snippet can access, whether in the browser or extension.

Where can I find the eyeo snippets library?

eyeo release the eyeo snippets library as a public npm module named @eyeo/snippets. You can reach the homepage from the eyeo GitLab snippets repository.

Other resources

• Snippet Filters Tutorial

The array-override overrides functions under Array.prototype to change their behaviour according to the given parameters. .

Parameters

Filter examples

Debugging

The following table contains messages you'll find useful during debugging:

The abort-on-iframe-property-read snippet patches a list of properties on the iframe's window object that aborts execution when the property is read.

You can use this snippet to prevent CV providers from using iframe native functions.

Parameters

Filter examples

The following table lists examples that use the abort-on-iframe-property-read snippet:

Debugging

The following table contains messages you'll find useful during debugging:

The cookie-remover removes certain cookies. You can parse document.cookie to set the expiration dates in the past for cookies that match targeted patterns.

Parameters

Filter examples

The following table lists examples that use the abort-on-iframe-property-write snippet:

Debugging

The following table contains messages you'll find useful during debugging:

The freeze-element freezes a DOM element, thereby preventing new nodes from being adding inside the element.

Parameters

Filter examples

The following table lists examples that use the abort-on-property-write snippet:

Debugging

During debugging, you'll see messages in your browser's Developer Console of the browser for every attempt to add a child node inside the frozen element.

As a result, the elements will be added to the frozen parent node, but they won't be visible as the CSS property display: none is added.

For all the DOM mutation properties apart from textContent, innerText and nodeValue, the structure of the message is the following (each line in the table is a line printed to the console):

For textContent, innerText and nodeValue, the structure of the message is the following (each line in the table is a line printed to the console):

Considerations

Keep the following in mind when you use the freeze-elementsnippet:

• Logging is more reliable than highlighting. Sometimes, some elements don't show as highlighted even if their style has the correct rules.

• Sometimes, when you hover on addedNode in the console, the added node is not highlighted on the page as it should be. That is because for some DOM mutation properties, like innerHTML, outerHTML or insertAdjacentHTML, the element loses its reference when it gets added.

• When you see all the elements of a parent node highlighted/logged, that doesn't necessarily mean nothing was there to begin with. That's because of how innerHTML and outerHTML work: changing these properties of an element results in overriding the content. When you see all the children highlighted, then, it could be because innerHTML or outerHTML was used.

The abort-on-property-write snippet patches a property on the window object that aborts execution when the property is written or set. No error gets printed to the console.

You can use this snippet to abort the execution of inline scripts.

Parameters

Filter examples

The following table lists examples that use the abort-on-property-write snippet:

Debugging

The following table contains messages you'll find useful during debugging:

Tradeoffs

Keep the following tradeoffs in mind when you use the abort-on-property-writefilter:

• The snippet is executed after all of a page's inline scripts. As a result, you should only attach properties read inside of a callback, which can be executed after the script.

• You can only attach this snippet to global properties, or properties of the window object.

• You should only attach to properties set just inside the script you want to abort. Otherwise, an error will be thrown.

The json-override snippet wraps JSON.parse to override values from the same list as override-property-read.

Parameters

Possible override values

Filter examples

The following table lists examples that use the json-override snippet:

Debugging

The following table contains messages you'll find useful during debugging:

The json-prune snippet traps calls to JSON.parse and, if the result of the parsing is an Object, it will remove the specified properties from the result before returning to the caller.

Use json-prune when you want to remove properties from an object parsed with JSON.parse.

Parameters

Filter examples

The following table lists examples that use the json-override snippet:

Debugging

The following table contains messages you'll find useful during debugging:

The replace-xhr-response snippet replaces the response of a XHR request if the response text matches a given regular expression pattern.

Parameters

Filter examples

Debugging

The following table contains messages you'll find useful during debugging:

The strip-fetch-query-parameter strips a query string parameter from fetch() calls.

You can use this snippet to remove parameters from fetch calls that mach a urlPattern, if provided. If urlPattern isn't provided, the parameter gets stripped from all fetch calls.

Parameters

Filter examples

The following table lists examples that use the strip-fetch-query-parameter snippet:

The replace-fetch-response snippet replaces the response of a fetch request if the response text matches a given regular expression pattern.

Parameters

Filter examples

Debugging

The following table contains messages you'll find useful during debugging:

The override-property-read snippet overrides a property's value on the window object with a set of available properties.

You can use the override-property-read snippet to change the value of global properties.

Parameters