Links

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