Create a filter list

Creating a filter list

Anatomy of a filter list

A filter list is a text file that contains, in this order:

• An [Adblock Plus] header line, to identify itself as following the Adblock Plus syntax

• A collection of optional special comments, one per line

• A collection of filters or normal comments, one per line

The header 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

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: C++: Subscription::GetTitle() Java: Subscription::title() JavaScript: Subscription.title	! Title: My filters
Version	String	An arbitrary string that describes the current version of the list. Returned by: C++: Subscription::GetCurrentVersion() Java: Subscription::version() JavaScript: Subscription.current_version	! 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.

Filters and normal comments

This is probably the most important block of a filter list - the actual filters.

You can write one filter rule per line, as described in Adblock Plus syntax.

Comment lines start from an exclamation mark (!) and are skipped during parsing.

The filters are parsed until the end of file.

Examples

[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

Hosting

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.

Updating

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.

Limitations

Snippet filters and header filters will be ignored. They are only allowed on ABP Filters.

You can still add snippet and header filters as individual custom filters, as explained here.