Create a filter list
Creating a filter list
A filter list is a text file that contains, in this order:
- A collection of optional special comments, one per line
- A collection of filters or normal comments, one per line
The header line must be the first line of the file.
It should say
[Adblock Plus]
. It might also contain a version number, for example [Adblock Plus 2.0]
, but the version is ignored by the eyeo Browser Ad-Filtering Solution.Special comments are a single block of consecutive comments that start from an exclamation mark (
!
) and follow a key:value
semantic.The Browser Ad-Filtering Solution interprets the following special comments:
Key | Value | Meaning | Example |
---|---|---|---|
Redirect | URL | Instead of parsing this filter list, download a filter list from the provided URL.
Useful when the list location has changed and an http redirect cannot be implemented. | ! Redirect: https://new-location.com/list.txt |
Title | String | Human-readable title of the filter list. Returned by:
| ! Title: My filters |
Version | String | An arbitrary string that describes the current version of the list. Returned by:
| ! Version: 202305310750
! Version: 5.0.4 |
Expires | Number, optionally followed by text | How frequently should the Solution download updates. In number of days, unless followed by a text starting from h , then in number of hours. Following text is ignored. | ! Expires: 1 days (update frequency)
! Expires: 1 hours
! Expires: 7 (weekly) |
There are other special comments that may be interpreted by other eyeo Ad-Filtering Solution, for example:
Homepage
License
Checksum
Parsing of the special comments block stops after encountering a line that isn't a
! key : value
. All further comments are treated as not special and ignored.This is probably the most important block of a filter list - the actual filters.
Comment lines start from an exclamation mark (
!
) and are skipped during parsing.The filters are parsed until the end of file.
[Adblock Plus]
! Version: 202306020710
! Title: My list
! Expires: 2 days
! Allow loading all resources on mysite.net
@@||mysite.net^$document,domain=mysite.net
! Unhide banner element on example.com
example.com#@#.banner
For a big working example, consider
https://easylist-downloads.adblockplus.org/easylist.txt
For a more minimal example, compare the filter list used for test pages:
https://abptestpages.org/en/abp-testcase-subscription.txt
For safety, the Browser Ad-Filtering Solution will only download filter lists from HTTPS servers, HTTP is not allowed.
An exception is
localhost
- the Solution will download a filter list from http://localhost/any/path.txt
to facilitate local development and testing.The eyeo Browser Ad-Filtering Solution will periodically download filter list updates. It will respect the interval specified in
! Expires
or revert to the default period of 5 days.The update check interval is clamped between 1 hour and 14 days.
If a new version of the filter list fails to download or parse correctly, the SDK will retain the old version and retry the update in an hour.
Last modified 1mo ago