Run separate instances of the filtering engine
Using multiple filtering configurations.
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:
Name
Unique name of this configuration
Enabled
Whether this entire configuration is currently enabled and active
Filter lists
List of currently selected filter lists, typically identified by URLs
Allowed domains
List of domains exempt from filtering
Custom filters
List of individual filters installed in addition to those from filter lists
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 anad
substring.However, the user has allowlisted
example.com
by adding it toadblock
's allowed domains, therefore filtering configurationadblock
classifieshttps://example.com/ad.png
as an allowed resource.Filtering configuration
sfw
is an age-restricting configuration and it has a blocking filter forhttps://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);
Getting installed filtering configurations
List<FilteringConfiguration> configs = FilteringConfiguration.getConfigurations();
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");
If you have FilteringConfirutation
object for removed configuration, it becomes invalid. Any method called on a removed configuration will throw an IllegalStateException.
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
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
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.
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
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);
Last updated
Was this helpful?