This article introduces how to write URL blocking rules in X Browser. If you are already familiar with ABP blocking rule syntax, you can use ABP rule syntax to write rules. X Browser is compatible with ABP rule syntax. Here we only introduce the simplified rule syntax that is easier to get started with in X Browser.
Series Navigation
- Overview: Ad Blocking Introduction
- Current: URL Blocking Rules
- Next: Writing Hidden Element Rules
- Exception Rules: How to Write Exception Rules
- Strong Blocking: Strong Blocking Mode and Rules
Quick Start (TL;DR)
Below are some of the most commonly used rule formats. You can start with these:
example.com |
Domain Matching Rules
Single domain rules will match as long as the domain of the resource URL can be matched.
Example 1
The simplest case is to use a complete domain name as a blocking rule, as shown below.
www.example.com |
The following resource URL will be matched by the rule.
https://www.example.com/path/of/banner.js |
Example 2
You can also use subdomains or combine them with wildcards to form blocking rules, such as the following rules:
example.com |
The above rules have the same effect. Choose the writing style you are comfortable with. The following resource URLs will be matched:
https://a.example.com/path/of/banner.js |
Example 3
Wildcards are used for fuzzy matching and can simplify rule writing. Here are more examples using wildcards.
ad.*.example.com |
The following resource URLs will be matched:
https://ad.img.example.com/path/of/banner.js |
Example 4
s*.example.com |
Can match resource URLs like the following:
https://s1.example.com/path/of/banner.js |
Path Matching Rules
Using path as a matching condition, it will be matched as long as the path can be matched, as shown in the following examples.
Example 1
/path/of/banner.js |
These two rules are equivalent and can match the following resource URLs:
https://www.example.com/path/of/banner.js |
Example 2
/path/*/banner.js |
Wildcards can also be used. Resource URLs like the following will be matched:
https://www.example.com/path/of/banner.js |
Example 3
/path/of/banner.* |
Resource URLs like the following will be matched:
https://www.example.com/path/of/banner.js |
Query Parameter Matching Rules
Using query parameters as matching conditions, it will be matched as long as the query parameters can be matched, as shown in the following examples.
Example 1
&ct=bj&dit= |
Resource URLs like the following can be matched:
https://www.example.com/path/of/banner.js?lang=en&ct=bj&dit=100060 |
Example 2
Using wildcards
?frm=*&ct=*&dit= |
Resource URLs like the following will be matched:
https://www.example.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
Combined Usage
From the above examples, we can see that blocking rules can match domains, paths, and query parameters separately. Moreover, we can combine them to get more precise matching.
Example 1
example.com/path/of/banner.js?frm= |
Can match resource URLs like the following:
https://www.example.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
Example 2
Using wildcards
example.com/*?frm=cn&ct=*&dit= |
Will match resource URLs like the following:
https://www.example.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
Advanced Usage
Using Control Parameter “$3p”
3p is short for “third-party”. Sometimes we only want our blocking rules to apply to external resources, in other words, rules only apply to resource URLs with different domains from the current website. In this case, we just need to add the control parameter “$3p” after the rule, as shown in the following example.
/path/of/banner.js$3p |
Assuming the website we are currently visiting is www.example.com, the rule will match the following resource URL:
https://mydomain.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
And allow the following resource URL:
https://www.example.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
Using Control Parameter “$~3p”
Contrary to the control parameter “$3p”, sometimes we want blocking rules to only apply to internal resources, in other words, rules only apply to resource URLs under the same domain as the current website. In this case, we need to use the control parameter “$~3p”, as shown in the following example.
/path/of/banner.js$~3p |
Assuming the website we are currently visiting is www.example.com, the rule will match the following resource URL:
https://www.example.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
And allow:
https://mydomain.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
Using Regular Expressions
If you are familiar with regular expressions, you can directly match resource URLs using regular expressions. We specify that regular expression rules start with “–” followed by the regular expression, as shown in the following example.
--ad(\d{1,2})?\.example\.com |
Can block resource URLs like the following:
https://ad.example.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
But the following resource URLs, although similar, will be allowed because they don’t match the regular expression:
https://ads.example.com/path/of/banner.js?frm=cn&ct=bj&dit=100080 |
Adding Domain Scope
To make rules more precise and avoid accidentally blocking resources from other sites, we can add domain scope to rules, limiting rules to only take effect under specified domains. The format is “rule@domain list”, as shown in the following examples.
/path/of/banner.js@my.example.com |
This rule only takes effect on sites with the domain my.example.com
/path/of/banner.js@example.com |
This rule takes effect on sites with the top-level domain example.com
/path/of/banner.js@my.example.com,mysite.com,myspace.com |
The rule can take effect under multiple specified domains
Combined Usage
Regular rules and control parameters can be used together. Below are some valid rule examples.
/path/of/banner.js$3p@example.com |
Performance Recommendations
Please prioritize using rules without wildcards. Pure domain, path, query parameter matching or their combinations are very fast, requiring no traversal search. Even hundreds of thousands of rules will not affect performance.
For rules with wildcards, internally we convert them to greedy mode regular expressions. As is well known, greedy mode regular expressions have relatively lower performance. So try to prioritize using combinations of domains, paths, and query parameters without wildcards to write rules.
For example, optimized rules will have better performance.
*/path/of/banner.js |
Recommended to change to:
/path/of/banner.js |