Configure SDK settings

Customization options for the SDK.

Available settings
The example Android UI and the example Desktop Settings Extension come with the following settings that can be manipulated by your users.
Setting
Type
Description
Ad-blocking
Boolean
Enables or disables ad-filtering
Acceptable Ads
Boolean
Displays or hides Acceptable Ads​
Subscriptions
List
Filter list subscriptions
Allowed domains
List
Domains on which no ads will be blocked, even if ad-filtering is enabled
Custom filters
List
Additional filters written in filter language​
Custom implementation
You can implement user settings according to your needs via any of these entry points:
The C++ class AdblockController,
The Java class org.chromium.components.adblock.AdblockController
The Browser Extension API defined and documented in chrome/common/extensions/api/adblock_private.idl
Toggle ad-filtering
To toggle ad-filtering use setEnabled with the appropriate bool value:
To query if ad-filtering is enabled use isEnabled.
The following example disables adblocking:
Java
JavaScript
C++
import org.chromium.components.adblock.AdblockController;
​
AdblockController.getInstance().isEnabled();  // true
AdblockController.getInstance().setEnabled(false);
AdblockController.getInstance().isEnabled();  // false
chrome.adblockPrivate.isEnabled();  // true
chrome.adblockPrivate.setEnabled(false);
chrome.adblockPrivate.isEnabled();  // false
#include "chrome/browser/adblock/adblock_controller_factory.h"
#include "components/adblock/core/adblock_controller.h"
​
AdblockController* controller =
    AdblockControllerFactory::GetForBrowserContext(profile());
controller->IsAdblockEnabled();  // true
controller->SetAdblockEnabled(false);
controller->IsAdblockEnabled();  // false
Toggle Acceptable Ads
Acceptable ads can be toggled in a similar way with the setAcceptableAdsEnabled API call.
To query if Acceptable Ads are enabled use isAcceptableAdsEnabled.
The following example disabled Acceptable Ads:
Java
JavaScript
C++
import org.chromium.components.adblock.AdblockController;
​
AdblockController.getInstance().isAcceptableAdsEnabled();  // true
AdblockController.getInstance().setAcceptableAdsEnabled(false);
AdblockController.getInstance().isAcceptableAdsEnabled();  // false
chrome.adblockPrivate.isAcceptableAdsEnabled();  // true
chrome.adblockPrivate.setAcceptableAdsEnabled(false);
chrome.adblockPrivate.isAcceptableAdsEnabled();  // false
#include "chrome/browser/adblock/adblock_controller_factory.h"
#include "components/adblock/core/adblock_controller.h"
​
AdblockController* controller =
    AdblockControllerFactory::GetForBrowserContext(profile());
controller->IsAcceptableAdsEnabled();  // true
controller->SetAcceptableAdsEnabled(false);
controller->IsAcceptableAdsEnabled();  // false
Note: Acceptable Ads can be enabled/disabled with installSubscription/uninstallSubscription methods too.
Add/Remove subscriptions
Use installSubscription to add and uninstallSubscription to remove a filter list.
To get the list of installed subscriptions use getInstalledSubscriptions.
The following code snippet installs example_list:
Java
JavaScript
C++
import org.chromium.components.adblock.AdblockController;
​
URL exampleFilterList = new URL("http://example.com/example_list.txt");
AdblockController.getInstance().installSubscription(exampleFilterList);
AdblockController.getInstance().getInstalledSubscriptions();  // ["http://example.com/example_list.txt", ...]
var exampleFilterList = new URL("http://example.com/example_list.txt");
chrome.adblockPrivate.installSubscription(exampleFilterList.href);
chrome.adblockPrivate.getInstalledSubscriptions();  // ["http://example.com/example_list.txt", ...]
#include "chrome/browser/adblock/adblock_controller_factory.h"
#include "components/adblock/core/adblock_controller.h"
​
const GURL example_filter_list("http://example.com/example_list.txt");
​
AdblockController* controller =
    AdblockControllerFactory::GetForBrowserContext(profile());
controller->InstallSubscription(example_filter_list);
​
std::vector<scoped_refptr<Subscription>> subscriptions =
    controller->GetInstalledSubscriptions();
