Configure Solution settings

Customization options for the Browser Ad-Filtering Solution.

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

Java

• Android OS

• Instance of a BrowserContextHandle required

JavaScript

• Desktop OS (Windows, Linux, MacOS)

• The SHA1 hash of your extension ID must be added to the allowlist in chrome/common/extensions/api/_permission_features.json

C++

• Works on any platform

• Instance of a BrowserContext required

• API changes more frequently than the Java and JavaScript APIs

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:

Java

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

JavaScript

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

C++

#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

Java

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

JavaScript

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

C++

#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:

Java

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", ...]

JavaScript

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", ...]

C++

#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.

Java

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();  // []

JavaScript

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

C++

#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:

Java

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();  // []

JavaScript

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");  // []

C++

#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.

Java

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) {
        // ...
    }
});

JavaScript

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

C++

#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);