Configure SDK settings
Customization options for the SDK.
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 | |
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 |
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
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
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.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
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.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').
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(); // []
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) {
// ...
});
Last modified 18d ago