AG Filters Registry
This repository contains the known filters subscriptions available to AdGuard users. We re-host these filters on filters.adtidy.org
. Also, these filters can be slightly modified in order to achieve better compatibility with AdGuard.
What filters can be added to this repository
We may add third-party filters to AdGuard Filters Registry. When making a decision about adding a third-party filter, we follow these rules:
- The filter should be oriented towards browser content blockers.
- The filter should be legal. If it has rules for paywall circumvention, we won't add such a filter.
- The filter should have a place for receiving user complaints and holding discussions, such as a repository on github.com, or a website open to public.
- The filter should be relatively popular, meaning:
- if there is a repository on GitHub, the number of stars should be at least 50
- if there is no repository on GitHub, the number of analyzed issues and discussions is estimated at 10 per month on the filter's website
- the filter should be actively supported for at least 6 months
- The filter should be regularly updated with at least 10 updates per month.
- The filter should be compatible with AdGuard products. You can familiarize yourself with AdGuard syntax here: https://adguard.com/kb/general/ad-filtering/create-own-filters/.
- If the filter works only in some operating systems and satisfies all other criteria, it will be added but only for the supported platforms.
- Previously added filters that haven't received any support for a year will be removed. We reserve the right to remove the filter earlier, depending on circumstances.
- If the filter contains too many problematic rules, it will not be added. A rule is considered problematic if it causes false positives or otherwise displays unintended behavior. Decisions about filters with problematic rules are arbitrary and there may be exceptions (see items 9 and 10, for example).
- If the filter intentionally blocks or restricts access to any services for no reason other than being a reflection of the filter author's opinion, the filter will not get added, or will get removed if already added.
- If the filter is popular in a specific region and there are no alternatives to it, then it can be added as is.
- If the filter gets added, it receives a so-called trustLevel (Low, High, Full), based on the number of problematic rules it contains and some other factors. Filters without "Full" trust level may have part of their rules disabled.
- The trust level of a filter can be re-reviewed and raised if the author improves the filter over time.
- If there are two or more similar filters that satisfy all other criteria, they all may be added if they don't duplicate each other and don't conflict with each other. If there is a large amount of conflicting or duplicate rules, the filter with more matches on such rules gets the priority.
Filters metadata
-
template.txt
Template file is used by the filters compiler to prepare the final filter version.
-
exclude.txt
A list of regular expressions. Rules that match these exclusions will not be included in the resulting filter.
-
metadata.json
Filter metadata. Includes name, description, etc.
filterId
— unique filter identifier (integer)name
— filter name; can be localizeddescription
— filter descriptiontimeAdded
— time when this filter was added to the registry; milliseconds since January 1, 1970; you can execnew Date().getTime()
in the browser console to get the current timehomepage
— filter website/homepageexpires
— filter's default expiration period; used as filter update interval if "Default" is chosen for according setting in AdGuard productdisplayNumber
— this number is used when AdGuard sorts available filters (GUI)groupId
— group identifiersubscriptionUrl
— default filter subscription URLtags
— a list of tags-
trustLevel
— level of trust which describe allowed and permitted rules types; possible values:low
— only low-risk rule types are allowed; defaults to low if trust level is not configured at allhigh
— trusted third-party filter lists; some particular rules from there are still permittedfull
— all types of filter rules are allowed; only AdGuard filter lists have full trust at the moment
platformsIncluded
— the list of platforms to compile the filter for, e.g.["mac", "windows", "android"]
. If you need to compile the filter for all platforms remove this propertyplatformsExcluded
— the list of platforms to skip while filter compiling, e.g.["ios", "ext_safari"]
. If you need to compile the filter for all platforms remove this property
Note please that both
platformsIncluded
andplatformsExcluded
should not be set in filter's metadata simultaneously.Metadata example
{ "filterId": 2, "name": "AdGuard Base filter", "description": "EasyList + AdGuard English filter. This filter is necessary for quality ad blocking.", "timeAdded": 1404115015843, "homepage": "https://adguard.com/kb/general/ad-filtering/adguard-filters/", "expires": "4 days", "displayNumber": 1, "groupId": 1, "subscriptionUrl": "https://filters.adtidy.org/extension/chromium/filters/2.txt", "tags": [ "purpose:ads", "reference:101", "recommended", "reference:2" ], "trustLevel": "full", "platformsIncluded": [ "windows", "mac", "android", "ext_ublock" ] }
-
revision.json
Filter version metadata, automatically filled and overwritten on each build.
-
filter.txt
Resulting compiled filter.
-
diff.txt
Build log that contains excluded and converted rules with an explanation.
Tags
Every filter can be marked by a number of tags. Every tag metadata listed in /tags/metadata.json
.
Example
{
"tagId": 1,
"keyword": "purpose:ads"
},
Possible tags:
-
lang:*
— for language-specific filters; one or multiple lang-tags can be used. For instance, AdGuard Russian filter is marked with thelang:ru
tag. -
purpose:*
— determines filters purposes; multiple purpose-tags can be used for one filter list. For instance,AdGuard DNS
is marked with bothpurpose:ads
andpurpose:privacy
. -
recommended
— for low-risk filter lists which are recommended to use in their category. The category is determined by the pair of thelang:*
andpurpose:*
tags. -
obsolete
— for abandoned filter lists; filter's metadata with this tag will be excluded fromfilters.json
andfilters_i18n.json
.
Groups
/groups/metadata.json
— filters groups metadata. Each filter should belong to one of the groups.
Filters optimization
For each filter, AdGuard compiles two versions: full and optimized. Optimized version is much more lightweight and does not contain rules which are not used at all or used rarely. Rules usage frequency comes from the collected filter rules statistics (thanks to the volunteers who enabled it in their AdGuard).
optimization_config.json
- defines the target for the optimization process. AdGuard will try to compress the lists by removing the most rarely used rules until the compression goal (defined in percents) is met.
Filters compiler customization
custom_platforms.js
customizes the way filters are compiled for certain platforms. We should use it if we need to
temporary change rules for a platform. In all other cases, we should prefer the default configuration.
Below is a example of the configuration for the platform AdGuard for Chrome
with comments:
"EXTENSION_CHROMIUM": {
// Defines the platform for which the settings are specified.
"platform": "ext_chromium",
// Defines the path that can be used to access the settings or resources associated with this platform.
"path": "extension/chromium",
"configuration": {
// Sets an array of regular expressions that will be used to remove certain rules.
"removeRulePatterns": [
"^((?!#%#).)*\\$\\$|\\$\\@\\$",
"\\$(.*,)?replace=",
"important,replace=",
"\\$(.*,)?app",
"\\$network",
"\\$protobuf",
"important,protobuf",
"\\$extension",
",extension"
],
// Sets an array of objects that will be used to replace certain values.
"replacements": [
{
"from": ":has\\(",
"to": ":-abp-has("
}
],
// Specifies whether to ignore hints for rules. A value of "false" means that hints will not be ignored.
"ignoreRuleHints": false
},
"defines": {
"adguard": true,
"adguard_ext_chromium": true
}
},
Filters localization
If you want to help with filters translations, you can join us on Crowdin: https://crowdin.com/project/adguard-applications/en#/miscellaneous/filters-registry
Please learn more about translating our products: https://adguard.com/kb/miscellaneous/contribute/translate/program/
Filters templates
@include
directive allows to include the content of specified file into the filter.
If you want to add a filter and keep all its rules during optimization, use the /notOptimized
parameter.
Example:
@include "https://example.org/test-filter.txt" /notOptimized
How to build
yarn install
Run the following command:
node index.js
Build with white/black lists:
node index.js -i=1,2,3 -s=4,5,6
Validate filters.json
and filters_i18n.json
for platforms:
node validate ./platforms
For AdGuard filters all locales are required, it means 100% translated.
Validate locales:
yarn locales:validate
For third-party filters only
REQUIRED_LOCALES
should be 100% done.