// subscriptions[0]->GetSourceUrl() == example_filter_list
// subscriptions[0]->GetInstallationState() == InstallationState::Installing
​
Known subscriptions
The SDK contains static, built-in descriptions of some filter lists that contain:
The URL of the filter list (for example "https://easylist-downloads.adblockplus.org/bulgarian_list+easylist.txt")
Languages that the filter list applies to (for example "bg")
Human-readable titles (for example "Bulgarian list+EasyList")
Policies that govern whether the SDK:
installs it by default
allows snippets in the list
shows the list in the example UI
To view those descriptions, use the following code:
Java
JavaScript
C++
import org.chromium.components.adblock.AdblockController;
​
List<Subscription> known_subscriptions =
        AdblockController.getInstance().getRecommendedSubscriptions();
let known_subscriptions = chrome.adblockPrivate.getBuiltInSubscriptions();
#include "chrome/browser/adblock/adblock_controller_factory.h"
#include "components/adblock/core/adblock_controller.h"
​
AdblockController* controller =
    AdblockControllerFactory::GetForBrowserContext(profile());
std::vector<KnownSubscriptionInfo> known_subscriptions =
    controller->GetKnownSubscriptions();
It is not possible to modify those descriptions at runtime, but you can change them by modifying components/adblock/core/subscription/subscription_config.cc and recompiling.
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
JavaScript
C++
import org.chromium.components.adblock.AdblockController;
​
AdblockController.getInstance().addAllowedDomain("example.com");
AdblockController.getInstance().getAllowedDomains();  // ["example.com"]
AdblockController.getInstance().removeAllowedDomain("example.com");
AdblockController.getInstance().getAllowedDomains();  // []
chrome.adblockPrivate.addAllowedDomain("example.com");
chrome.adblockPrivate.getAllowedDomains();  // ["example.com"]
chrome.adblockPrivate.removeAllowedDomain("example.com");
chrome.adblockPrivate.getAllowedDomains();  // []
#include "chrome/browser/adblock/adblock_controller_factory.h"
#include "components/adblock/core/adblock_controller.h"
​
AdblockController* controller =
    AdblockControllerFactory::GetForBrowserContext(profile());
controller->AddAllowedDomain("example.com");
controller->GetAllowedDomains();  // ["example.com"]
controller->RemoveAllowedDomain("example.com");
controller->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
JavaScript
C++
import org.chromium.components.adblock.AdblockController;
​
AdblockController.getInstance().addCustomFilter("example_domain##.example_selector");
AdblockController.getInstance().getCustomFilters();  // ["example_domain##.example_selector"]
AdblockController.getInstance().removeCustomFilter("example_domain##.example_selector");
AdblockController.getInstance().getCustomFilters();  // []
chrome.adblockPrivate.addCustomFilter("example_domain##.example_selector");
chrome.adblockPrivate.getCustomFilters();  // ["example_domain##.example_selector"]
chrome.adblockPrivate.removeCustomFilter("example_domain##.example_selector");
chrome.adblockPrivate.getCustomFilters();  // []
#include "chrome/browser/adblock/adblock_controller_factory.h"
#include "components/adblock/core/adblock_controller.h"
​
AdblockController* controller =
    AdblockControllerFactory::GetForBrowserContext(profile());
controller->AddCustomFilter("example_domain##.example_selector");
controller->GetCustomFilters();  // ["example_domain##.example_selector"]
controller->RemoveCustomFilter("example_domain##.example_selector");
controller->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
JavaScript
import org.chromium.components.adblock.AdblockController;
​
AdblockController.getInstance().addOnAdBlockedObserver(new ResourceClassificationNotifier.AdBlockedObserver{
    @Override
    public void onAdAllowed(AdblockCounters.ResourceInfo info) {
        // ...
    }
    @Override
    public void onAdBlocked(AdblockCounters.ResourceInfo info) {
        // ...
    }
});
Since version 92:
chrome.adblockPrivate.onAdAllowed.addListener(function(info) {
    // ...
});
chrome.adblockPrivate.onAdBlocked.addListener(function(info) {
    // ...
});
Since version 109:
chrome.eyeoFilteringPrivate.onRequestAllowed.addListener(function(info) {
    // ...
});
chrome.eyeoFilteringPrivate.onRequestBlocked.addListener(function(info) {
    // ...
});

Setting	Type	Description
Ad-blocking	Boolean	Enables or disables ad-filtering
Acceptable Ads	Boolean	Displays or hides Acceptable Ads
Subscriptions	List	Filter list subscriptions
Allowed domains	List	Domains on which no ads will be blocked, even if ad-filtering is enabled
Custom filters	List	Additional filters written in filter language

User counting

Run separate instances of the filtering engine

Last modified 18d ago