So erstellen Sie Ihre eigenen Werbefilter
In diesem Artikel wird erklärt, wie Sie benutzerdefinierte Filterregeln für die Verwendung in AdGuard-Produkten erstellen können. Um Ihre Regeln zu testen, können Sie die AdGuard-App herunterladen
Ein Filter ist eine Reihe von Filterregeln, die auf bestimmte Inhalte wie Banner oder Pop-ups angewendet werden. AdGuard verfügt über eine von unserem Team erstellte Liste von Standardfiltern. Wir verbessern und aktualisieren sie ständig und bemühen uns, den Bedürfnissen der meisten unserer Nutzer gerecht zu werden.
Gleichzeitig können Sie mit AdGuard Ihre eigenen benutzerdefinierten Filter erstellen, indem Sie dieselben Regeltypen verwenden, die wir in unseren Filtern haben.
Um die Syntax unserer Filterregeln zu beschreiben, verwenden wir Augmented BNF for Syntax Specifications, aber wir halten uns nicht immer streng an diese Spezifikation.
Ursprünglich basierte die Syntax des AdGuard auf der Syntax der Adblock Plus-Regeln. Später haben wir es um neue Regelarten für eine bessere Filterung der Werbung erweitert. Einige Teile dieses Artikels über die Regeln, die sowohl für AdGuard als auch für ABP gelten, wurden aus der Anleitung von Adblock Plus zum Schreiben von Filtern übernommen.
Kommentare
Jede Zeile, die mit einem Ausrufezeichen beginnt, ist ein Kommentar. In der Liste der Regeln wird sie in grauer Farbe angezeigt. AdGuard ignoriert diese Zeile, Sie können also schreiben, was Sie wollen. Kommentare werden in der Regel über den Regeln platziert und beschreiben, was eine Regel bewirkt.
Zum Beispiel:
! Dies ist der Kommentar. Unterhalb dieser Zeile befindet sich die eigentliche Filterregel.
||example.org^
Beispiele
Sperren nach Domainnamen
Diese Regel sperrt:
http://example.org/ad1.gif
http://subdomain.example.org/ad1.gif
https://ads.example.org:8000/
Diese Regel sperrt nicht:
http://ads.example.org.us/ad1.gif
http://example.com/redirect/http://ads.example.org/
Standardmäßig funktionieren solche Regeln nicht für Dokumentanfragen. This means that the ||example.org^
rule will block a request made to example.org
when you try to navigate to this domain from another website, but if you type example.org
into the address bar and try to navigate to it, the website will open. To block the document request, you will need to use a rule with the $document
modifier: ||example.org^$document
.
Sperren der genauen Adresse
Diese Regel sperrt:
http://example.org/
Diese Regel sperrt nicht:
https://example.org/banner/img
Modifikatoren für Grundregeln
Filterregeln unterstützen zahlreiche Modifikatoren, mit denen Sie das Verhalten der Regel feinabstimmen können. Hier ist ein Beispiel für eine Regel mit einigen einfachen Modifikatoren.
Diese Regel sperrt:
http://example.org/script.js
if this script is loaded fromexample.com
.
Diese Regel sperrt nicht:
https://example.org/script.js
if this script is loaded fromexample.org
.https://example.org/banner.png
weil es sich nicht um ein Skript handelt.
Entsperren einer Adresse
Diese Regel sperrt nicht:
http://example.org/banner.png
, auch wenn es eine Sperrregel für diese Adresse gibt.
Sperrregeln mit dem Modifikator $important
können Ausnahmen außer Kraft setzen.
Entsperren einer gesamten Website
Diese Regel entsperrt
- alle kosmetischen Regeln auf
example.com
. - alle von dieser Website gesendeten Anfragen, auch wenn es für diese Anfragen Sperrregeln gibt.
Kosmetische Regeln
Kosmetische Regeln basieren auf der Verwendung einer speziellen Sprache namens CSS, die jeder Browser versteht. Im Grunde fügt es der Website einen neuen CSS-Stil hinzu, der dazu dient, bestimmte Elemente zu verbergen. Sie können mehr über CSS im Allgemeinen hier erfahren.
AdGuard erweitert CSS und ermöglicht es den Entwicklern von Filtern, viel kompliziertere Fälle zu behandeln. Um diese erweiterten Regeln nutzen zu können, müssen Sie jedoch mit regulärem CSS vertraut sein.
Beliebte CSS-Selektoren
Name | CSS-Selektor | Beschreibung |
---|---|---|
ID-Selektor | #banners | Matches all elements with id attribute equal to banners . |
Klassenselektor | .banners | Matches all elements with class attribute containing banners . |
Attribut-Selektor | div[class="banners"] | Matches all div elements with class attribute exactly equal to banners . |
Attribute substring selector | div[class^="advert1"] | Matches all div elements which class attribute starts with the advert1 string. |
Selektor für Attribut-Teilstrings | div[class$="banners_ads"] | Entspricht allen div -Elementen, deren class -Attribut mit banners_ads endet. |
Selektor für Attribut-Teilstrings | a[href^="http://example.com/"] | Entspricht allen Links, die von der Domain http://example.com/ geladen werden. |
Attribut-Selektor | a[href="http://example.com/"] | Matches all links to exactly the http://example.com/ address. |
Einschränkungen und Begrenzungen
Vertrauenswürdige Filter
Einige Regeln können nur in vertrauenswürdigen Filtern verwendet werden. Diese Kategorie umfasst:
- Filterlisten, die vom AdGuard-Team erstellt wurden,
- benutzerdefinierte Filterlisten, die als
vertrauenswürdig
installiert wurden, - Benutzerregeln.
AdGuard-Inhaltsblocker
AdGuard Inhaltsblocker ist eine Erweiterung für Samsung- und Yandex-Browser, die über Google Play installiert werden kann. Es ist nicht zu verwechseln mit dem voll funktionsfähigen AdGuard für Android, der nur von unserer Website heruntergeladen werden kann. Leider sind die Möglichkeiten von AdGuard Inhaltsblocker durch die von den Browsern erlaubten Funktionen begrenzt, und sie unterstützen nur eine ältere Adblock Plus-Filtersyntax:
- Grundregeln zur Sperrung mit den folgenden Modifikatoren:
$domain
,$third-party
, content-type-Modifikatoren. - Basic exception rules with the following modifiers:
$document
,$elemhide
. - Basic element hiding rules with no extended CSS support.
Aufgrund der oben genannten Einschränkungen wird AdGuard Inhaltsblocker nicht in den Kompatibilitätshinweisen erwähnt.
Grundregeln
Die einfachsten Regeln sind die sogenannten Grundregeln. Sie werden verwendet, um Anfragen an bestimmte URLs zu sperren. Oder um sie zu entsperren, wenn am Anfang der Regel eine spezielle Kennzeichnung „@@“ vorhanden ist. Das Grundprinzip für diese Art von Regeln ist recht einfach: Sie müssen die Adresse und zusätzliche Parameter angeben, die den Regelbereich einschränken oder erweitern.
Die Grundregeln für das Sperren von Anfragen werden nur auf Sub-Anfragen angewandt. Das bedeutet, dass sie das Laden der Seite nicht verhindern, es sei denn, es wird explizit mit einem $document
-Modifikator angegeben.
Der Browser erkennt eine gesperrte Anfrage als mit einem Fehler abgeschlossen.
Regeln, die kürzer als 4 Zeichen sind, gelten als ungültig und werden ignoriert.
Syntax der Grundregeln
rule = ["@@"] pattern [ "$" modifiers ]
modifiers = [modifier0, modifier1[, ...[, modifierN]]]
pattern
— eine Adressmaske. Jede Anfrage-URL wird mit dieser Maske abgeglichen. In der Vorlage können Sie auch die unten beschriebenen Sonderzeichen verwenden. Beachten Sie, dass AdGuard die URLs auf eine Länge von 4096 Zeichen kürzt, um den Abgleich zu beschleunigen und Probleme mit übermäßig langen URLs zu vermeiden.@@
— a marker that is used in rules of exception. Um die Filterung für eine Anfrage zu deaktivieren, beginnen Sie Ihre Regel mit diesem Marker.modifiers
— Parameter, die die Grundregel „verdeutlichen“. Einige von ihnen schränken den Anwendungsbereich der Regeln ein, andere können ihre Funktionsweise völlig verändern.
Sonderzeichen
*
— ein Platzhalterzeichen. Es wird verwendet, um eine beliebige Menge von Zeichen darzustellen. Dies kann auch eine leere Zeichenkette oder eine Zeichenkette mit beliebiger Länge sein.||
— eine Angabe zur Anwendung der Regel auf die angegebene Domain und ihre Subdomains. Mit diesem Zeichen müssen Sie kein bestimmtes Protokoll und keine Subdomain in der Adressmaske angeben. It means that||
stands forhttp://*.
,https://*.
,ws://*.
,wss://*.
at once.^
— ein Trennzeichen. Das Trennzeichen ist ein beliebiges Zeichen, jedoch ein Buchstabe, eine Ziffer oder eines der folgenden Zeichen:_
-
.
%
. In diesem Beispiel sind die Trennzeichen fett gedruckt:http:
//
beispiel.de
/?
t=1
&
t2=t3
. Das Ende der Adresse wird auch als Trennzeichen akzeptiert.|
— ein Zeiger auf den Anfang oder das Ende der Adresse. Der Wert hängt von der Platzierung des Zeichens in der Maske ab. Zum Beispiel entspricht die Regelswf|
der Regelhttp://beispiel.de/annoyingflash.swf
, aber nicht der Regelhttp://beispiel.de/swf/index.html
.|http://beispiel.de
entsprichthttp://beispiel.de
, aber nichthttp://domain.com?url=http://beispiel.de
.
|
, ||
, ^
kann nur mit Regeln verwendet werden, die einem URL-Muster entsprechen. Zum Beispiel ist ||example.com##.advert
falsch und wird vom Blocker ignoriert.
We also recommend to get acquainted with the Adblock Plus filter cheatsheet, for better understanding of how such rules should be made.
Unterstützung regulärer Ausdrücke
If you want even more flexibility in making rules, you can use Regular expressions instead of a default simplified mask with special characters.
Rules with regular expressions work more slowly, therefore it is recommended to avoid them or to limit their scope to specific domains.
Wenn Sie möchten, dass ein Blocker einen regulären Ausdruck erkennt, müssen die pattern
wie folgt aussehen:
pattern = "/" regexp "/"
For example, /banner\d+/$third-party
this rule will apply the regular expression banner\d+
to all third-party requests. Die Ausschlussregel mit regulärem Ausdruck sieht wie folgt aus: @@/banner\d+/
.
AdGuard Safari and AdGuard for iOS do not fully support regular expressions because of Content Blocking API restrictions (look for "The Regular expression format" section).
Platzhalter-Unterstützung für TLD (Top-Level-Domains)
Wildcard characters are supported for TLDs of the domains in patterns of cosmetic, HTML filtering and JavaScript rules.
Bei kosmetischen Regeln, z. B. example.*##.banner
, werden aufgrund des Teils .*
mehrere Domains abgeglichen, d. h. example.com
, sub.example.net
, example.co.uk
, usw.
For basic rules the described logic is applicable only for the domains specified in $domain
modifier, e.g. ||*/banners/*$image,domain=example.*
.
In AdGuard für Windows, Mac, Android und AdGuard Browsererweiterung passen Regeln mit dem Platzhalter .*
auf jede öffentliche Domainendung (oder eTLD). Aber für AdGuard für Safari und iOS ist die Liste der unterstützten Top-Level-Domains aufgrund der Einschränkungen von Safari begrenzt.
Regeln mit Platzhaltern für TLD werden vom AdGuard Inhaltsblocker nicht unterstützt.
Beispiele für Grundregeln
||example.com/ads/*
— eine einfache Regel, die Adressen wiehttp://example.com/ads/banner.jpg
und sogarhttp://subdomain.example.com/ads/otherbanner.jpg
entspricht.||example.org^$third-party
— diese Regel blockiert Anfragen von Drittanbietern zuexample.org
und seinen Subdomains.@@||example.com$document
— allgemeine Ausnahmeregel. It completely disables filtering forexample.com
and all subdomains. Es gibt eine Reihe von Modifikatoren, die in Ausnahmeregeln verwendet werden können. Weitere Einzelheiten finden Sie unter dem Link unten.
Modifikatoren für Grundregeln
The features described in this section are intended for experienced users. Sie erweitern die Möglichkeiten der Grundregeln, aber um sie nutzen zu können, müssen Sie ein grundlegendes Verständnis der Funktionsweise Ihres Browsers haben.
Sie können das Verhalten einer Grundregel ändern, indem Sie zusätzliche Modifikatoren verwenden. Modifikatoren sollten am Ende der Regel nach einem $
-Zeichen stehen und durch Kommata getrennt sein.
Beispiel:
||domain.com^$popup,third-party
Basismodifikatoren
Die folgenden Modifikatoren sind die einfachsten und am häufigsten verwendeten. Im Grunde beschränken sie lediglich den Anwendungsbereich der Regeln.
Modifikator \ Produkte | CoreLibs-Apps | AdGuard für Chromium | AdGuard für Chrome MV3 | AdGuard für Firefox | AdGuard für iOS | AdGuard für Safari | AdGuard-Inhaltsblocker |
---|---|---|---|---|---|---|---|
$app | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$denyallow | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$domain | ✅ | ✅ | ✅ *[1] | ✅ | ✅ *[1] | ✅ *[1] | ✅ |
$header | ✅ | ✅ *[2] | ❌ | ✅ *[2] | ❌ | ❌ | ❌ |
$important | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$match-case | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$method | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$popup | ✅ *[3] | ✅ | ✅ *[3] | ✅ | ✅ *[3] | ✅ *[3] | ❌ |
$strict-first-party | ⏳ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$strict-third-party | ⏳ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$third-party | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$to | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — vollständig unterstützt
- ✅ * — unterstützt, aber die Zuverlässigkeit kann variieren oder es können Einschränkungen auftreten; weitere Einzelheiten finden Sie in der Beschreibung des Modifikators
- ⏳ — Funktion, deren Implementierung geplant ist, die aber noch in keinem Produkt verfügbar ist
- ❌ — nicht unterstützt
$app
Mit diesem Modifikator können Sie die Regelabdeckung auf eine bestimmte Anwendung (oder eine Liste von Anwendungen) eingrenzen. Unter Windows und Mac mag dies nicht so wichtig sein, aber auf mobilen Geräten, wo einige der Filterregeln app-spezifisch sein müssen, ist dies sehr wichtig.
- Android — use the app package name, e.g.
org.example.app
. - Windows — use the process name, e.g.
chrome.exe
. - Mac — use the bundle ID or the process name, e.g.
com.google.Chrome
.
Für Mac können Sie die Bundle-ID oder den Prozessnamen der Anwendung herausfinden, indem Sie die entsprechenden Anfragedetails im Filterprotokoll anzeigen.
Beispiele
||baddomain.com^$app=org.example.app
— a rule to block requests that match the specified mask and are sent from theorg.example.app
Android app.||baddomain.com^$app=org.example.app1|org.example.app2
— the same rule but it works for bothorg.example.app1
andorg.example.app2
apps.
If you want the rule not to be applied to certain apps, start the app name with the ~
sign.
||baddomain.com^$app=~org.example.app
— a rule to block requests that match the specified mask and are sent from any app except for theorg.example.app
.||baddomain.com^$app=~org.example.app1|~org.example.app2
— same as above, but now two apps are excluded:org.example.app1
andorg.example.app2
.
Apps in the modifier value cannot have a wildcard, e.g. $app=com.*.music
. Regeln mit einem solchen Modifikator gelten als ungültig.
- Nur AdGuard für Windows, Mac und Android ist technisch in der Lage, Regeln mit dem Modifikator
$app
zu verwenden. - On Windows the process name is case-insensitive starting with AdGuard for Windows with CoreLibs v1.12 or later.
$denyallow
Der Modifikator $denyallow
ermöglicht es, die Erstellung zusätzlicher Regeln zu vermeiden, wenn eine bestimmte Regel für bestimmte Domänen deaktiviert werden muss. $denyallow
matches only target domains and not referrer domains.
Adding this modifier to a rule is equivalent to excluding the domains by the rule's matching pattern or to adding the corresponding exclusion rules. Um verschiedene Domains zu einer Regel hinzuzufügen, benutzen Sie |
als Trennungszeichen.
Beispiele
Diese Regel:
*$script,domain=a.com|b.com,denyallow=x.com|y.com
ist gleichbedeutend mit diesem:
/^(?!.*(x.com|y.com)).*$/$script,domain=a.com|b.com
or to the combination of these three:
*$script,domain=a.com|b.com
@@||x.com$script,domain=a.com|b.com
@@||y.com$script,domain=a.com|b.com
- The rule's matching pattern cannot target any specific domains, e.g. it cannot start with
||
. - Domains in the modifier value cannot be negated, e.g.
$denyallow=~x.com
, or have a wildcard TLD, e.g.$denyallow=x.*
, or be a regular expression, e.g.$denyallow=/\.(com\|org)/
. $denyallow
kann nicht zusammen mit$to
verwendet werden. It can be expressed with inverted$to
:$denyallow=a.com|b.com
is equivalent to$to=~a.com|~b.com
.
Die Regeln, die gegen diese Einschränkungen verstoßen, gelten als ungültig.
Regeln mit dem Modifikator $denyallow
werden von AdGuard Inhaltsblocker, AdGuard für iOS und AdGuard für Safari nicht unterstützt.
$domain
$domain
limits the rule scope to requests made from the specified domains and their subdomains (as indicated by the Referer HTTP header).
Syntax
Der Modifikator ist eine Liste von einem oder mehreren Ausdrücken, getrennt durch |
Symbol, von dem jedes je nach Typ auf eine bestimmte Weise mit einer Domain abgeglichen wird (siehe unten).
domains = ["~"] entry_0 ["|" ["~"] entry_1 ["|" ["~"]entry_2 ["|" ... ["|" ["~"]entry_N]]]]
entry_i = ( regular_domain / any_tld_domain / regexp )
regular_domain
– ein regulärer Domainname (domain.com
). Entspricht der angegebenen Domain und ihren Subdomains. It is matched lexicographically.any_tld_domain
— a domain name ending with a wildcard character as a public suffix, e.g. forexample.*
it isco.uk
inexample.co.uk
. Entspricht der angegebenen Domain und ihren Subdomains mit einem beliebigen öffentlichen Suffix. It is matched lexicographically.regexp
– ein regulärer Ausdruck, beginnt und endet mit/
. The pattern works the same way as in the basic URL rules, but the characters/
,$
,,
, and|
must be escaped with\
.
Regeln mit dem Modifikator $domain
als regular_domain
werden von allen AdGuard-Produkten unterstützt.
Beispiele
Einfach $domain
:
||baddomain.com^$domain=example.org
sperrt Anfragen, die der angegebenen Maske entsprechen und von der Domainexample.org
oder ihren Subdomains gesendet werden.||baddomain.com^$domain=example.org|example.com
— die gleiche Regel, aber sie funktioniert sowohl fürexample.org
als auch fürexample.com
.
Wenn Sie möchten, dass die Regel nicht auf bestimmte Domains angewendet wird, beginnen Sie einen Domainnamen mit dem Tilde-Zeichen ~
.
$domain
und Negation ~
:
||baddomain.com^$domain=example.org
sperrt Anfragen, die der angegebenen Maske entsprechen und von der Domainexample.org
oder ihren Subdomains gesendet werden.||baddomain.com^$domain=example.org|example.com
— die gleiche Regel, aber sie funktioniert sowohl fürexample.org
als auch fürexample.com
.||baddomain.com^$domain=example.org
sperrt Anfragen, die der angegebenen Maske entsprechen und von der Domainexample.org
oder ihren Subdomains gesendet werden.||baddomain.com^$domain=example.org|~foo.example.org
blocks requests sent fromexample.org
and its subdomains, except the subdomainfoo.example.org
.||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/
blocks requests sent fromexample.org
andexample.com
domains and all their subdomains.||baddomain.com^$domain=~a.com|~b.*|~/(^\|.+\.)c\.(com\|org)\$/
blocks requests sent from any domains, excepta.com
,b
with any public suffix (b.com
,b.co.uk
, etc.),c.com
,c.org
, and their subdomains.
$domain
-Modifikator, der der Zieldomain entspricht:
In einigen Fällen kann der Modifikator $domain
nicht nur mit der Referrer-Domain, sondern auch mit der Zieldomain übereinstimmen. Dies ist der Fall, wenn alle folgenden Bedingungen erfüllt sind:
- Die Anfrage hat den Inhaltstyp
document
- Das Regelmuster stimmt mit keiner bestimmten Domain überein
- Das Regelmuster enthält keine regulären Ausdrücke
- Der Modifikator
$domain
enthält nur ausgeschlossene Domains, z. B.$domain=~example.org|~example.com
The following predicate should be satisfied to perform a target domain matching:
1 UND ((2 UND 3) ODER 4)
That is, if the modifier $domain
contains only excluded domains, then the rule does not need to meet the second and third conditions to match the target domain against the modifier $domain
.
If some of the conditions above are not met but the rule contains $cookie
or $csp
modifier, the target domain will still be matched.
If the referrer matches a rule with $domain
that explicitly excludes the referrer domain, then the rule will not be applied even if the target domain also matches the rule. Dies betrifft auch Regeln mit den Modifikatoren $cookie
und $csp
.
Beispiele
*$cookie,domain=example.org|example.com
blockiert Cookies für alle Anfragen an und vonexample.org
undexample.com
.*$document,domain=example.org|example.com
blockiert alle Anfragen an und vonexample.org
undexample.com
.
In den folgenden Beispielen wird davon ausgegangen, dass die Anfragen von http://example.org/page
(dem Referrer) gesendet werden und die Ziel-URL http://targetdomain.com/page
lautet.
page$domain=example.org
will be matched, as it matches the referrer domain.page$domain=targetdomain.com
will be matched, as it matches the target domain and satisfies all requirements mentioned above.||*page$domain=targetdomain.com
will not be matched, as the pattern||*page
may match specific domains, e.g.example.page
.||*page$domain=targetdomain.com,cookie
will be matched because the rule contains$cookie
modifier despite the pattern||*page
may match specific domains./banner\d+/$domain=targetdomain.com
will not be matched as it contains a regular expression.Seite$domain=targetdomain.com|~example.org
wird nicht abgeglichen, da die Referrer-Domain explizit ausgeschlossen ist.
Einschränkungen des Modifikators $domain
In AdGuard for Chrome MV3, regexp
and any_tld_domain
entries are not supported.
Safari does not support the simultaneous use of allowed and disallowed domains, so rules like ||baddomain.com^$domain=example.org|~foo.example.org
will not work in AdGuard for iOS and AdGuard for Safari.
Rules with regular expressions in the $domain
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.11 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
In AdGuard for Windows, Mac and Android with CoreLibs v1.12 or later the $domain
modifier can be alternatively spelled as $from
.
$header
Der Modifikator $header
ermöglicht den Abgleich der HTTP-Antwort mit einem bestimmten Header mit (optional) einem bestimmten Wert.
Syntax
$header "=" h_name [":" h_value]
h_value = string / regexp
mit:
h_name
— required, an HTTP header name. It is matched case-insensitively.h_value
— optional, an HTTP header value matching expression, it may be one of the following:string
— a sequence of characters. It is matched against the header value lexicographically;regexp
– ein regulärer Ausdruck, beginnt und endet mit/
. The pattern works the same way as in the basic URL rules, but the characters/
,$
and,
must be escaped with\
.
The modifier part, ":" h_value
, may be omitted. In diesem Fall stimmt der Modifikator nur mit dem Headernamen überein.
Beispiele
||example.com^$header=set-cookie:foo
blockiert Anfragen, deren Antworten den HeaderSet-Cookie
mit dem Wertfoo
wörtlich übereinstimmen.||example.com^$header=set-cookie
blocks requests whose responses have theSet-Cookie
header with any value.@@||example.com^$header=set-cookie:/foo\, bar\$/
unblocks requests whose responses have theSet-Cookie
header with value matching thefoo, bar$
regular expression.@@||example.com^$header=set-cookie
unblocks requests whose responses have aSet-Cookie
header with any value.
$header
modifier limitations
- The
$header
modifier can be matched only when headers are received. So if the request is blocked or redirected at an earlier stage, the modifier cannot be applied. - In Adguard Browser Extension, the
$header
modifier is only compatible with$csp
,$removeheader
,$important
, and$badfilter
.
Rules with the $header
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.11 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
$important
The $important
modifier applied to a rule increases its priority over rules without the identical modifier. Even over basic exception rules.
Go to rules priorities for more details.
Beispiele
! blocking rule will block all requests despite of the exception rule
||example.org^$important
@@||example.org^
! if the exception rule also has `$important` modifier, it will prevail and requests won't be blocked
||example.org^$important
@@||example.org^$important
$match-case
Dieser Modifikator definiert eine Regel, die nur für Adressen gilt, die auf den Fall zutreffen. Bei den Standardregeln wird die Groß- und Kleinschreibung nicht berücksichtigt.
Beispiele
*/BannerAd.gif$match-case
– diese Regel blockierthttp://example.com/BannerAd.gif
, aber nichthttp://example.com/bannerad.gif
.
Rules with the $match-case
are supported by AdGuard for iOS and AdGuard for Safari with SafariConverterLib v2.0.43 or later.
Alle anderen Produkte unterstützen diesen Modifikator bereits.
$method
Dieser Modifikator schränkt den Regelbereich auf Anfragen ein, die den angegebenen Satz von HTTP-Methoden verwenden. Negierte Methoden sind zulässig. Die Methoden müssen ausschließlich in Kleinbuchstaben angegeben werden, die Groß-/Kleinschreibung wird jedoch nicht beachtet. Um mehrere Methoden zu einer Regel hinzuzufügen, verwenden Sie den vertikalen Balken |
als Trennzeichen.
Beispiele
||evil.com^$method=get|head
blockiert nur GET- und HEAD-Anfragen anevil.com
.||evil.com^$method=~post|~put
blockiert alle Anfragen anevil.com
außer POST oder PUT.@@||evil.com$method=get
entsperrt nur GET-Anfragen anevil.com
.@@||evil.com$method=~post
entsperrt alle Anfragen anevil.com
außer POST.
Regeln mit gemischt negierten und nicht negierten Werten werden als ungültig betrachtet. So wird beispielsweise die Regel ||evil.com^$method=get|~head
ignoriert.
Rules with $method
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.12 or later, and AdGuard Browser Extension for Chrome, Firefox, and Edge with TSUrlFilter v2.1.1 or later.
$popup
AdGuard versucht, den Browser-Tab mit jeder Adresse zu schließen, die einer Sperrregel mit diesem Modifikator entspricht. Bitte beachten Sie, dass nicht alle Tabs geschlossen werden können.
Beispiele
||domain.com^$popup
- wenn Sie versuchen,http://domain.com/
von einer beliebigen Seite des Browsers aus aufzurufen, wird eine neue Registerkarte, in der die angegebene Website geöffnet werden muss, durch diese Regel geschlossen.
$popup
modifier limitations
- Der Modifikator
$popup
funktioniert am besten in der AdGuard Browsererweiterung für Chromium-basierte Browser und Firefox. - In AdGuard for Chrome MV3 rules with the
$popup
modifier would not work, so we disable converting them to declarative rules. We will try to use them only in our TSUrlFilter engine and close new tabs programmatically. - In AdGuard für iOS und AdGuard für Safari blockieren
$popup
-Regeln die Seite einfach sofort. - In AdGuard für Windows, AdGuard für Mac und AdGuard für Android erkennt der Modifikator
$popup
in manchen Fällen möglicherweise kein Pop-up und es wird nicht blockiert. The$popup
modifier applies thedocument
content type with a special flag which is passed to a blocking page. Die blockierende Seite selbst kann einige Prüfungen durchführen und das Fenster schließen, wenn es sich wirklich um ein Pop-up-Fenster handelt. Andernfalls sollte die Seite geladen werden. It can be combined with other request type modifiers, such as$third-party
,$strict-third-party
,$strict-first-party
, and$important
.
Rules with the $popup
modifier are not supported by AdGuard Content Blocker.
$strict-first-party
Works the same as the $~third-party
modifier, but only treats the request as first-party if the referrer and origin have exactly the same hostname.
Beispiele
- domain.com$strict-first-party' — this rule applies only to
domain.com
. For example, a request fromdomain.com
tohttp://domain.com/icon.ico
is a first-party request. A request fromsub.domain.com
tohttp://domain.com/icon.ico
is treated as a third-party one (as opposed to the$~third-party
modifier).
You can use a shorter name (alias) instead of using the full modifier name: $strict1p
.
Rules with the $strict-first-party
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.16 or later.
$strict-third-party
Works the same as the $third-party
modifier but also treats requests from the domain to its subdomains and vice versa as third-party requests.
Beispiele
||domain.com^$strict-third-party
— this rule applies to all domains exceptdomain.com
. An example of a third-party request:http://sub.domain.com/banner.jpg
(as opposed to the$third-party
modifier).
Sie können einen kürzeren Namen (Alias) anstelle des vollständigen Modifikatornamens verwenden: $strict3p
.
Regeln mit dem $strict-third-party
-Modifikator werden von AdGuard für Windows, AdGuard für Mac und AdGuard für Android unterstützt, wenn CoreLibs v1.16 oder höher verwendet wird.
$third-party
Eine Einschränkung für Drittanbieter- und benutzerdefinierte Anfragen. Eine Drittanbieteranfrage ist eine Anfrage von einer externen Domain. Beispielsweise ist eine Anfrage an example.org
von domain.com
eine Anfrage eines Drittanbieters.
Um als solche zu gelten, muss eine Anfrage Dritter eine der folgenden Bedingungen erfüllen:
- Sein Referrer ist keine Subdomain der Zieldomain oder umgekehrt. Beispielsweise ist eine Anfrage an
subdomain.example.org
vonexample.org
eine Anfrage eines Drittanbieters - Its
Sec-Fetch-Site
header is set tocross-site
Beispiele
$third-party
:
||domain.com^$third-party
— diese Regel gilt für alle Domains, außerdomain.com
und seinen Subdomains. Ein Beispiel für eine Drittanbieteranfrage:http://example.org/banner.jpg
.
Wenn ein Modifikator $~third-party
vorhanden ist, wird die Regel nur auf Anfragen angewendet, die nicht von Dritten stammen. Das heißt, sie müssen von derselben Domain gesendet werden.
$~third-party
:
||domain.com$~third-party
— diese Regel wird ausschließlich aufdomain.com
angewendet. Beispiel für eine Anfrage, die nicht von Dritten stammt:http://domain.com/icon.ico
.
Sie können einen kürzeren Namen (Alias) verwenden, anstatt den vollständigen Namen des Modifikators zu verwenden: $3p
.
$to
$to
begrenzt den Geltungsbereich der Regel auf Anfragen, die von den angegebenen Domains und ihren Subdomains (wie durch den Referer HTTP-Header angegeben) gestellt werden. Um verschiedene Domains zu einer Regel hinzuzufügen, benutzen Sie |
als Trennungszeichen.
Beispiele
/ads$to=evil.com|evil.org
blockiert jede Anfrage anevil.com
oderevil.org
und ihre Subdomains mit einem Pfad, der mit/ads
übereinstimmt./ads$to=~not.evil.com|evil.com
blocks any request toevil.com
and its subdomains, with a path matching/ads
, except requests tonot.evil.com
and its subdomains./ads$to=~good.com|~good.org
blocks any request with a path matching/ads
, except requests togood.com
orgood.org
and their subdomains.
$denyallow
kann nicht zusammen mit $to
verwendet werden. It can be expressed with inverted $to
: $denyallow=a.com|b.com
is equivalent to $to=~a.com|~b.com
.
Rules with the $to
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.12 or later, and AdGuard Browser Extension with TSUrlFilter v2.1.3 or later.
Inhaltstyp-Modifikatoren
There is a set of modifiers, which can be used to limit the rule's application area to certain type of content. These modifiers can also be combined to cover, for example, both images and scripts.
There is a big difference in how AdGuard determines the content type on different platforms. For AdGuard Browser Extension, content type for every request is provided by the browser. AdGuard for Windows, Mac, and Android use the following method: first, the apps try to determine the type of the request by the Sec-Fetch-Dest
request header or by the filename extension. If the request is not blocked at this stage, the type will be determined using the Content-Type
header at the beginning of the server response.
Beispiele für Inhaltstypmodifikatoren
||example.org^$image
— entspricht allen Bildern vonexample.org
.||example.org^$script,stylesheet
— entspricht allen Skripten und Stilen vonexample.org
.||example.org^$~image,~script,~stylesheet
— entspricht allen Anfragen anexample.org
mit Ausnahme der Bilder, Skripte und Stile.
Modifikator \ Produkte | CoreLibs-Apps | AdGuard für Chromium | AdGuard für Chrome MV3 | AdGuard für Firefox | AdGuard für iOS | AdGuard für Safari | AdGuard-Inhaltsblocker |
---|---|---|---|---|---|---|---|
$document | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$font | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$image | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$media | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$object | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$other | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$ping | ✅ *[1] | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
$script | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$stylesheet | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$subdocument | ✅ *[2] | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$websocket | ✅ | ✅ | ✅ | ✅ | ✅ *[3] | ✅ *[3] | ❌ |
$xmlhttprequest | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$webrtc 🚫 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$object-subrequest 🚫 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
- ✅ — vollständig unterstützt
- ✅ * — unterstützt, aber die Zuverlässigkeit kann variieren oder es können Einschränkungen auftreten; weitere Einzelheiten finden Sie in der Beschreibung des Modifikators
- ❌ — nicht unterstützt
- 🚫 — entfernt und nicht mehr unterstützt
$document
Die Regel entspricht den Anforderungen für das Hauptdokument, d.h. HTML-Dokumente, die im Browser-Tab geladen werden. Es stimmt nicht mit Iframes überein, für diese gibt es den Modifikator $subdocument
.
Standardmäßig blockiert der AdGuard nicht die Anfragen, die im Browser-Tab geladen werden (z.B. "Mainframe-Bypass"). The idea is not to prevent pages from loading as the user clearly indicated that they want this page to be loaded. Wenn jedoch der Modifikator $document
explizit angegeben wird, verwendet AdGuard diese Logik nicht und verhindert das Laden der Seite. Instead, it responds with a "blocking page".
If this modifier is used with an exclusion rule (@@
), it completely disables blocking on corresponding pages. It is equivalent to using $elemhide
, $content
, $urlblock
, $jsinject
, $extension
modifiers simultaneously.
Beispiele
@@||example.com^$document
completely disables filtering on all pages atexample.com
and all subdomains.||example.com^$document
blocks HTML document request toexample.com
with a blocking page.||example.com^$document,redirect=noopframe
redirects HTML document request toexample.com
to an empty html document.||example.com^$document,removeparam=test
removestest
query parameter from HTML document request toexample.com
.||example.com^$document,replace=/test1/test2/
replacestest1
withtest2
in HTML document request toexample.com
.
You may use a shorter name (alias) instead of using the full modifier name: $doc
.
$font
The rule corresponds to requests for fonts, e.g. .woff
filename extension.
$image
The rule corresponds to images requests.
$media
The rule corresponds to requests for media files — music and video, e.g. .mp4
files.
$object
The rule corresponds to browser plugins resources, e.g. Java or Flash.
$other
The rule applies to requests for which the type has not been determined or does not match the types listed above.
$ping
The rule corresponds to requests caused by either navigator.sendBeacon()
or the ping
attribute on links.
$ping
modifier limitations
AdGuard for Windows, Mac, and Android often cannot accurately detect navigator.sendBeacon()
. Using $ping
is not recommended in the filter lists that are supposed to be used by CoreLibs-based AdGuard products.
Rules with $ping
modifier are not supported by AdGuard for Safari and AdGuard for iOS.
$script
The rule corresponds to script requests, e.g. javascript, vbscript.
$stylesheet
Die Regel entspricht CSS-Dateianfragen.
Sie können einen kürzeren Namen (Alias) verwenden, anstatt den vollständigen Namen des Modifikators zu verwenden: $css
.
$subdocument
The rule corresponds to requests for built-in pages — HTML tags frame
and iframe
.
Beispiele
||example.com^$subdocument
blocks built-in page requests (frame
andiframe
) toexample.com
and all its subdomains anywhere.||example.com^$subdocument,domain=domain.com
blocks built-in page requests (frame
иiframe
) toexample.com
(and its subdomains) fromdomain.com
and all its subdomains.
Sie können einen kürzeren Namen (Alias) verwenden, anstatt den vollständigen Namen des Modifikators zu verwenden: $frame
.
Einschränkungen des Modifikators $subdocument
In AdGuard für Windows, Mac und Android werden Unterdokumente durch den Sec-Fetch-Dest-Header erkannt, sofern dieser vorhanden ist. Andernfalls werden einige Hauptseiten möglicherweise als Unterdokumente behandelt.
Regeln mit dem $subdocument
-Modifikator werden von AdGuard Inhaltsblocker nicht unterstützt.
$websocket
Die Regel gilt nur für WebSocket-Verbindungen.
Einschränkungen des Modifikators $websocket
Für AdGuard für Safari und AdGuard für iOS wird es auf Geräten mit macOS Monterey (Version 12) und iOS 16 oder höher unterstützt.
$websocket
wird von allen AdGuard-Produkten außer AdGuard Inhaltsblocker unterstützt.
$xmlhttprequest
Die Regel gilt nur für Ajax-Anfragen (Anfragen, die über das Javascript-Objekt XMLHttpRequest
gesendet werden).
Sie können einen kürzeren Namen (Alias) verwenden, anstatt den vollständigen Namen des Modifikators zu verwenden: $xhr
.
AdGuard for Windows, Mac, Android when filtering older browsers cannot accurately detect this type and sometimes detects it as $other
or $script
. Sie können diesen Inhaltstyp nur zuverlässig erkennen, wenn sie moderne Browser filtern, die Fetch metadata request headersunterstützen.
$object-subrequest
(entfernt)
Der Modifikator $object-subrequest
wurde entfernt und wird nicht mehr unterstützt. Regeln mit einem solchen Modifikator werden als ungültig betrachtet. Die Regel entspricht Anfragen von Browser-Plugins (in der Regel handelt es sich um Flash).
$webrtc
(entfernt)
This modifier is removed and is no longer supported. Regeln mit einem solchen Modifikator werden als ungültig betrachtet. If you need to suppress WebRTC, consider using the nowebrtc
scriptlet.
Die Regel gilt nur für WebRTC-Verbindungen.
Beispiele
||example.com^$webrtc,domain=example.org
sperrt webRTC-Verbindungen zuexample.com
vonexample.org
.@@*$webrtc,domain=example.org
deaktiviert den RTC-Wrapper fürexample.org
.
Modifikatoren für Ausschlussregeln
Ausschlussregeln deaktivieren die anderen Grundregeln für die Adressen, denen sie entsprechen. They begin with a @@
mark. Alle oben aufgeführten Basismodifikatoren können auf sie angewendet werden und sie verfügen auch über einige spezielle Modifikatoren.
Wir empfehlen auch, sich mit dem Adblock Plus Filter Tabellenblatt vertraut zu machen, um besser zu verstehen, wie solche Regeln erstellt werden sollten.
Modifikator \ Produkte | CoreLibs-Apps | AdGuard für Chromium | AdGuard für Chrome MV3 | AdGuard für Firefox | AdGuard für iOS | AdGuard für Safari | AdGuard-Inhaltsblocker |
---|---|---|---|---|---|---|---|
$content | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
$elemhide | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$extension | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$jsinject | ✅ | ✅ | ✅ *[1] | ✅ | ✅ | ✅ | ❌ |
$stealth | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
$urlblock | ✅ | ✅ | ❌ | ✅ | ✅ *[2] | ✅ *[2] | ❌ |
$genericblock | ✅ | ✅ | ✅ | ✅ | ✅ *[3] | ✅ *[3] | ❌ |
$generichide | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$specifichide | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — vollständig unterstützt
- ✅ * — unterstützt, aber die Zuverlässigkeit kann variieren oder es können Einschränkungen auftreten; weitere Einzelheiten finden Sie in der Beschreibung des Modifikators
- ❌ — nicht unterstützt
$content
Deaktiviert HTML-Filterung, $hls
, $replace
und $jsonprune
Regeln auf den Seiten, die der Regel entsprechen.
Beispiele
@@||example.com^$content
deaktiviert alle inhaltsverändernden Regeln auf den Seitenexample.com
und allen ihren Subdomains.
$elemhide
Deaktiviert alle kosmetischen Regeln auf den Seiten, auf die die Regel zutrifft.
Beispiele
@@||example.com^$elemhide
deaktiviert alle kosmetischen Regeln auf den Seitenexample.com
und allen Subdomains.
Sie können einen kürzeren Namen (Alias) verwenden, anstatt den vollständigen Namen des Modifikators zu verwenden: $ehide
.
$extension
Deaktiviert bestimmte Benutzerskripte oder alle Benutzerskripte für eine bestimmte Domain.
Syntax
$extension[="userscript_name1"[|"userscript_name2"[|"userscript_name3"[...]]]]
userscript_name(i)
steht für einen bestimmten Benutzerskript-Namen, der durch den Modifikator deaktiviert werden soll. Der Modifikator kann eine beliebige Anzahl von Benutzerskriptnamen oder keinen enthalten. Im letzteren Fall deaktiviert der Modifikator alle Benutzerskripte.
Benutzerskriptnamen enthalten normalerweise Leerzeichen oder andere Sonderzeichen, weshalb Sie den Namen in Anführungszeichen setzen sollten. Both single ('
) and double ("
) ASCII quotes are supported. Mehrere Benutzerskriptnamen sollten durch einen senkrechten Strich (|
) getrennt werden. Wenn der Name eines Benutzerskripts jedoch ein einzelnes Wort ohne Sonderzeichen ist, kann er ohne Anführungszeichen verwendet werden.
Sie können ein Benutzerskript auch ausschließen, indem Sie ihm ein ~
Zeichen voranstellen. In diesem Fall wird das Benutzerskript nicht durch den Modifikator deaktiviert.
$extension=~"userscript name"
Wenn Sie ein Benutzerskript ausschließen, müssen Sie ~
außerhalb der Anführungszeichen setzen.
Wenn der Name eines Benutzerskripts Anführungszeichen ("
), Kommas (,
) oder Pipes (|
) enthält, müssen diese mit einem Backslash (\
) maskiert werden.
$extension="userscript name\, with \"quote\""
Beispiele
@@||example.com^$extension="AdGuard Assistant"
disables theAdGuard Assistant
userscript onexample.com
website.@@||example.com^$extension=MyUserscript
disables theMyUserscript
userscript onexample.com
website.@@||example.com^$extension='AdGuard Assistant'|'AdGuard Popup Blocker'
disables bothAdGuard Assistant
andAdGuard Popup Blocker
userscripts onexample.com
website.@@||example.com^$extension=~"AdGuard Assistant"
disables all user scripts onexample.com
website, exceptAdGuard Assistant
.@@||example.com^$extension=~"AdGuard Assistant"|~"AdGuard Popup Blocker"
disables all user scripts onexample.com
website, exceptAdGuard Assistant
andAdGuard Popup Blocker
.@@||example.com^$extension
no userscript will work on webpages onexample.com
.@@||example.com^$extension="AdGuard \"Assistant\""
disables theAdGuard "Assistant"
userscript onexample.com
website.
- Nur AdGuard für Windows, Mac, Android ist technisch in der Lage, Regeln mit dem Modifikator
$extension
zu verwenden. - Rules with
$extension
modifier with specific userscript name are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.13 or later.
$jsinject
Verhindert das Hinzufügen von JavaScript-Code zur Seite. Weitere Informationen zu Scriptlets und Javascript-Regeln finden Sie weiter unten.
Beispiele
@@||example.com^$jsinject
disables javascript on pages atexample.com
and all subdomains.
$jsinject
modifier limitations
Rules with the $jsinject
modifier cannot be converted to DNR in AdGuard for Chrome MV3. We only use them in the TSUrlFilter engine to disable some cosmetic rules.
The $jsinject
modifier is not supported by AdGuard for Chrome MV3 (yet) and AdGuard Content Blocker.
$stealth
Disables the Tracking protection (formerly Stealth Mode) module for all corresponding pages and requests.
Syntax
$stealth [= opt1 [| opt2 [| opt3 [...]]]]
opt(i)
stehen für bestimmte Tracking-Schutzoptionen, die von dem Modifikator deaktiviert werden. Der Modifikator kann eine beliebige Anzahl von spezifischen Optionen (siehe unten) oder keine enthalten. Im letzteren Fall deaktiviert der Modifikator alle Tracking-Schutzfunktionen.
Die Liste der verfügbaren Modifikatoroptionen:
searchqueries
disables Hide your search queries optiondonottrack
disables Ask websites not to track you option3p-cookie
disables Self-destructing third-party cookies option1p-cookie
disables Self-destructing first-party cookies option3p-cache
disables Disable cache for third-party requests option3p-auth
disables Block third-party Authorization header optionwebrtc
disables Block WebRTC optionpush
deaktiviert die Option Push API blockierenlocation
deaktiviert die Option Standort-API blockierenflash
deaktiviert die Option Flash blockierenjava
deaktiviert die Option Java blockierenreferrer
disables Hide Referer from third parties optionuseragent
disables Hide your User-Agent optionip
disables Hide your IP address optionxclientdata
disables Remove X-Client-Data header from HTTP requests optiondpi
disables Protect from DPI option
Beispiele
@@||example.com^$stealth
disables Tracking protection forexample.com
(and subdomains) requests, except for blocking cookies and hiding tracking parameters (see below).@@||domain.com^$script,stealth,domain=example.com
disables Tracking protection only for script requests todomain.com
(and its subdomains) onexample.com
and all its subdomains.@@||example.com^$stealth=3p-cookie|dpi
disables blocking third-party cookies and DPI fooling measures forexample.com
.
Blocking cookies and removing tracking parameters is achieved by using rules with the $cookie
, $urltransform
and $removeparam
modifiers. Exception rules that contain only the $stealth
modifier will not do these things. If you want to completely disable all Tracking protection features for a given domain, you must include all three modifiers: @@||example.org^$stealth,removeparam,cookie
.
- Modifier options must be lowercase, i.e.
$stealth=DPI
will be rejected. - Modifier options cannot be negated, i.e.
$stealth=~3p-cookie
will be rejected. - AdGuard Browser Extension supports only
searchqueries
,donottrack
,referrer
,xclientdata
,1p-cookie
and3p-cookie
options.
- Tracking protection (formerly Stealth Mode) is available in AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard Browser Extension for Firefox and Chromium-based browsers, except AdGuard for Chrome MV3. All other products will ignore the rules with
$stealth
modifier. - Rules with
$stealth
modifier with specific options are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.10 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
$urlblock
Disables blocking of all requests sent from the pages matching the rule and disables all $cookie
rules.
Beispiele
@@||example.com^$urlblock
— any requests sent from the pages atexample.com
and all subdomains are not going to be blocked.
$urlblock
modifier limitations
In AdGuard for iOS and AdGuard for Safari, rules with $urlblock
work as $document exclusion — unblock everything.
Rules with $urlblock
modifier are not supported by AdGuard Content Blocker, and AdGuard for Chrome MV3.
Generic rules
Before we can proceed to the next modifiers, we have to make a definition of generic rules. The rule is generic if it is not limited to specific domains. Das Platzhalterzeichen *
wird ebenfalls unterstützt.
For example, these rules are generic:
###banner
*###banner
#@#.adsblock
*#@#.adsblock
~domain.com###banner
||domain.com^
||domain.com^$domain=~example .com
Und diese nicht:
domain.com###banner
||domain.com^$domain=example.com
$genericblock
Disables generic basic rules on pages that correspond to exception rule.
Beispiele
@@||example.com^$genericblock
disables generic basic rules on any pages atexample.com
and all subdomains.
$genericblock
modifier limitations
In AdGuard for iOS and AdGuard for Safari, rules with $genericblock
work as $document exclusion — unblock everything.
Rules with $genericblock
modifier are not supported by AdGuard Content Blocker, and AdGuard for Chrome MV3.
$generichide
Disables all generic cosmetic rules on pages that correspond to the exception rule.
Beispiele
@@||example.com^$generichide
disables generic cosmetic rules on any pages atexample.com
and its subdomains.
You may use a shorter name (alias) instead of using the full modifier name: $ghide
.
specifichide
Deaktiviert alle spezifischen Regeln zum Ausblenden von Elementen und alle CSS-Regeln, jedoch nicht die allgemeinen. Hat einen entgegengesetzten Effekt zu $generichide
.
Beispiele
@@||example.org^$specifichide
disablesexample.org##.banner
but not##.banner
.
You may use a shorter name (alias) instead of using the full modifier name: $shide
.
All cosmetic rules — not just specific ones — can be disabled by $elemhide
modifier.
Rules with $specifichide
modifier are not supported by AdGuard for iOS, AdGuard for Safari, and AdGuard Content Blocker.
Erweiterte Fähigkeiten
These modifiers are able to completely change the behavior of basic rules.
Modifikator \ Produkte | CoreLibs-Apps | AdGuard für Chromium | AdGuard für Chrome MV3 | AdGuard für Firefox | AdGuard für iOS | AdGuard für Safari | AdGuard-Inhaltsblocker |
---|---|---|---|---|---|---|---|
$all | ✅ | ✅ | ✅ *[1] | ✅ | ✅ | ✅ | ❌ |
$badfilter | ✅ | ✅ | ✅ *[2] | ✅ | ✅ | ✅ | ❌ |
$cookie | ✅ | ✅ | ✅ *[3] | ✅ | ❌ | ❌ | ❌ |
$csp | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$hls | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$inline-font | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$inline-script | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$jsonprune | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$xmlprune | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$network | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$permissions | ✅ *[4] | ✅ | ✅ | ✅ *[4] | ❌ | ❌ | ❌ |
$redirect | ✅ | ✅ | ✅ *[5] | ✅ | ❌ | ❌ | ❌ |
$redirect-rule | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
$referrerpolicy | ✅ | ❌ | ⏳ | ❌ | ❌ | ❌ | ❌ |
$removeheader | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
$removeparam | ✅ | ✅ | ✅ *[6] | ✅ | ❌ | ❌ | ❌ |
$replace | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
$urltransform | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
noop | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$empty 👎 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$mp4 👎 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — vollständig unterstützt
- ✅ * — unterstützt, aber die Zuverlässigkeit kann variieren oder es können Einschränkungen auftreten; weitere Einzelheiten finden Sie in der Beschreibung des Modifikators
- ⏳ — Funktion, deren Implementierung geplant ist, die aber noch in keinem Produkt verfügbar ist
- ❌ — nicht unterstützt
- 👎 — veraltet; wird noch unterstützt, aber in Zukunft entfernt
$all
$all
modifier is made of all content-types modifiers and $popup
. z.B. rule ||example.org^$all
is converting into rule:
||example.org^$document,subdocument,font,image,media,object,other,ping,script,stylesheet,websocket,xmlhttprequest,popup
This modifier cannot be used as an exception with the @@
mark.
Einschränkungen des Modifikators $all
Since $popup
is a part if $all
, the $all
modifier is not supported by AdGuard for Chrome MV3 because of $popup
modifier limitations.
Rules with $all
modifier are not supported by AdGuard Content Blocker.
$badfilter
The rules with the $badfilter
modifier disable other basic rules to which they refer. It means that the text of the disabled rule should match the text of the $badfilter
rule (without the $badfilter
modifier).
Beispiele
||example.com$badfilter
disables||example.com
||example.com$image,badfilter
deaktiviert||example.com$image
@@||example.com$badfilter
deaktiviert@@||example.com
||example.com$domain=domain.com,badfilter
deaktiviert||example.com$domain=domain.com
Rules with $badfilter
modifier can disable other basic rules for specific domains if they fulfill the following conditions:
- The rule has a
$domain
modifier - The rule does not have a negated domain
~
in$domain
modifier value
In that case, the $badfilter
rule will disable the corresponding rule for domains specified in both the $badfilter
and basic rules. Please note that wildcard-TLD logic works here as well.
Beispiele
/some$domain=example.com|example.org|example.io
is disabled forexample.com
by/some$domain=example.com,badfilter
/some$domain=example.com|example.org|example.io
is disabled forexample.com
andexample.org
by/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org
and/some$domain=example.io
are disabled completely by/some$domain=example.com|example.org|example.io,badfilter
/some$domain=example.com|example.org|example.io
is disabled completely by/some$domain=example.*,badfilter
/some$domain=example.*
is disabled forexample.com
andexample.org
by/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org|example.io
is NOT disabled forexample.com
by/some$domain=example.com|~example.org,badfilter
because the value of$domain
modifier contains a negated domain
Einschränkungen des Modifikators $badfilter
In AdGuard for Chrome MV3 a rule with the $badfilter
modifier is applied in DNR only if it fully cancels the source rule. We cannot calculate it if it is only partially canceled. Examples
Rules with $badfilter
modifier are not supported by AdGuard Content Blocker.
$cookie
The $cookie
modifier completely changes rule behavior. Instead of blocking a request, this modifier makes AdGuard suppress or modify the Cookie
and Set-Cookie
headers.
Multiple rules matching a single request
In case if multiple $cookie
rules match a single request, we will apply each of them one by one.
Syntax
$cookie [= name[; maxAge = seconds [; sameSite = strategy ]]]
mit:
name
— optional, string or regular expression to match cookie name.seconds
— number of seconds for current time to offset the expiration date of cookie.strategy
— string for Same-Site strategy to be applied to the cookie.
For example,
||example.org^$cookie=NAME;maxAge=3600;sameSite=lax
every time AdGuard encounters a cookie called NAME
in a request to example.org
, it will do the following:
- Set its expiration date to current time plus
3600
seconds - Makes the cookie use Same-Site "lax" strategy.
Escapen von Sonderzeichen
Wenn regulärer Ausdruck name
zum Abgleichen verwendet wird, müssen zwei Zeichen umgangen werden: Komma ,
und Dollarzeichen $
. Verwenden Sie einen Backslash \
, um jeden von ihnen zu escapen. For example, escaped comma looks like this: \,
.
Beispiele
||example.org^$cookie
blocks all cookies set byexample.org
; this is an equivalent to settingmaxAge=0
$cookie=__cfduid
blocks CloudFlare cookie everywhere$cookie=/__utm[a-z]/
blocks Google Analytics cookies everywhere||facebook.com^$third-party,cookie=c_user
prevents Facebook from tracking you even if you are logged in
There are two methods to deactivate $cookie
rules: the primary method involves using an exception marked with @@
— @@||example.org^$cookie
. The alternative method employs a $urlblock
exception (also included under the $document
exception alias — $elemhide,jsinject,content,urlblock,extension
). So funktioniert es:
@@||example.org^$cookie
unblocks all cookies set byexample.org
@@||example.org^$urlblock
unblocks all cookies set byexample.org
and disables blocking of all requests sent fromexample.org
@@||example.org^$cookie=concept
unblocks a single cookie namedconcept
@@||example.org^$cookie=/^_ga_/
unblocks every cookie that matches the regular expression
$cookie
modifier limitations
In AdGuard for Chrome MV3 we delete cookies in 2 ways: from content-script
side (to which we have access) and from onBeforeSendHeaders
listener. Since onBeforeSendHeaders
and other listeners are no longer blocking, we are not able to delete them in all cases. You can check if a rule works with this test.
$cookie
rules support these types of modifiers: $domain
, $~domain
, $important
, $third-party
, $~third-party
, strict-third-party
, and strict-first-party
.
Rules with $cookie
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
$csp
Dieser Modifikator ändert das Verhalten der Regel vollständig. Wenn sie auf eine Regel angewendet wird, blockiert die Regel die entsprechende Anfrage nicht. Response headers will be modified instead.
In order to use this type of rules, it is required to have the basic understanding of the Content Security Policy security layer.
For the requests matching a $csp
rule, we will strengthen response security policy by enhancing the content security policy, similar to the content security policy of the $csp
modifier contents. $csp
rules are applied independently from any other rule type. Only document-level exceptions can influence it (see the examples section), but no other basic rules.
Multiple rules matching a single request
In case if multiple $csp
rules match a single request, we will apply each of them.
Syntax
$csp
value syntax is similar to the Content Security Policy header syntax.
$csp
value can be empty in the case of exception rules. Siehe den Abschnitt mit den Beispielen unten.
Beispiele
||example.org^$csp=frame-src 'none'
blocks all frames on example.org and its subdomains.@@||example.org/page/*$csp=frame-src 'none'
disables all rules with the$csp
modifier exactly matchingframe-src 'none'
on all the pages matching the rule pattern. Zum Beispiel, die Regel oben.@@||example.org/page/*$csp
disables all the$csp
rules on all the pages matching the rule pattern.||example.org^$csp=script-src 'self' 'unsafe-eval' http: https:
disables inline scripts on all the pages matching the rule pattern.@@||example.org^$document
or@@||example.org^$urlblock
disables all the$csp
rules on all the pages matching the rule pattern.
- There are a few characters forbidden in the
$csp
value:,
,$
. $csp
rules support three types of modifiers:$domain
,$important
,$subdocument
.- Rules with
report-*
directives are considered invalid.
Rules with $csp
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS and AdGuard for Safari.
$hls
$hls
rules modify the response of a matching request. They are intended as a convenient way to remove segments from HLS playlists (RFC 8216).
The word "segment" in this document means either a "Media Segment" or a "playlist" as part of a "Master Playlist": $hls
rules do not distinguish between a "Master Playlist" and a "Media Playlist".
Syntax
||example.org^$hls=urlpattern
entfernt Segmente, deren URL mit dem URL-Musterurlpattern
übereinstimmt. The pattern works just like the one in basic URL rules, however, the characters/
,$
and,
must be escaped with\
insideurlpattern
.||example.org^$hls=/regexp/options
removes segments where the URL or one of the tags (for certain options, if present) is matched by the regular expressionregexp
. FolgendeOptionen
sind verfügbar:t
— instead of testing the segment's URL, test each of the segment's tags against the regular expression. A segment with a matching tag is removed;i
— make the regular expression case-insensitive.
The characters /
, $
and ,
must be escaped with \
inside regexp
.
Exceptions
Basic URL exceptions shall not disable rules with $hls
modifier. They can be disabled as described below:
@@||example.org^$hls
disables all$hls
rules for responses from URLs matching||example.org^
.@@||example.org^$hls=text
disables all$hls
rules with the value of the$hls
modifier equal totext
for responses from URLs matching||example.org^
.
$hls
rules can also be disabled by $document
, $content
and $urlblock
exception rules.
When multiple $hls
rules match the same request, their effect is cumulative.
Beispiele
||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads
removes all segments with the matching URL.||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i
achieves more or less the same with a regular expression instead of a URL pattern.||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
entfernt alle Segmente, die ein übereinstimmendes Tag haben.
Anatomy of an HLS playlist
Eine kurze Zusammenfassung der Spezifikation:
- Eine HLS-Playlist ist eine Sammlung von Textzeilen
- Eine Zeile kann leer sein, ein Kommentar (beginnt mit
#
), ein Tag (beginnt ebenfalls mit#
, kann nur anhand des Namens erkannt werden) oder eine URL - A URL line is called a "segment"
- Tags may apply to a single segment, i.e. the first URL line after the tag, to all segments following the tag and until the tag with the same name, or to the whole playlist
Some points specific to the operation of $hls
rules:
- When a segment is removed, all of the tags that apply only to that segment are also removed
- When there is a tag that applies to multiple segments, and all of those segments are removed, the tag is also removed
- Since there is no way to recognize different kinds of tags by syntax, we recognize all of the tags specified by the RFC, plus some non-standard tags that we have seen in the field. Any lines starting with
#
and not recognized as a tag are passed through without modification, and are not matched against the rules - Tags will not be matched if they apply to the entire playlist, and
$hls
rules cannot be used to remove them, as these rule types are intended for segment removals. If you know what you are doing, you can use$replace
rules to remove or rewrite just a single tag from the playlist
An example of a transformation done by the rules:
Ursprüngliche Antwort
#EXTM3U
#EXT-X-TARGETDURATION:10
#EXTINF,5
preroll.ts
#UPLYNK-SEGMENT:abc123,ad
#UPLYNK-KEY:aabb1122
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#UPLYNK-SEGMENT:abc123,segment
#UPLYNK-KEY:ccdd2233
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#EXT-X-ENDLIST
Angewandte Regeln
||example.org^$hls=preroll
||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
Geänderte Antwort
#EXTM3U
#EXT-X-TARGETDURATION:10
#UPLYNK-SEGMENT:abc123,segment
#UPLYNK-KEY:ccdd2233
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#EXT-X-ENDLIST
- Regeln mit dem Modifikator
$hls
können nur in vertrauenswürdigen Filtern verwendet werden. $hls
rules are compatible with the modifiers$domain
,$third-party
,$strict-third-party
,$strict-first-party
,$app
,$important
,$match-case
, and$xmlhttprequest
only.$hls
rules only apply to HLS playlists, which are UTF-8 encoded text starting with the line#EXTM3U
. Any other response will not be modified by these rules.$hls
rules do not apply if the size of the original response is more than 10 MB.
Rules with the $hls
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.10 or later.
$inline-script
The $inline-script
modifier is designed to block inline JavaScript embedded into the web page, using Content Security Policy (CSP). It improves security and privacy by preventing application of inline ads or potentially malicious scripts. Die Regel ||example.org^$inline-script
wird in die CSP-Syntaxregel umgewandelt:
||example.org^$csp=script-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
$inline-font
Der $inline-font
-Modifikator wurde entwickelt, um Inline-Fonts, die in die Webseite eingebettet sind, mit Hilfe der Content Security Policy (CSP) zu sperren. It improves security and privacy by preventing application of inline fonts that could be used for data collection and fingerprinting. The rule ||example.org^$inline-font
is converting into the CSP-syntax rule:
||example.org^$csp=font-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
$jsonprune
$jsonprune
rules modify the response to a matching request by removing JSON items that match a modified JSONPath expression. They do not modify responses which are not valid JSON documents.
In AdGuard for Windows, Mac, and Android with CoreLibs v1.11 or later, $jsonprune
also supports modifying JSONP (padded JSON) documents.
Syntax
||example.org^$jsonprune=expression
removes items that match the modified JSONPath expressionexpression
from the response.
Due to the way rule parsing works, the characters $
and ,
must be escaped with \
inside expression
.
The modified JSONPath syntax has the following differences from the original:
- Skriptausdrücke werden nicht unterstützt
- Die unterstützten Filterausdrücke sind:
?(has <key>)
— true if the current object has the specified key?(key-eq <key> <value>)
— true if the current object has the specified key, and its value is equal to the specified value?(key-substr <key> <value>)
— true if the specified value is a substring of the value of the specified key of the current object
- Whitespace outside of double- or single-quoted strings has no meaning
- Both double- and single-quoted strings can be used
- Expressions ending with
..
are not supported - Multiple array slices can be specified in square brackets
There are various online tools that make working with JSONPath expressions more convenient:
https://www.site24x7.com/tools/jsonpath-finder-validator.html https://jsonpathfinder.com/ https://jsonpath.com/
Keep in mind, though, that all JSONPath implementations have unique features/quirks and are subtly incompatible with each other.
Exceptions
Basic URL exceptions shall not disable rules with the $jsonprune
modifier. They can be disabled as described below:
@@||example.org^$jsonprune
disables all$jsonprune
rules for responses from URLs matching||example.org^
.@@||example.org^$jsonprune=text
disables all$jsonprune
rules with the value of the$jsonprune
modifier equal totext
for responses from URLs matching||example.org^
.
$jsonprune
rules can also be disabled by $document
, $content
and $urlblock
exception rules.
When multiple $jsonprune
rules match the same request, they are sorted in lexicographical order, the first rule is applied to the original response, and each of the remaining rules is applied to the result of applying the previous one.
Beispiele
||example.org^$jsonprune=\$..[one\, "two three"]
removes all occurrences of the keys "one" and "two three" anywhere in the JSON document.
Eingabe
{
"one": 1,
"two": {
"two three": 23,
"four five": 45
}
}
Ausgabe
{
"two": {
"four five": 45
}
}
||example.org^$jsonprune=\$.a[?(has ad_origin)]
removes all children ofa
that have anad_origin
key.
Eingabe
{
"a": [
{
"ad_origin": "https://example.org",
"b": 42
},
{
"b": 1234
}
]
}
Ausgabe
{
"a": [
{
"b": 1234
}
]
}
||example.org^$jsonprune=\$.*.*[?(key-eq 'Some key' 'Some value')]
removes all items that are at nesting level 3 and have a property "Some key" equal to "Some value".
Eingabe
{
"a": {"b": {"c": {"Some key": "Some value"}, "d": {"Some key": "Other value"}}},
"e": {"f": [{"Some key": "Some value"}, {"Some key": "Other value"}]}
}
Ausgabe
{
"a": {"b": {"d": {"Some key": "Other value"}}},
"e": {"f": [{"Some key": "Other value"}]}
}
Nested JSONPath expressions
In AdGuard for Windows, Mac and Android with CoreLibs v1.11 or later, JSONPath expressions may be used as keys in filter expressions.
||example.org^$jsonprune=\$.elems[?(has "\$.a.b.c")]
removes all children ofelems
which have a property selectable by the JSONPath expression$.a.b.c
.
Eingabe
{
"elems": [
{
"a": {"b": {"c": 123}},
"k": "v"
},
{
"d": {"e": {"f": 123}},
"k1": "v1"
}
]
}
Ausgabe
{
"elems": [
{
"d": {"e": {"f": 123}},
"k1": "v1"
}
]
}
||example.org^$jsonprune=\$.elems[?(key-eq "\$.a.b.c" "abc")]
removes all children ofelems
which have a property selectable by the JSONPath expression$.a.b.c
with a value equal to"abc"
.
Eingabe
{
"elems": [
{
"a": {"b": {"c": 123}}
}
]
}
Ausgabe
{
"elems": [
{
"a": {"b": {"c": 123}}
}
]
}
$jsonprune
rules are only compatible with these modifiers:$domain
,$third-party
,$strict-third-party
,$strict-first-party
,$app
,$important
,$match-case
, and$xmlhttprequest
.$jsonprune
rules do not apply if the size of the original response is greater than 10 MB.
Rules with the $jsonprune
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.10 or later.
$xmlprune
$xmlprune
rules modify the response to a matching request by removing XML items that match an XPath 1.0 expression. The expression must return a node-set. $xmlprune
rules do not modify responses which are not well-formed XML documents.
Syntax
||example.org^$xmlprune=expression
removes items that match the XPath expressionexpression
from the response.
Due to the way rule parsing works, the characters $
and ,
must be escaped with \
inside expression
.
Exceptions
Basic URL exceptions shall not disable rules with the $xmlprune
modifier. They can be disabled as described below:
@@||example.org^$xmlprune
disables all$xmlprune
rules for responses from URLs matching||example.org^
.@@||example.org^$xmlprune=text
disables all$xmlprune
rules with the value of the$xmlprune
modifier equal totext
for responses from URLs matching||example.org^
.
$xmlprune
rules can also be disabled by $document
, $content
and $urlblock
exception rules.
When multiple $xmlprune
rules match the same request, they are applied in lexicographical order.
Beispiele
||example.org^$xmlprune=/bookstore/book[position() mod 2 = 1]
removes odd-numbered books from the bookstore.
Eingabe
<?xml version="1.0" encoding="UTF-8"?>
<bookstore>
<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>
<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>
<book category="web">
<title lang="en">XQuery Kick Start</title>
<author>James McGovern</author>
<author>Per Bothner</author>
<author>Kurt Cagle</author>
<author>James Linn</author>
<author>Vaidyanathan Nagarajan</author>
<year>2003</year>
<price>49.99</price>
</book>
<book category="web">
<title lang="en">Learning XML</title>
<author>Erik T. Ray</author>
<year>2003</year>
<price>39.95</price>
</book>
</bookstore>
Ausgabe
<?xml version="1.0" encoding="UTF-8"?>
<bookstore>
<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>
<book category="web">
<title lang="en">Learning XML</title>
<author>Erik T. Ray</author>
<year>2003</year>
<price>39.95</price>
</book>
</bookstore>
||example.org^$xmlprune=/bookstore/book[year = 2003]
removes books from the year 2003 from the bookstore.
Eingabe
<?xml version="1.0" encoding="UTF-8"?>
<bookstore>
<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>
<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>
<book category="web">
<title lang="en">XQuery Kick Start</title>
<author>James McGovern</author>
<author>Per Bothner</author>
<author>Kurt Cagle</author>
<author>James Linn</author>
<author>Vaidyanathan Nagarajan</author>
<year>2003</year>
<price>49.99</price>
</book>
<book category="web">
<title lang="en">Learning XML</title>
<author>Erik T. Ray</author>
<year>2003</year>
<price>39.95</price>
</book>
</bookstore>
Ausgabe
<?xml version="1.0" encoding="UTF-8"?>
<bookstore>
<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>
<book category="children">
<title lang="en">Harry Potter</title>
<author>J K. Rowling</author>
<year>2005</year>
<price>29.99</price>
</book>
</bookstore>
||example.org^$xmlprune=//*/@*
removes all attributes from all elements.
Eingabe
<?xml version="1.0" encoding="UTF-8"?>
<bookstore location="cy">
<book category="cooking">
<title lang="en">Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>
</bookstore>
Ausgabe
<?xml version="1.0" encoding="UTF-8"?>
<bookstore>
<book>
<title>Everyday Italian</title>
<author>Giada De Laurentiis</author>
<year>2005</year>
<price>30.00</price>
</book>
</bookstore>
$xmlprune
rules are only compatible with these modifiers:$domain
,$third-party
,$strict-third-party
,$strict-first-party
,$app
,$important
,$match-case
, and$xmlhttprequest
.$xmlprune
rules do not apply if the size of the original response is greater than 10 MB.
Rules with the $xmlprune
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.15 or later.
$network
This is basically a Firewall-like rule allowing to fully block or unblock access to a specified remote address.
$network
rules match IP addresses only! You cannot use them to block or unblock access to a domain.- To match an IPv6 address, you have to use the collapsed syntax, e.g. use
[2001:4860:4860::8888]$network
instead of[2001:4860:4860:0:0:0:0:8888]$network
. - An allowlist
$network
rule makes AdGuard bypass data to the matching endpoint, hence there will be no further filtering at all. - If the IP part starts and ends with
/
character, it is treated as a regular expression.
We recommend to get acquainted with this article for better understanding of regular expressions.
The $network
modifier can only be used in rules together with the $app
and $important
modifiers, and not with any other modifiers.
Beispiele
174.129.166.49:3478^$network
blocks access to174.129.166.49:3478
(but not to174.129.166.49:34788
).[2001:4860:4860::8888]:443^$network
blocks access to[2001:4860:4860::8888]:443
.174.129.166.49$network
blocks access to174.129.166.49:*
.@@174.129.166.49$network
makes AdGuard bypass data to the endpoint. No other rules will be applied./.+:3[0-9]{4}/$network
blocks access to any port from 30000 to 39999./8.8.8.(:?8|4)/$network
blocks access to both8.8.8.8
and8.8.8.4
.
Only AdGuard for Windows, Mac, and Android are technically capable of using rules with $network
modifier.
$permissions
Dieser Modifikator ändert das Verhalten der Regel vollständig. Wenn er auf eine Regel angewendet wird, blockiert die Regel die entsprechende Anfrage nicht. Response headers will be modified instead.
In order to use this type of rules, it is required to have a basic understanding of the Permissions Policy security layer.
For the requests matching a $permissions
rule, AdGuard strengthens response's permissions policy by adding an additional permission policy equal to the $permissions
modifier contents. $permissions
rules are applied independently from any other rule type. Only document-level exceptions can influence it (see the examples section), but no other basic rules.
Syntax
$permissions
value syntax is identical to that of the Permissions-Policy
header syntax with the following exceptions:
- A comma that separates multiple features MUST be escaped — see examples below.
- A pipe character (
|
) can be used instead of a comma to separate features.
The list of available directives is available here.
$permissions
value can be empty in the case of exception rules — see examples below.
Beispiele
||example.org^$permissions=autoplay=()
disallows autoplay media requested through theHTMLMediaElement
interface acrossexample.org
.@@||example.org/page/*$permissions=autoplay=()
disables all rules with the$permissions
modifier exactly matchingautoplay=()
on all the pages matching the rule pattern. Zum Beispiel, die Regel oben. It is important to note that the exception rule only takes effect in the case of an exact value match. For example, if you want to disable the rule$permissions=a=()\,b=()
, you need exception rule@@$permissions=a=()\,b=()
, and not@@$permissions=b=()\,a=()
, nor@@$permissions=b=()
becauseb=()\,a=()
orb=()
does not match witha=()\,b=()
.@@||example.org/page/*$permissions
disables all the$permissions
rules on all the pages matching the rule pattern.$domain=example.org|example.com,permissions=storage-access=()\, camera=()
disallows using the Storage Access API to request access to unpartitioned cookies and using video input devices acrossexample.org
andexample.com
.$domain=example.org|example.com,permissions=storage-access=()|camera=()
does the same — a|
can be used to separate the features instead of an escaped comma.@@||example.org^$document
or@@||example.org^$urlblock
disables all the$permission
rules on all the pages matching the rule pattern.
$permissions
rules only take effect for main frame and sub frame requests. This means they are applied when a page is loaded or when an iframe is loaded.
If there are multiple $permissions
rules that match the same request, multiple Permissions-Policy
headers will be added to the response for each rule with their $permissions
value. So if you have two rules: ||example.org^$permissions=autoplay=()
and ||example.org^$permissions=geolocation=()\,camera=()
that match the same request, the response will contain two Permissions-Policy
headers: autoplay=()
and geolocation=()\,camera=()
.
$permissions
modifier limitations
Firefox ignores the Permissions-Policy
header. For more information, see this issue.
- Characters forbidden in the
$permissions
value:$
. $permissions
is compatible with a limited set of modifiers:$domain
,$important
,$subdocument
, and content-type modifiers.$permissions
rules that do not have any content-type modifiers will match only requests where content type isdocument
.
- Rules with the
$permissions
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.11 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later. - Pipe separator
|
instead of escaped comma is supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.14 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
$redirect
AdGuard is able to redirect web requests to a local "resource".
Syntax
AdGuard uses the same filtering rule syntax as uBlock Origin. Also, it is compatible with ABP $rewrite=abp-resource
modifier.
$redirect
is a modifier for the basic filtering rules so rules with this modifier support all other basic modifiers like $domain
, $third-party
, $script
, etc.
The value of the $redirect
modifier must be the name of the resource that will be used for redirection.
Disabling $redirect
rules
||example.org/script.js$script,redirect=noopjs
— this rule redirects all requests toexample.org/script.js
to the resource namednoopjs
.||example.org/test.mp4$media,redirect=noopmp4-1s
— this rule redirects all requests toexample.org/test.mp4
to the resource namednoopmp4-1s
.@@||example.org^$redirect
will disable all$redirect
rules for URLs that match||example.org^
.@@||example.org^$redirect=nooptext
will disable all rules with$redirect=nooptext
for any request that matches||example.org^
.
More information on redirects and their usage is available on GitHub.
Prioritäten der $redirect
-Regeln
$redirect
rules have higher priority than regular basic blocking rules. This means that if there is a basic blocking rule, the $redirect
rule will override it. Allowlist rules with @@
mark have higher priority than $redirect
rules. If a basic rule with the $important
modifier and the $redirect
rule matches the same URL, the latter is overridden unless it's also marked as $important
.
In short: $important
> @@
> $redirect
> basic rules
.
Go to rules priorities for more details.
$redirect
modifier limitations
In AdGuard for Chrome MV3 allowlist rules with $redirect
are not supported.
- Rules with
$redirect
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari . $redirect
in uBlock Origin supports specifying priority, e.g.$redirect=noopjs:42
. AdGuard does not support it and instead just discards the priority postfix.
$redirect-rule
This is basically an alias to $redirect
since it has the same "redirection" values and the logic is almost similar. The difference is that $redirect-rule
is applied only in the case when the target request is blocked by a different basic rule.
Go to rules priorities for more details.
Negating $redirect-rule
works exactly the same way as for regular $redirect
rules. Even more than that, @@||example.org^$redirect
will negate both $redirect
and $redirect-rule
rules.
Beispiele
||example.org/script.js
||example.org^$redirect-rule=noopjs
In this case, only requests to example.org/script.js
will be "redirected" to noopjs
. All other requests to example.org
will be kept intact.
Rules with $redirect-rule
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, AdGuard for Safari, and AdGuard for Chrome MV3. The discussion about adding support for $redirect-rule
rules in Chrome MV3 extensions is currently open.
$referrerpolicy
These rules allow overriding of a page's referrer policy. Responses to matching requests will have all of their Referrer-Policy
headers replaced with a single header with the value equal to the matching rule's modifier value. If the response carries an HTML document with a <meta name="referrer"...
tag, the content
attribute of the tag will also be replaced with the modifier value.
An exception rule with a modifier value disables the blocking rule with the same modifier value. An exception rule without a modifier value disables all matched referrer-policy rules.
If a request matches multiple $referrerpolicy
rules not disabled by exceptions, only one of them (it is not specified which one) is applied. $referrerpolicy
rules without specified content-type modifiers apply to $document
and $subdocument
content types.
Beispiele
||example.com^$referrerpolicy=unsafe-url
overrides the referrer policy forexample.com
withunsafe-url
.@@||example.com^$referrerpolicy=unsafe-url
disables the previous rule.@@||example.com/abcd.html^$referrerpolicy
disables all$referrerpolicy
rules onexample.com/abcd.html
.
Rules with the $referrerpolicy
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.12 or later.
$removeheader
Rules with $removeheader
modifier are intended to remove headers from HTTP requests and responses. The initial motivation for this rule type is to be able to get rid of the Refresh
header which is often used to redirect users to an undesirable location. However, this is not the only case where this modifier can be useful.
Just like $csp
, $redirect
, $removeparam
, and $cookie
, this modifier exists independently, rules with it do not depend on the regular basic rules, i.e. regular exception or blocking rules will not affect it. By default, it only affects response headers. However, you can also change it to remove headers from HTTP requests as well.
Syntax
Grundlegende Syntax
||example.org^$removeheader=header-name
removes a response header calledheader-name
||example.org^$removeheader=request:header-name
removes a request header calledheader-name
$removeheader
is case-insensitive, but we suggest always using lower case.
Negating $removeheader
This type of rules works pretty much the same way it works with $csp
and $redirect
modifiers.
Use @@
to negate $removeheader
:
@@||example.org^$removeheader
negates all$removeheader
rules for URLs that match||example.org^
.@@||example.org^$removeheader=header
negates the rule with$removeheader=header
for any request matching||example.org^
.
$removeheader
rules can also be disabled by $document
and $urlblock
exception rules. But basic exception rules without modifiers will not do that. For example, @@||example.com^
will not disable $removeheader=p
for requests to example.com
, but @@||example.com^$urlblock
will.
In case of multiple $removeheader
rules matching a single request, we will apply each of them one by one.
Beispiele
||example.org^$removeheader=refresh
removesRefresh
header from all HTTP responses returned byexample.org
and its subdomains.||example.org^$removeheader=request:x-client-data
removesX-Client-Data
header from all HTTP requests.Next block of rules removes
Refresh
andLocation
headers from all HTTP responses returned byexample.org
save for requests toexample.org/path/*
, for which no headers will be removed:||example.org^$removeheader=refresh
||example.org^$removeheader=location
@@||example.org/path/$removeheader
This type of rules can only be used in trusted filters.
In order to avoid compromising the security
$removeheader
cannot remove headers from the list below:access-control-allow-origin
access-control-allow-credentials
access-control-allow-headers
access-control-allow-methods
access-control-expose-headers
access-control-max-age
access-control-request-headers
access-control-request-method
origin
timing-allow-origin
allow
cross-origin-embedder-policy
cross-origin-opener-policy
cross-origin-resource-policy
content-security-policy
content-security-policy-report-only
expect-ct
feature-policy
origin-isolation
strict-transport-security
upgrade-insecure-requests
x-content-type-options
x-download-options
x-frame-options
x-permitted-cross-domain-policies
x-powered-by
x-xss-protection
public-key-pins
public-key-pins-report-only
sec-websocket-key
sec-websocket-extensions
sec-websocket-accept
sec-websocket-protocol
sec-websocket-version
p3p
sec-fetch-mode
sec-fetch-dest
sec-fetch-site
sec-fetch-user
referrer-policy
content-type
content-length
accept
accept-encoding
host
connection
transfer-encoding
upgrade
$removeheader
rules are only compatible with$domain
,$third-party
,$strict-third-party
,$strict-first-party
,$app
,$important
,$match-case
, and content type modifiers such as$script
and$stylesheet
. The rules which have any other modifiers are considered invalid and will be discarded.
Rules with $removeheader
modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard Browser Extension for Chrome, Firefox, and Edge.
$removeparam
$queryprune
is an alias of $removeparam
. Since $queryprune
is deprecated, avoid using it and use $removeparam
instead.
Rules with $removeparam
modifier are intended to strip query parameters from requests' URLs. Please note that such rules are only applied to GET
, HEAD
, OPTIONS
, and sometimes POST
requests.
Syntax
Grundlegende Syntax
$removeparam=param
removes query parameter with the nameparam
from URLs of any request, e.g. a request tohttp://example.com/page?param=1&another=2
will be transformed intohttp://example.com/page?another=2
.
Regular expressions
You can also use regular expressions to match query parameters and/or their values:
$removeparam=/regexp/[options]
— removes query parameters that matches theregexp
regular expression from URLs of any request. Unlike basic syntax, it means "remove query parameters normalized to aname=value
string which match theregexp
regular expression".[options]
here is the list of regular expression options. At the moment, the only supported option isi
which makes matching case-insensitive.
Escapen von Sonderzeichen
Do not forget to escape special characters like ,
, /
and $
in the regular expressions. Use \
character for that purpose. For example, an escaped comma should look like this: \,
.
Regexp-type rules target both name and value of the parameter. To minimize mistakes, it is safer to start every regexp with /^
unless you specifically target parameter values.
We will try to detect and ignore unescaped $
automatically using a simple rule of thumb — it is not an options delimiter if all three are true:
- It looks like
$/
- There is another slash character
/
to the left of it - There is another unescaped dollar sign
$
to the left of that slash character
Remove all query parameters
Specify naked $removeparam
to remove all query parameters:
||example.org^$removeparam
— removes all query parameters from URLs matching||example.org^
.
Inversion
Use ~
to apply inversion:
$removeparam=~param
— removes all query parameters with the name different fromparam
.$removeparam=~/regexp/
— removes all query parameters that do not match theregexp
regular expression.
Negating $removeparam
This sort of rules work pretty much the same way it works with $csp
and $redirect
modifiers.
Use @@
to negate $removeparam
:
@@||example.org^$removeparam
negates all$removeparam
rules for URLs that match||example.org^
.@@||example.org^$removeparam=param
negates the rule with$removeparam=param
for any request matching||example.org^
.@@||example.org^$removeparam=/regexp/
negates the rule with$removeparam=/regexp/
for any request matching||example.org^
.
Multiple rules matching a single request
In the case when multiple $removeparam
rules match a single request, each of them will be applied one by one.
Beispiele
$removeparam=/^(utm_source|utm_medium|utm_term)=/
$removeparam=/^(utm_content|utm_campaign|utm_referrer)=/
@@||example.com^$removeparam
With these rules some UTM parameters will be stripped out from any request, except that requests to example.com
will not be stripped at all, e.g. http://google.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img
will be transformed to http://google.com/page
, but http://example.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img
will not be affected by the blocking rule.
$removeparam=utm_source
removesutm_source
query parameter from all requests.$removeparam=/utm_.*/
removes allutm_* query
parameters from URL queries of any request, e.g. a request tohttp://example.com/page?utm_source=test
will be transformed tohttp://example.com/page
.$removeparam=/^utm_source=campaign$/
removesutm_source
query parameter with the value equal tocampaign
. It does not touch otherutm_source
parameters.
Negating one $removeparam
rule and replacing it with a different rule
$removeparam=/^(gclid|yclid|fbclid)=/
@@||example.com^$removeparam=/^(gclid|yclid|fbclid)=/
||example.com^$removeparam=/^(yclid|fbclid)=/
With these rules, Google, Yandex, and Facebook Click IDs will be removed from all requests. There is one exception: Google Click ID (gclid) will not be removed from requests to example.com.
Negating $removeparam
for all parameters
$removeparam=/^(utm_source|utm_medium|utm_term)=/
$removeparam=/^(utm_content|utm_campaign|utm_referrer)=/
@@||example.com^$removeparam
With these rules, specified UTM parameters will be removed from any request save for requests to example.org
.
$removeparam
rules can also be disabled by $document
and $urlblock
exception rules. But basic exception rules without modifiers do not do that. For example, @@||example.com^
will not disable $removeparam=p
for requests to example.com, but @@||example.com^$urlblock
will.
$removeparam
modifier limitations
AdGuard for Chrome MV3 has some limitations:
Regular expressions, negation and allowlist rules are not supported.
Group of similar
$removeparam
rules will be combined into one. Beispiel:||testcases.adguard.com$xmlhttprequest,removeparam=p1case1
||testcases.adguard.com$xmlhttprequest,removeparam=p2case1
||testcases.adguard.com$xmlhttprequest,removeparam=P3Case1
$xmlhttprequest,removeparam=p1case2wird umgewandelt in
[
{
"id": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": {
"queryTransform": {
"removeParams": [
"p1case1",
"p2case1",
"P3Case1"
]
}
}
}
},
"condition": {
"urlFilter": "||testcases.adguard.com",
"resourceTypes": [
"xmlhttprequest"
],
"isUrlFilterCaseSensitive": false
}
},
{
"id": 4,
"action": {
"type": "redirect",
"redirect": {
"transform": {
"queryTransform": {
"removeParams": [
"p1case2"
]
}
}
}
},
"condition": {
"resourceTypes": [
"xmlhttprequest"
],
"isUrlFilterCaseSensitive": false
}
}
]
- Rules with the
$removeparam
modifier can only be used in trusted filters. $removeparam
rules are compatible with basic modifiers, content-type modifiers, and with the$important
and$app
modifiers. Rules with any other modifiers are considered invalid and will be discarded.$removeparam
rules without content type modifiers will only match requests where the content type isdocument
.
- Rules with
$removeparam
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.7 or later, and AdGuard Browser Extension v3.6 or later. $removeparam
syntax for regular expressions is supported AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.8 or later, and AdGuard Browser Extension v4.0 or later.POST
request types are supported only by AdGuard for Windows, Mac, and Android with CoreLibs v1.10 or later, and AdGuard Browser Extension with TSWebExtension v0.4.6 or later.
$replace
Dieser Modifikator ändert das Verhalten der Regel vollständig. If it is applied, the rule will not block the request. The response is going to be modified instead.
You will need some knowledge of regular expressions to use $replace
modifier.
Funktionen
$replace
rules apply to any text response, but will not apply to binary (media
,image
,object
, etc.).$replace
rules do not apply if the size of the original response is more than 10 MB.$replace
rules have a higher priority than other basic rules (including exception rules). So if a request natches two different rules, one of which has the$replace
modifier, this rule will be applied.- Document-level exception rules with
$content
or$document
modifiers do disable$replace
rules for requests matching them. - Other document-level exception rules (
$generichide
,$elemhide
or$jsinject
modifiers) are applied alongside$replace
rules. It means that you can modify the page content with a$replace
rule and disable cosmetic rules there at the same time.
$replace
value can be empty in the case of exception rules. See examples section for further information.
Multiple rules matching a single request
In case if multiple $replace
rules match a single request, we will apply each of them. The order is defined alphabetically.
Syntax
In general, $replace
syntax is similar to replacement with regular expressions in Perl.
replace = "/" regexp "/" replacement "/" modifiers
regexp
— a regular expression.replacement
— a string that will be used to replace the string corresponding toregexp
.modifiers
— a regular expression flags. For example,i
— insensitive search, ors
— single-line mode.
In the $replace
value, two characters must be escaped: comma ,
and dollar sign $
. Use backslash \
for it. For example, an escaped comma looks like this: \,
.
Beispiele
||example.org^$replace=/(<VAST[\s\S]*?>)[\s\S]*<\/VAST>/\$1<\/VAST>/i
Es gibt drei Teile in dieser Regel:
regexp
—(<VAST(.|\s)*?>)(.|\s)*<\/VAST>
;replacement
—\$1<\/VAST>
, wo$
maskiert ist;modifiers
—i
for insensitive search.
Hier können Sie sehen, wie diese Regel funktioniert: http://regexr.com/3cesk
Multiple $replace
rules
||example.org^$replace=/X/Y/
||example.org^$replace=/Z/Y/
@@||example.org/page/*$replace=/Z/Y/
- Regel 1 und 2 werden auf alle Anfragen angewendet, die an
example.org
gesendet werden. - Rule 2 is disabled for requests matching
||example.org/page/
, but rule 1 still works!
Disabling $replace
rules
@@||example.org^$replace
will disable all$replace
rules matching||example.org^
.@@||example.org^$document
or@@||example.org^$content
will disable all$replace
rules originated from pages ofexample.org
including the page itself.
Rules with the $replace
modifier can only be used in trusted filters.
Rules with $replace
modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard Browser Extension for Firefox. Such rules do not work in extensions for other browsers because they are unable to modify content on the network level.
$urltransform
The $urltransform
rules allow you to modify the request URL by replacing text matched by a regular expression.
Funktionen
$urltransform
rules normally only apply to the path and query parts of the URL, see below for one exception.$urltransform
will not be applied if the original URL is blocked by other rules.$urltransform
will be applied before$removeparam
rules.
The $urltransform
value can be empty for exception rules.
Multiple rules matching a single request
If multiple $urltransform
rules match a single request, we will apply each of them. The order is defined alphabetically.
Syntax
$urltransform
syntax is similar to replacement with regular expressions in Perl.
urltransform = "/" regexp "/" replacement "/" modifiers
regexp
— a regular expression.replacement
— a string that will be used to replace the string corresponding toregexp
.modifiers
— a regular expression flags. For example,i
— insensitive search, ors
— single-line mode.
In the $urltransform
value, two characters must be escaped: the comma ,
and the dollar sign $
. Use the backslash character \
for this. For example, an escaped comma looks like this: \,
.
Changing the origin
This section only applies to AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.17 or later.
As stated above, normally $urltransform
rules are only allowed to change the path and query parts of the URL. However, if the rule's regexp
begins with the string ^http
, then the full URL is searched and can be modified by the rule. Such a rule will not be applied if the URL transformation can not be achieved via an HTTP redirect (for example, if the request's method is POST
).
Beispiele
||example.org^$urltransform=/(pref\/).*\/(suf)/\$1\$2/i
Es gibt drei Teile in dieser Regel:
regexp
—(pref\/).*\/(suf)
;replacement
—\$1\$2
where$
is escaped;modifiers
—i
for insensitive search.
Multiple $urltransform
rules
||example.org^$urltransform=/X/Y/
||example.org^$urltransform=/Z/Y/
@@||example.org/page/*$urltransform=/Z/Y/
- Regel 1 und 2 werden auf alle Anfragen angewendet, die an
example.org
gesendet werden. - Regel 2 ist deaktiviert für Anfragen, die mit
||example.org/page/
übereinstimmen, aber Regel 1 funktioniert weiterhin.
Re-matching rules after transforming the URL
After applying all matching $urltransform
rules, the transformed request will be matched against all other rules:
E.g., with the following rules:
||example.com^$urltransform=/firstpath/secondpath/
||example.com/secondpath^
the request to https://example.com/firstpath
will be blocked.
Disabling $urltransform
rules
@@||example.org^$urltransform
will disable all$urltransform
rules matching||example.org^
.@@||example.org^$urltransform=/Z/Y/
will disable the rule with$urltransform=/Z/Y/
for any request matching||example.org^
.
$urltransform
rules can also be disabled by $document
and $urlblock
exception rules. But basic exception rules without modifiers do not do that. For example, @@||example.com^
will not disable $urltransform=/X/Y/
for requests to example.com, but @@||example.com^$urlblock
will.
Rules with the $urltransform
modifier can only be used in trusted filters.
Rules with the $urltransform
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.15 or later.
noop
noop
modifier does nothing and can be used solely to increase rules' readability. It consists of a sequence of underscore characters (_
) of arbitrary length and can appear in a rule as often as needed.
Beispiele
||example.com$_,removeparam=/^ss\\$/,_,image
||example.com$replace=/bad/good/,___,~third-party
Rules with noop
modifier are not supported by AdGuard Content Blocker.
$empty
(deprecated)
This modifier is deprecated in favor of the $redirect
modifier. Rules with $empty
are still supported and being converted into $redirect=nooptext
now but the support shall be removed in the future.
Usually, blocked requests look like a server error to browser. If you use $empty
modifier, AdGuard will emulate a blank response from the server with200 OK
status.
Beispiele
||example.org^$empty
returns an empty response to all requests toexample.org
and all subdomains.
Rules with $empty
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
$mp4
(veraltet)
This modifier is deprecated in favor of the $redirect
modifier. Rules with $mp4
are still supported and being converted into $redirect=noopmp4-1s,media
now but the support shall be removed in the future.
As a response to blocked request AdGuard returns a short video placeholder.
Beispiele
||example.com/videos/$mp4
blocks all video downloads from||example.com/videos/*
and changes the response to a video placeholder.
Rules with $mp4
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
Regelprioritäten
Each rule has its own priority, which is necessary when several rules match the request and the filtering engine needs to select one of them. Priority is measured by a positive integer.
When two rules with the same priority match the same request, the filter engine implementation determines which one is chosen.
The concept of rule priorities becomes increasingly important in light of Manifest V3, as the existing rules need to be converted to declarativeNetRequest rules.
Berechnung der Prioritäten
Um die Priorität zu berechnen, haben wir die Modifikatoren in verschiedene Gruppen kategorisiert. Diese Gruppen werden entsprechend ihrer Priorität, von niedrig nach hoch, eingestuft. A modifier that significantly narrows the scope of a rule adds more weight to its total priority. Conversely, if a rule applies to a broader range of requests, its priority decreases.
It's worth noting that there are cases where a single-parameter modifier has a higher priority than multi-parameter ones. For instance, in the case of $domain=example.com|example.org
, a rule that includes two domains has a slightly broader effective area than a rule with one specified domain, therefore its priority is lower.
Die Basispriorität jeder Regel beträgt 1. Wenn die berechnete Priorität eine Fließkommazahl ist, wird sie aufgerundet auf die kleinste ganze Zahl, die größer oder gleich der berechneten Priorität ist.
- The concept of priority has been introduced in TSUrlFilter v2.1.0 and CoreLibs v1.13. Before that AdGuard didn't have any special priority computation algorithm and collisions handling could be different depending on AdGuard product and version.
- AdGuard für iOS, Safari und der AdGuard Inhaltsblocker verlassen sich auf die Implementierung der Browser und können den hier angegebenen Regeln nicht folgen.
Modifikator-Aliase (1p
, 3p
, usw.) sind nicht in diesen Kategorien enthalten, werden jedoch innerhalb der Engine zur Berechnung der Regelpriorität verwendet.
Basic modifiers, the presence of each adds 1 to the priority
$app
with negated applications using~
,$denyallow
,$domain
with negated domains using~
,$match-case
,$method
with negated methods using~
,$strict-first-party
,$strict-third-party
,$third-party
,$to
,- restricted content-types with
~
.
When dealing with a negated domain, app, method, or content-type, we add 1 point for the existence of the modifier itself, regardless of the quantity of negated domains or content-types. This is because the rule's scope is already infinitely broad. Put simply, by prohibiting multiple domains, content-types, methods or apps, the scope of the rule becomes only minimally smaller.
Defined content-type modifiers, defined methods, defined headers, $all, $popup, specific exceptions
All valid content types:
$document
,$font
,$image
,$media
,$object
,$other
,$ping
,$script
,$stylesheet
,$subdocument
,$websocket
,$xmlhttprequest
;
This also includes rules that implicitly add all content types:
$all
;
Or rules that implicitly add the modifier $document
:
Or some specific exceptions that implicitly add $document,subdocument
:
Or allowed methods via $method
.
Or rules with $header
.
The presence of any content-type modifiers adds (50 + 50 / N)
, where N
is the number of modifiers present, for example: ||example.com^$image,script
will add 50 + 50 / 2 = 50 + 25 = 75
to the total weight of the rule.
The $all
also belongs to this category, because it implicitly adds all content type modifiers, e.g., $document,subdocument,image,script,media,<etc>
+ $popup
.
The $popup
also belongs to this category, because it implicitly adds the modifier $document
. Similarly, specific exceptions add $document,subdocument
.
If there is a $method
modifier in the rule with allowed methods it adds (50 + 50 / N)
, where N
is the number of methods allowed, for example: ||example.com^$method=GET|POST|PUT
will add 50 + 50 / 3 = 50 + 16.6 = 67
to the total weight of the rule.
If there is a $header
modifier in the rule, it adds 50
.
$domain
or $app
with allowed domains or applications
Specified domains through $domain
or specified applications through $app
add 100 + 100 / N
, where N
is the number of modifier values for example: ||example.com^$domain=example.com|example.org|example.net
will add 100 + 100 / 3 = 134.3 = 135
or ||example.com^$app=org.example.app1|org.example.app2
will add 100 + 100 / 2 = 151
or ||example.com^$domain=example.com,app=org.example.app1|org.example.app2
will add 100 + 100/1
($domain part) and 100 + 100/2
($app part), totaling 350
.
Modifier values that are regexps or tld will be interpreted as normal entries of the form example.com
and counted one by one, for example: ||example.com^$domain=example.*
will add 100 + 100 / 1 = 200
or ||example.com^$domain=example.*|adguard.*
will add 100 + 100 / 2 = 150
.
$redirect
-Regeln
Each of which adds 10^3
to rule priority.
Specific exceptions
Each of which adds 10^4
to the priority.
As well as exception with $document modifier
: because it's an alias for $elemhide,content,jsinject,urlblock,extension
. It will add 10^4
for each modifier from the top list, 10^4 * 5
in total.
In addition, each of these exceptions implicitly adds the two allowed content-type modifiers $document,subdocument
.
Allowlist rules
Modifier @@
adds 10^5
to rule priority.
$important
rules
Modifier $important
adds 10^6
to rule priority.
Rules for which there is no priority weight
Other modifiers, which are supposed to perform additional post- or pre-processing of requests, do not add anything to the rules priority.
Beispiele
||example.com^
Gewicht der Regel ohne Modifikatoren:
1
.||example.com^$match-case
Regelgewicht: Basisgewicht + Gewicht des Modifikators aus Kategorie 1:
1 + 1 = 2
.||example.org^$removeparam=p
Rule weight: base weight + 0, since $removeparam is not involved in the priority calculation:
1 + 0 = 1
.||example.org^$document,redirect=nooptext
Rule weight: base weight + allowed content type, category 3 + $redirect from category 6:
1 + (100 + 100 / 1) + 1000 = 1201
.@@||example.org^$removeparam=p,document
Rule weight: base weight + allowlist rule, category 5 + 0 because $removeparam is not involved in the priority calculation + allowed content type, category 2:
1 + 10000 + 0 + (50 + 50 / 1) = 10101
.@@||example.com/ad/*$domain=example.org|example.net,important
Rule weight: base weight + allowlist rule, category 5 + important rule, category 7 + allowed domains, category 3:
1 + 10000 + 1000000 + (100 + 100 / 2) = 1010152
.@@||example.org^$document
without additional modifiers is an alias for@@||example.com^$elemhide,content,jsinject,urlblock,extension
Rule weight: base weight + specific exceptions, category 4 + two allowed content types (document and subdocument), category 2:
1 + 10000 * 4 + (50 + 50 / 2) = 40076
.*$script,domain=a.com,denyallow=x.com|y.com
Rule weight: base weight + allowed content type, category 2 + allowed domain, category 3 + denyallow, category 1:
1 + (50 + 50/1) + (100 + 100 / 1) + 1 = 303
.||example.com^$all
— alias to||example.com^$document,subdocument,image,script,media,etc. + $popup
Rule weight: base weight + popup (category 1) + allowed content types (category 2):
1 + 1 + (50 + 50/12) = 55
.
Non-basic rules
However, basic rules may not be enough to block ads. Sometimes you need to hide an element or change part of the HTML code of a web page without breaking anything. The rules described in this section are created specifically for this purpose.
Categories \ Products | CoreLibs-Apps | AdGuard für Chromium | AdGuard für Chrome MV3 | AdGuard für Firefox | AdGuard für iOS | AdGuard für Safari | AdGuard-Inhaltsblocker |
---|---|---|---|---|---|---|---|
Element hiding | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
CSS-Regeln | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
Extended CSS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
HTML filtering | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
JavaScript | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
Skriptlets | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
- ✅ — vollständig unterstützt
- ❌ — nicht unterstützt
Kosmetische Regeln
Work with non-basic rules requires the basic knowledge of HTML and CSS. So, if you want to learn how to make such rules, we recommend to get acquainted with this documentation.
Element hiding rules
Element hiding rules are used to hide the elements of web pages. It is similar to applying { display: none; }
style to selected element.
Element hiding rules may operate differently depending on the platform.
Syntax
rule = [domains] "##" selector
domains = [domain0, domain1[, ...[, domainN]]]
selector
— CSS selector, defines the elements to be hidden.domains
— domain restriction for the rule.
If you want to limit the rule application area to certain domains, just enter them separated with commas. For example: example.org,example.com##selector
.
This rule will be also applied to all subdomains of example.org
and example.com
.
Wenn Sie möchten, dass die Regel nicht auf bestimmte Domains angewendet wird, beginnen Sie einen Domainnamen mit dem Tilde-Zeichen ~
. For example: ~example.org##selector
.
You can use both approaches in a single rule. For example, example.org,~subdomain.example.org##domain
will work for example.org
and all subdomains, except subdomain.example.org
.
Element hiding rules are not dependent on each other. If there is a rule example.org##selector
in the filter and you add ~example.org##selector
both rules will be applied independently.
Beispiele
example.com##div.textad
— hides adiv
with the classtextad
atexample.com
and all subdomains.example.com,example.org###adblock
— hides an element with attributeid
equalsadblock
atexample.com
,example.org
and all subdomains.~example.com##.textad
— hides an element with the classtextad
at all domains, exceptexample.com
and its subdomains.
Beschränkungen
Safari does not support both allowed and disallowed domains. So the rules like example.org,~foo.example.org##.textad
are invalid in AdGuard for Safari.
Exceptions
Exceptions can disable some rules on particular domains. They are very similar to usual exception rules, but instead of ##
you have to use #@#
.
For example, there is a rule in filter:
##.textad
If you want to disable it for example.com
, you can create an exception rule:
example.com#@#.textad
Sometimes, it may be necessary to disable all restriction rules. For example, to conduct tests. To do this, use the exclusion rule without specifying a domain. It will completely disable matching CSS elemhide rule on ALL domains:
#@#.textad
The same can be achieved by adding this rule:
*#@#.textad
We recommend to use this kind of exceptions only if it is not possible to change the hiding rule itself. In other cases it is better to change the original rule, using domain restrictions.
CSS-Regeln
Sometimes, simple hiding of an element is not enough to deal with advertising. For example, blocking an advertising element can just break the page layout. In this case AdGuard can use rules that are much more flexible than hiding rules. With these rules you can basically add any CSS styles to the page.
Syntax
rule = [domains] "#$#" selector "{" style "}"
domains = [domain0, domain1[, ...[, domainN]]]
selector
— CSS selector, that defines the elements we want to apply the style to.domains
— domain restriction for the rule. Same principles as in element hiding rules.style
— CSS style, that we want to apply to selected elements.
Beispiele
example.com#$#body { background-color: #333!important; }
This rule will apply a style background-color: #333!important;
to the body
element at example.com
and all subdomains.
Exceptions
Just like with element hiding, there is a type of rules that disable the selected CSS style rule for particular domains. Exception rule syntax is almost the same, you just have to change #$#
to #@$#
.
For example, there is a rule in filter:
#$#.textad { visibility: hidden; }
If you want to disable it for example.com
, you can create an exception rule:
example.com#@$#.textad { visibility: hidden; }
We recommend to use this kind of exceptions only if it is not possible to change the CSS rule itself. In other cases it is better to change the original rule, using domain restrictions.
Styles that lead to loading any resource are forbidden. Basically, it means that you cannot use any <url>
type of value in the style.
CSS rules are not supported by AdGuard Content Blocker.
CSS rules may operate differently depending on the platform.
Erweiterte CSS-Selektoren
- Beschränkungen
- Pseudo-class
:has()
- Pseudo-class
:contains()
- Pseudo-class
:matches-css()
- Pseudo-class
:matches-attr()
- Pseudo-class
:matches-property()
- Pseudo-class
:xpath()
- Pseudo-class
:nth-ancestor()
- Pseudo-class
:upward()
- Pseudo-class
:remove()
and pseudo-propertyremove
- Pseudo-class
:is()
- Pseudo-class
:not()
- Pseudo-class
:if-not()
(removed)
CSS 3.0 is not always enough to block ads. To solve this problem AdGuard extends CSS capabilities by adding support for the new pseudo-elements. We have developed a separate open-source library for non-standard element selecting and applying CSS styles with extended properties.
The idea of extended capabilities is an opportunity to match DOM elements with selectors based on their own representation (style, text content, etc.) or relations with other elements. There is also an opportunity to apply styles with non-standard CSS properties.
Anwendungsbereich
Extended selectors can be used in any cosmetic rule, whether they are element hiding rules or CSS rules.
Rules with extended CSS selectors are not supported by AdGuard Content Blocker.
Syntax
Regardless of the CSS pseudo-classes you are using in the rule, you can use special markers to force applying these rules by ExtendedCss. It is recommended to use these markers for all extended CSS cosmetic rules so that it was easier to find them.
The syntax for extended CSS rules:
#?#
— for element hiding,#@?#
— for exceptions#$?#
— for CSS rules,#@$?#
— for exceptions
We strongly recommend using these markers any time when you use an extended CSS selector.
Beispiele
example.org#?#div:has(> a[target="_blank"][rel="nofollow"])
— this rule blocks alldiv
elements containing a child node that has a link with the attributes[target="_blank"][rel="nofollow"]
. The rule applies only toexample.org
and its subdomains.example.com#$?#h3:contains(cookies) { display: none!important; }
— this rule sets the styledisplay: none!important
to allh3
elements that contain the wordcookies
. The rule applies only toexample.com
and all its subdomains.example.net#?#.banner:matches-css(width: 360px)
— this rule blocks all.banner
elements with the style propertywidth: 360px
. The rule applies only toexample.net
and its subdomains.example.net#@?#.banner:matches-css(width: 360px)
— this rule will disable the previous rule.
You can apply standard CSS selectors using the ExtendedCss library by using the rule marker #?#
, e.g. #?#div.banner
.
Learn more about how to debug extended selectors.
Some pseudo-classes do not require selector before it. Still adding the universal selector *
makes an extended selector easier to read, even though it has no effect on the matching behavior. So selector #block :has(> .inner)
works exactly like #block *:has(> .inner)
, but the second one is more obvious.
Pseudo-class names are case-insensitive, e.g. :HAS()
works as :has()
. Still the lower-case names are used commonly.
ExtendedCss Limitations
Specific pseudo-class may have its own limitations:
:has()
,:xpath()
,:nth-ancestor()
,:upward()
,:is()
,:not()
, and:remove()
.
Pseudo-class :has()
Draft CSS 4.0 specification describes the :has()
pseudo-class. Unfortunately, it is not yet supported by all popular browsers.
Rules with the :has()
pseudo-class must use the native implementation of :has()
if they use ##
marker and if it is possible, i.e. with no other extended selectors inside. To force applying of ExtendedCss rules with :has()
, use #?#
/#$?#
marker explicitly.
Compatibility with other pseudo-classes
Synonyms :-abp-has()
is supported by ExtendedCss for better compatibility.
:if()
is no longer supported as a synonym for :has()
.
Syntax
[target]:has(selector)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementselector
— required, standard or extended CSS selector
The pseudo-class :has()
selects the target
elements that fit to the selector
. Also the selector
can start with a combinator.
A selector list can be set in selector
as well. In this case all selectors in the list are being matched for now. In the future it will be fixed for <forgiving-relative-selector-list>
as argument.
:has()
limitations
Usage of the :has()
pseudo-class is restricted for some cases (2, 3):
- disallow
:has()
inside the pseudos accepting only compound selectors; - disallow
:has()
after regular pseudo-elements.
Native :has()
pseudo-class does not allow :has()
, :is()
, :where()
inside :has()
argument to avoid increasing the :has()
invalidation complexity (case 1). But ExtendedCss did not have such limitation earlier and filter lists already contain such rules, so we have not added this limitation to ExtendedCss and allow to use :has()
inside :has()
as it was possible before. To use it, just force ExtendedCss usage by setting #?#
/#$?#
rule marker.
Native implementation does not allow any usage of :scope
inside the :has()
argument ([1], [2]). Still, there are some such rules in filter lists: div:has(:scope a)
which we continue to support by simply converting them to div:has(> a)
, as it used to be done previously.
Beispiele
div:has(.banner)
selects all div
elements which include an element with the banner
class:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<span class="banner">inner element</span>
</div>
div:has(> .banner)
selects all div
elements which include an banner
class element as a direct child of div
:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<p class="banner">child element</p>
</div>
div:has(+ .banner)
selects all div
elements preceding banner
class element which immediately follows the div
and both are children of the same parent:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected</div>
<p class="banner">adjacent sibling</p>
<span>Not selected</span>
div:has(~ .banner)
selects all div
elements preceding banner
class element which follows the div
but not necessarily immediately and both are children of the same parent:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected</div>
<span>Not selected</span>
<p class="banner">general sibling</p>
div:has(span, .banner)
selects all div
elements which include both span
element and banner
class element:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<span>child span</span>
<p class="banner">child .banner</p>
</div>
Backward compatible syntax for :has()
is supported but not recommended.
Pseudo-class :contains()
The :contains()
pseudo-class principle is very simple: it allows to select the elements that contain specified text or which content matches a specified regular expression. Regexp flags are supported.
The :contains()
pseudo-class uses the textContent
element property for matching, not the innerHTML
.
Compatibility with other pseudo-classes
Synonyms :-abp-contains()
and :has-text()
are supported for better compatibility.
Syntax
[target]:contains(match)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementmatch
— required, string or regular expression for matching elementtextContent
. Regular expression flags are supported.
Beispiele
Für solche DOM:
<!-- HTML code -->
<div>Not selected</div>
<div id="match">Selected as IT contains "banner"</div>
<div>Not selected <div class="banner"></div></div>
the element div#match
can be selected by any of these extended selectors:
! plain text
div:contains(banner)
! regular expression
div:contains(/as .*banner/)
! regular expression with flags
div:contains(/it .*banner/gi)
Only the div
with id=match
is selected because the next element does not contain any text, and banner
is a part of code, not a text.
Backward compatible syntax for :contains()
is supported but not recommended.
Pseudo-class :matches-css()
The :matches-css()
pseudo-class allows to match the element by its current style properties. The work of the pseudo-class is based on using the Window.getComputedStyle()
method.
Syntax
[target]:matches-css([pseudo-element, ] property: pattern)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementpseudo-element
— optional, valid standard pseudo-element, e.g.before
,after
,first-line
, etc.property
— required, a name of CSS property to check the element forpattern
— required, a value pattern that is using the same simple wildcard matching as in the basic URL filtering rules or a regular expression. For this type of matching, AdGuard always does matching in a case-insensitive manner. In the case of a regular expression, the pattern looks like/regexp/
.
Special characters escaping and unescaping
For non-regexp patterns (
,)
,[
,]
must be unescaped, e.g. :matches-css(background-image:url(data:*))
.
For regexp patterns \
should be escaped, e.g. :matches-css(background-image: /^url\\("data:image\\/gif;base64.+/)
.
Beispiele
Für solche DOM:
<!-- HTML code -->
<style type="text/css">
#matched::before {
content: "Block me"
}
</style>
<div id="matched"></div>
<div id="not-matched"></div>
the div
elements with pseudo-element ::before
and with specified content
property can be selected by any of these extended selectors:
! string pattern
div:matches-css(before, content: block me)
! string pattern with wildcard
div:matches-css(before, content: block*)
! regular expression pattern
div:matches-css(before, content: /block me/)
Regexp patterns do not support flags.
Obsolete pseudo-classes :matches-css-before()
and :matches-css-after()
are no longer recommended but still are supported for better compatibility.
Backward compatible syntax for :matches-css()
is supported but not recommended.
Pseudo-class :matches-attr()
The :matches-attr()
pseudo-class allows selecting an element by its attributes, especially if they are randomized.
Syntax
[target]:matches-attr("name"[="value"])
target
— optional, standard or extended CSS selector, can be skipped for checking any elementname
— required, simple string or string with wildcard or regular expression for attribute name matchingvalue
— optional, simple string or string with wildcard or regular expression for attribute value matching
Escapen von Sonderzeichen
For regexp patterns "
and \
should be escaped, e.g. div:matches-attr(class=/[\\w]{5}/)
.
Beispiele
div:matches-attr("ad-link")
selects the element div#target1
:
<!-- HTML code -->
<div id="target1" ad-link="1random23-banner_240x400"></div>
div:matches-attr("data-*"="adBanner")
selects the element div#target2
:
<!-- HTML code -->
<div id="target2" data-1random23="adBanner"></div>
div:matches-attr(*unit*=/^click$/)
selects the element div#target3
:
<!-- HTML code -->
<div id="target3" random123-unit094="click"></div>
*:matches-attr("/.{5,}delay$/"="/^[0-9]*$/")
selects the element #target4
:
<!-- HTML code -->
<div>
<inner-random23 id="target4" nt4f5be90delay="1000"></inner-random23>
</div>
Regexp patterns do not support flags.
Pseudo-class :matches-property()
The :matches-property()
pseudo-class allows selecting an element by matching its properties.
Syntax
[target]:matches-property("name"[="value"])
target
— optional, standard or extended CSS selector, can be skipped for checking any elementname
— required, simple string or string with wildcard or regular expression for element property name matchingvalue
— optional, simple string or string with wildcard or regular expression for element property value matching
Escapen von Sonderzeichen
For regexp patterns "
and \
must be escaped, e.g. div:matches-property(prop=/[\\w]{4}/)
.
Regexp patterns are supported in name
for any property in chain, e.g. prop./^unit[\\d]{4}$/.type
.
Beispiele
An element with such properties:
divProperties = {
id: 1,
check: {
track: true,
unit_2random1: true,
},
memoizedProps: {
key: null,
tag: 12,
_owner: {
effectTag: 1,
src: 'ad.com',
},
},
};
can be selected by any of these extended selectors:
div:matches-property(check.track)
div:matches-property("check./^unit_.{4,8}$/")
div:matches-property("check.unit_*"=true)
div:matches-property(memoizedProps.key="null")
div:matches-property(memoizedProps._owner.src=/ad/)
To check properties of a specific element, do the following:
- Inspect the page element or select it in
Elements
tab of browser DevTools - Run
console.dir($0)
inConsole
tab
Regexp patterns do not support flags.
Pseudo-class :xpath()
The :xpath()
pseudo-class allows selecting an element by evaluating an XPath expression.
Syntax
[target]:xpath(expression)
target
- optional, standard or extended CSS selectorexpression
— required, valid XPath expression
:xpath()
limitations
target
can be omitted so it is optional. For any other pseudo-class that would mean "apply to all DOM nodes", but in case of :xpath()
it just means "apply to the whole document", and such applying slows elements selecting significantly. That's why rules like #?#:xpath(expression)
are limited to looking inside the body
tag. For example, rule #?#:xpath(//div[@data-st-area=\'Advert\'])
is parsed as #?#body:xpath(//div[@data-st-area=\'Advert\'])
.
Extended selectors with defined target
as any selector — *:xpath(expression)
— can still be used but it is not recommended, so target
should be specified instead.
Works properly only at the end of selector, except for pseudo-class :remove().
Beispiele
:xpath(//*[@class="banner"])
selects the element div#target1
:
<!-- HTML code -->
<div id="target1" class="banner"></div>
:xpath(//*[@class="inner"]/..)
selects the element div#target2
:
<!-- HTML code -->
<div id="target2">
<div class="inner"></div>
</div>
Pseudo-class :nth-ancestor()
The :nth-ancestor()
pseudo-class allows to lookup the nth ancestor relative to the previously selected element.
subject:nth-ancestor(n)
subject
— required, standard or extended CSS selectorn
— required, number >= 1 and < 256, distance to the needed ancestor from the element selected bysubject
Syntax
subject:nth-ancestor(n)
subject
— required, standard or extended CSS selectorn
— required, number >= 1 and < 256, distance to the needed ancestor from the element selected bysubject
:nth-ancestor()
limitations
The :nth-ancestor()
pseudo-class is not supported inside the argument of the :not()
pseudo-class.
Beispiele
Für solche DOM:
<!-- HTML code -->
<div id="target1">
<div class="child"></div>
<div id="target2">
<div>
<div>
<div class="inner"></div>
</div>
</div>
</div>
</div>
.child:nth-ancestor(1)
selects the element div#target1
, div[class="inner"]:nth-ancestor(3)
selects the element div#target2
.
Pseudo-class :upward()
The :upward()
pseudo-class allows to lookup the ancestor relative to the previously selected element.
Syntax
subject:upward(ancestor)
subject
— required, standard or extended CSS selectorancestor
— required, specification for the ancestor of the element selected bysubject
, can be set as:- number >= 1 and < 256 for distance to the needed ancestor, same as
:nth-ancestor()
- standard CSS selector for matching closest ancestor
- number >= 1 and < 256 for distance to the needed ancestor, same as
:upward()
limitations
The :upward()
pseudo-class is not supported inside the argument of the :not()
pseudo-class.
Beispiele
Für solche DOM:
<!-- HTML code -->
<div id="target1" data="true">
<div class="child"></div>
<div id="target2">
<div>
<div>
<div class="inner"></div>
</div>
</div>
</div>
</div>
.inner:upward(div[data])
selects the element div#target1
, .inner:upward(div[id])
selects the element div#target2
, .child:upward(1)
selects the element div#target1
, .inner:upward(3)
selects the element div#target2
.
Pseudo-class :remove()
and pseudo-property remove
Sometimes, it is necessary to remove a matching element instead of hiding it or applying custom styles. In order to do it, you can use the :remove()
pseudo-class as well as the remove
pseudo-property.
Pseudo-class :remove()
can be placed only at the end of a selector.
Syntax
! pseudo-class
selector:remove()
! pseudo-property
selector { remove: true; }
selector
— required, standard or extended CSS selector
:remove()
and remove
limitations
The :remove()
pseudo-class is limited to work properly only at the end of selector.
For applying the :remove()
pseudo-class to any element, the universal selector *
should be used. Otherwise such extended selector may be considered as invalid, e.g. .banner > :remove()
is not valid for removing any child element of banner
class element, so it should look like .banner > *:remove()
.
If the :remove()
pseudo-class or the remove
pseudo-property is used, all style properties are ignored except for the debug
pseudo-property.
Beispiele
div.banner:remove()
div:has(> div[ad-attr]):remove()
div:contains(advertisement) { remove: true; }
div[class]:has(> a > img) { remove: true; }
Rules with the remove
pseudo-property must use #$?#
marker: $
for CSS-style rule syntax, ?
for ExtendedCss syntax.
Pseudo-class :is()
The :is()
pseudo-class allows to match any element that can be selected by any of selectors passed to it. Invalid selectors are skipped and the pseudo-class deals with valid ones with no error thrown. Our implementation of the native :is()
pseudo-class.
Syntax
[target]:is(selectors)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementselectors
— forgiving selector list of standard or extended selectors. For extended selectors, only compound selectors are supported, not complex.
:is()
limitations
Rules with the :is()
pseudo-class must use the native implementation of :is()
if rules use ##
marker and it is possible, i.e. with no other extended selectors inside. To force applying ExtendedCss rules with :is()
, use #?#
/#$?#
marker explicitly.
If the :is()
pseudo-class argument selectors
is an extended selector, due to the way how the :is()
pseudo-class is implemented in ExtendedCss v2.0, it is impossible to apply it to the top DOM node which is html
, i.e. #?#html:is(<extended-selectors>)
does not work. So if target
is not defined or defined as the universal selector *
, the extended pseudo-class applying is limited to html
's children, e.g. rules #?#:is(...)
and #?#*:is(...)
are parsed as #?#html *:is(...)
. Please note that there is no such limitation for a standard selector argument, i.e. #?#html:is(.locked)
works fine.
Complex selectors with extended pseudo-classes are not supported as selectors
argument for :is()
pseudo-class, only compound ones are allowed. Check examples below for more details.
Beispiele
#container *:is(.inner, .footer)
selects only the element div#target1
:
<!-- HTML code -->
<div id="container">
<div data="true">
<div>
<div id="target1" class="inner"></div>
</div>
</div>
</div>
Due to limitations :is(*:not([class]) > .banner)'
does not work but :is(*:not([class]):has(> .banner))
can be used instead of it to select the element div#target2
:
<!-- HTML code -->
<span class="span">text</span>
<div id="target2">
<p class="banner">inner paragraph</p>
</div>
Pseudo-class :not()
The :not()
pseudo-class allows to select elements which are not matched by selectors passed as argument. Invalid argument selectors are not allowed and error is to be thrown. Our implementation of the :not()
pseudo-class.
Syntax
[target]:not(selectors)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementselectors
— list of standard or extended selectors
:not()
limitations
Rules with the :not()
pseudo-class must use the native implementation of :not()
if rules use ##
marker and it is possible, i.e. with no other extended selectors inside. To force applying ExtendedCss rules with :not()
, use #?#
/#$?#
marker explicitly.
If the :not()
pseudo-class argument selectors
is an extended selector, due to the way how the :not()
pseudo-class is implemented in ExtendedCss v2.0, it is impossible to apply it to the top DOM node which is html
, i.e. #?#html:not(<extended-selectors>)
does not work. So if target
is not defined or defined as the universal selector *
, the extended pseudo-class applying is limited to html
's children, e.g. rules #?#:not(...)
and #?#*:not(...)
are parsed as #?#html *:not(...)
. Please note that there is no such limitation for a standard selector argument, i.e. #?#html:not(.locked)
works fine.
The :not()
is considered as a standard CSS pseudo-class inside the argument of the :upward()
pseudo-class because :upward()
supports only standard selectors.
"Up-looking" pseudo-classes which are :nth-ancestor()
and :upward()
are not supported inside selectors
argument for :not()
pseudo-class.
Beispiele
#container > *:not(h2, .text)
selects only the element div#target1
:
<!-- HTML code -->
<div id="container">
<h2>Header</h2>
<div id="target1"></div>
<span class="text">text</span>
</div>
Pseudo-class :if-not()
(removed)
The :if-not()
pseudo-class is removed and is no longer supported. Regeln mit einem solchen Modifikator werden als ungültig betrachtet.
This pseudo-class was basically a shortcut for :not(:has())
. It was supported by ExtendedCss for better compatibility with some filters subscriptions.
Cosmetic rules priority
The way element hiding and CSS rules are applied is platform-specific.
In AdGuard for Windows, Mac, and Android, we use a stylesheet injected into the page. The priority of cosmetic rules is the same as any other websites' CSS stylesheet. But there is a limitation: element hiding and CSS rules cannot override inline styles. In such cases, it is recommended to use extended selectors or HTML filtering.
In AdGuard Browser Extension, the so called "user stylesheets" are used. They have higher priority than even the inline styles.
Extended CSS selectors use JavaScript to work and basically add an inline style themselves, therefore they can override any style.
HTML-Filterregeln
In most cases, the basis and cosmetic rules are enough to filter ads. But sometimes it is necessary to change the HTML-code of the page itself before it is loaded. This is when you need filtering rules for HTML content. They allow to indicate the HTML elements to be cut out before the browser loads the page.
HTML filtering rules are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard Browser Extension for Firefox. Such rules do not work in extensions for other browsers because they are unable to modify content on network level.
Syntax
selector = [tagName] [attributes] [pseudoClasses]
combinator = ">"
rule = [domains] "$$" selector *(combinator selector)
domains = [domain0, domain1[, ...[, domainN]]]
attributes = "[" name0 = value0 "]" "[" name1 = value2 "]" ... "[" nameN = valueN "]"
pseudoClasses = pseudoClass *pseudoClass
pseudoClass = ":" pseudoName [ "(" pseudoArgs ")" ]
tagName
— name of the element in lower case, for example,div
orscript
.domains
— domain restriction for the rule. Same principles as in element hiding rule syntax.attributes
— a list of attributes that limit the selection of elements.name
— attribute name,value
— substring, that is contained in attribute value.pseudoName
— the name of a pseudo-class.pseudoArgs
— the arguments of a function-style pseudo-class.combinator
— an operator that works similarly to the CSS child combinator: that is, theselector
on the right of thecombinator
will only match an element whose direct parent matches theselector
on the left of thecombinator
.
Beispiele
HTML code:
<script data-src="/banner.js"></script>
Rule:
example.org$$script[data-src="banner"]
This rule removes all script
elements with the attribute data-src
containing the substring banner
. The rule applies only to example.org
and all its subdomains.
Besondere Attribute
In addition to usual attributes, which value is every element checked for, there is a set of special attributes that change the way a rule works. Below there is a list of these attributes:
tag-content
Dieses spezielle Attribut könnte zukünftig nicht mehr unterstützt werden. Prefer using the :contains()
pseudo-class where it is available.
This is the most frequently used special attribute. It limits selection with those elements whose innerHTML code contains the specified substring.
You must use ""
to escape "
, for instance: $$script[tag-content="alert(""this is ad"")"]
For example, take a look at this HTML code:
<script type="text/javascript">
document.write('<div>banner text</div>" />');
</script>
Following rule will delete all script
elements with a banner
substring in their code:
$$script[tag-content="banner"]
The tag-content
special attribute must not appear in a selector to the left of a >
combinator.
wildcard
Dieses besondere Attribut könnte zukünftig nicht mehr unterstützt werden. Prefer using the :contains()
pseudo-class where it is available.
This special attribute works almost like tag-content
and allows you to check the innerHTML code of the document. Rule will check if HTML code of the element fits to the search pattern.
You must use ""
to escape "
, for instance: $$script[wildcard=""banner""]
For example: $$script[wildcard="*banner*text*"]
It checks if the element code contains the two consecutive substrings banner
and text
.
The wildcard
special attribute must not appear in a selector to the left of a >
combinator.
max-length
Dieses spezielle Attribut könnte zukünftig nicht mehr unterstützt werden. Prefer using the :contains()
pseudo-class with a regular expression where it is available.
Specifies the maximum length for content of HTML element. If this parameter is set and the content length exceeds the value, a rule does not apply to the element.
Default value
If this parameter is not specified, the max-length
is considered to be 8192.
Zum Beispiel:
$$div[tag-content="banner"][max-length="400"]
This rule will remove all the div
elements, whose code contains the substring banner
and the length of which does not exceed 400
characters.
The max-length
special attribute must not appear in a selector to the left of a >
combinator.
min-length
Dieses spezielle Attribut könnte zukünftig nicht mehr unterstützt werden. Prefer using the :contains()
pseudo-class with a regular expression where it is available.
Specifies the minimum length for content of HTML element. If this parameter is set and the content length is less than preset value, a rule does not apply to the element.
Zum Beispiel:
$$div[tag-content="banner"][min-length="400"]
This rule will remove all the div
elements, whose code contains the substring banner
and the length of which exceeds 400
characters.
The min-length
special attribute must not appear in a selector to the left of a >
combinator.
Pseudo-classes
:contains()
Syntax
:contains(unquoted text)
oder
:contains(/reg(ular )?ex(pression)?/)
:-abp-contains()
and :has-text()
are synonyms for :contains()
.
The :contains()
pseudo-class is supported by AdGuard for Windows, Mac, and Android with CoreLibs v1.13 or later.
Requires that the inner HTML of the element contains the specified text or matches the specified regular expression.
A :contains()
pseudo-class must not appear in a selector to the left of a >
combinator.
Exceptions
Similar to hiding rules, there is a special type of rules that disable the selected HTML filtering rule for particular domains. The syntax is the same, you just have to change $$
to $@$
.
For example, there is a rule in filter:
$$script[tag-content="banner"]
If you want to disable it for example.com
, you can create an exception rule:
example.com$@$script[tag-content="banner"]
Sometimes, it may be necessary to disable all restriction rules. For example, to conduct tests. To do this, use the exclusion rule without specifying a domain.
$@$script[tag-content="banner"]
We recommend to use this kind of exceptions only if it is not possible to change the hiding rule itself. In other cases it is better to change the original rule, using domain restrictions.
JavaScript-Regeln
AdGuard supports a special type of rules that allows you to inject any JavaScript code to websites pages.
We strongly recommend using scriptlets instead of JavaScript rules whenever possible. JS rules are supposed to help with debugging, but as a long-time solution a scriptlet rule should be used.
Syntax
rule = [domains] "#%#" script
domains
— domain restriction for the rule. Same principles as in element hiding rules.script
— arbitrary JavaScript code in one string.
Beispiele
example.org#%#window.__gaq = undefined;
executes the codewindow.__gaq = undefined;
on all pages atexample.org
and all subdomains.
Exceptions
Similar to hiding rules, there is a special type of rules that disable the selected javascript rule for particular domains. The syntax is the same, you just have to change #%#
to #@%#
.
For example, there is a rule in filter:
#%#window.__gaq = undefined;
If you want to disable it for example.com
, you can create an exception rule:
example.com#@%#window.__gaq = undefined;
Sometimes, it may be necessary to disable all restriction rules. For example, to conduct tests. To do this, use the exclusion rule without specifying a domain.
#@%#window.__gaq = undefined;
We recommend to use this kind of exceptions only if it is not possible to change the hiding rule itself. In other cases it is better to change the original rule, using domain restrictions.
JavaScript rules can only be used in trusted filters.
JavaScript rules are not supported by AdGuard Content Blocker.
Scriptlet rules
Scriptlet is a JavaScript function that provides extended capabilities for content blocking. These functions can be used in a declarative manner in AdGuard filtering rules.
AdGuard supports a lot of different scriptlets. In order to achieve cross-blocker compatibility, we also support syntax of uBO and ABP.
Syntax der Filterregeln
[domains]#%#//scriptlet(name[, arguments])
domains
— optional, a list of domains where the rule should be applied;name
— required, a name of the scriptlet from AdGuard Scriptlets library;arguments
— optional, a list ofstring
arguments (no other types of arguments are supported).
Beispiele
Apply the
abort-on-property-read
scriptlet on all pages ofexample.org
and its subdomains, and pass it analert
argument:example.org#%#//scriptlet('abort-on-property-read', 'alert')
Remove the
branding
class from alldiv[class^="inner"]
elements on all pages ofexample.org
and its subdomains:example.org#%#//scriptlet('remove-class', 'branding', 'div[class^="inner"]')
Exception rules syntax
Exception rules can disable some scriptlets on particular domains. The syntax for exception scriptlet rules is similar to normal scriptlet rules but uses #@%#
instead of #%#
:
[domains]#@%#//scriptlet([name[, arguments]])
domains
— optional, a list of domains where the rule should be applied;name
— optional, a name of the scriptlet to except from the applying; if not set, all scriptlets will not be applied;arguments
— optional, a list ofstring
arguments to match the same blocking rule and disable it.
Beispiele
Disable specific scriptlet rule so that only
abort-on-property-read
is applied only onexample.org
and its subdomains:example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
example.com#@%#//scriptlet("abort-on-property-read", "alert")Disable all
abort-on-property-read
scriptlets forexample.com
and its subdomains:example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
example.com#@%#//scriptlet("abort-on-property-read")Disable all scriptlets for
example.com
and its subdomains:example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
example.com#@%#//scriptlet()Apply
set-constant
andset-cookie
to any web page, but due to special scriptlet exception rule only theset-constant
scriptlet will be applied onexample.org
and its subdomains:#%#//scriptlet('set-constant', 'adList', 'emptyArr')
#%#//scriptlet('set-cookie', 'accepted', 'true')
example.org#@%#//scriptlet('set-cookie')Apply
adjust-setInterval
to any web page andset-local-storage-item
onexample.com
and its subdomains, but there are also multiple scriptlet exception rules, so no scriptlet rules will be applied onexample.com
and its subdomains:#%#//scriptlet('adjust-setInterval', 'count', '*', '0.001')
example.com#%#//scriptlet('set-local-storage-item', 'ALLOW_COOKIES', 'false')
example.com#@%#//scriptlet()
Learn more about how to debug scriptlets.
More information about scriptlets can be found on GitHub.
Scriptlet rules are not supported by AdGuard Content Blocker.
The full syntax of scriptlet exception rules is supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.16 or later, and AdGuard Browser Extension for Chrome, Firefox, and Edge with TSUrlFilter v3.0 or later. Previous versions only support exception rules that disable specific scriptlets.
Trusted scriptlets
Trusted scriptlets are scriptlets with extended functionality. It means the same syntax and restrictions. Trusted scriptlet names are prefixed with trusted-
, e.g. trusted-set-cookie
, to be easily distinguished from common scriptlets.
Trusted scriptlets are not compatible with other ad blockers except AdGuard.
Trusted scriptlets rules can only be used in trusted filters.
Trusted scriptlets rules are not supported by AdGuard Content Blocker.
Learn more about how to debug scriptlets.
More information about trusted scriptlets can be found on GitHub.
Modifiers for non-basic type of rules
Each rule can be modified using the modifiers described in the following paragraphs.
Syntax {#non-basic-rules-modifiers-syntax}
rule = "[$" modifiers "]" [rule text]
modifiers = modifier0[, modifier1[, ...[, modifierN]]]
modifier
— set of the modifiers described below.rule text
— a rule to be modified.
For example, [$domain=example.com,app=test_app]##selector
.
In the modifiers values, the following characters must be escaped: [
, ]
, ,
, and \
(unless it is used for the escaping). Use \
to escape them. For example, an escaped bracket looks like this: \]
.
Modifikator \ Produkte | CoreLibs-Apps | AdGuard für Chromium | AdGuard für Chrome MV3 | AdGuard für Firefox | AdGuard für iOS | AdGuard für Safari | AdGuard-Inhaltsblocker |
---|---|---|---|---|---|---|---|
$app | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$domain | ✅ | ✅ | ✅ *[1] | ✅ | ✅ | ✅ | ❌ |
$path | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
$url | ✅ | ✅ *[2] | ✅ *[2] | ✅ *[2] | ❌ | ❌ | ❌ |
- ✅ — vollständig unterstützt
- ✅ * — unterstützt, aber die Zuverlässigkeit kann variieren oder es können Einschränkungen auftreten; weitere Einzelheiten finden Sie in der Beschreibung des Modifikators
- ❌ — nicht unterstützt
$app
$app
modifier lets you narrow the rule coverage down to a specific application or a list of applications. The modifier's behavior and syntax perfectly match the corresponding basic rules $app
modifier.
Beispiele
[$app=org.example.app]example.com##.textad
hides adiv
with the classtextad
atexample.com
and all subdomains in requests sent from theorg.example.app
Android app.[$app=~org.example.app1|~org.example.app2]example.com##.textad
hides adiv
with the classtextad
atexample.com
and all subdomains in requests sent from any app exceptorg.example.app1
andorg.example.app2
.[$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300')
applies scriptletprevent-setInterval
only in Safari browser on Mac.[$app=org.example.app]#@#.textad
disables all##.textad
rules for all domains while usingorg.example.app
.
Such rules with $app
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android.
$domain
$domain
modifier limits the rule application area to a list of domains and their subdomains. The modifier's behavior and syntax perfectly match the corresponding basic rules $domain
modifier.
Beispiele
[$domain=example.com]##.textad
— hides adiv
with the classtextad
atexample.com
and all subdomains.[$domain=example.com|example.org]###adblock
— hides an element with attributeid
equalsadblock
atexample.com
,example.org
and all subdomains.[$domain=~example.com]##.textad
— this rule hidesdiv
elements of the classtextad
for all domains, exceptexample.com
and its subdomains.
There are 2 ways to specify domain restrictions for non-basic rules:
- the "classic" way is to specify domains before rule mask and attributes:
example.com##.textad
; - the modifier approach is to specify domains via
$domain
modifier:[$domain=example.com]##.textad
.
But rules with mixed style domains restriction are considered invalid. So, for example, the rule [$domain=example.org]example.com##.textad
will be ignored.
Non-basic $domain
modifier limitations
Since the non-basic $domain
works the same as the basic one, it has the same limitations.
Such rules with $domain
modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, AdGuard Browser Extension for Chrome, for Chrome MV3, Firefox, and Edge.
$path
$path
modifier limits the rule application area to specific locations or pages on websites.
Syntax
$path ["=" pattern]
pattern
— optional, a path mask to which the rule is restricted. Its syntax and behavior are pretty much the same as with the pattern for basic rules. You can also use special characters, except for ||
, which does not make any sense in this case (see examples below).
If pattern
is not set for $path
, rule will apply only on the main page of website.
$path
modifier matches the query string as well.
$path
modifier supports regular expressions in the same way basic rules do.
Beispiele
[$path=page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
or/sub/page.html
or/another_page.html
[$path=/page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
or/sub/page.html
of any domain but not at/another_page.html
[$path=|/page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
of any domain but not at/sub/page.html
[$path=/page.html|]##.textad
hides adiv
with the classtextad
at/page.html
or/sub/page.html
of any domain but not at/page.html?<query>
[$path=/page*.html]example.com##.textad
hides adiv
with the classtextad
at/page1.html
or/page2.html
or any other path matching/page<...>.html
ofexample.com
[$path]example.com##.textad
hides adiv
with the classtextad
at the main page ofexample.com
[$domain=example.com,path=/page.html]##.textad
hides adiv
with the classtextad
atpage.html
ofexample.com
and all subdomains but not atanother_page.html
[$path=/\\/(sub1|sub2)\\/page\\.html/]##.textad
hides adiv
with the classtextad
at both/sub1/page.html
and/sub2/page.html
of any domain (please note the escaped special characters)
Rules with $path
modifier are not supported by AdGuard Content Blocker.
$url
$url
modifier limits the rule application area to URLs matching the specified mask.
Syntax
url = pattern
where pattern
is pretty much the same as pattern
of the basic rules assuming that some characters must be escaped. The special characters and regular expressions are supported as well.
Beispiele
[$url=||example.com/content/*]##div.textad
hides adiv
with the classtextad
at addresses likehttps://example.com/content/article.html
and evenhttps://subdomain.example.com/content/article.html
.[$url=||example.org^]###adblock
hides an element with attributeid
equal toadblock
atexample.org
and its subdomains.[$url=/\[a-z\]+\\.example\\.com^/]##.textad
hidesdiv
elements of the classtextad
for all domains matching the regular expression[a-z]+\.example\.com^
.
$url
modifier limitations
Rules with the $url
modifier are supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.11 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
Information for filter maintainers
If you maintain a third-party filter that is known to AdGuard, you might be interested in the information presented in this section. Please note that hints will be applied to registered filters only. The filter is considered to be registered and known by AdGuard, if it is present in the known filters index. If you want your filter to be registered, please file an issue to AdguardFilters repo.
Preprocessor directives
We provide preprocessor directives that can be used by filter maintainers to improve compatibility with different ad blockers and provide:
- including a file
- applying rules conditionally by ad blocker type
- content blocker specifying for rules applying in Safari
Any mistake in a preprocessor directive will lead to AdGuard failing the filter update in the same way as if the filter URL was unavailable.
Preprocessor directives can be used in the user rules or in the custom filters.
Including a file
The !#include
directive allows to include contents of a specified file into the filter. It supports only files from the same origin to make sure that the filter maintainer is in control of the specified file. The included file can also contain pre-directives (even other !#include
directives). Ad blockers should consider the case of recursive !#include
and implement a protection mechanism.
Syntax
!#include file_path
where file_path
is a same origin absolute or relative file path to be included.
The files must originate from the same domain, but may be located in a different folder.
If included file is not found or unavailable, the whole filter update should fail.
Same-origin limitation should be disabled for local custom filters.
Beispiele
Filter URL: https://example.org/path/filter.txt
! Valid (same origin):
!#include https://example.org/path/includedfile.txt
!
! Valid (relative path):
!#include /includedfile.txt
!#include ../path2/includedfile.txt
!
! Invalid (another origin):
!#include https://domain.com/path/includedfile.txt
Bedingungen
Filter maintainers can use conditions to supply different rules depending on the ad blocker type. A conditional directive beginning with an !#if
directive must explicitly be terminated with an !#endif
directive. Conditions support all basic logical operators.
Es gibt zwei mögliche Szenarien:
When an ad blocker encounters an
!#if
directive and no!#else
directive, it will compile the code between!#if
and!#endif
directives only if the specified condition is true.If there is an
!#else
directive, the code between!#if
and!#else
will be compiled if the condition is true; otherwise, the code between!#else
and!#endif
will be compiled.
Whitespaces matter. !#if
is a valid directive, while !# if
is not.
Syntax
!#if (conditions)
rules_list
!#endif
oder
!#if (conditions)
true_conditions_rules_list
!#else
false_conditions_rules_list
!#endif
mit:
!#if (conditions)
— start of the block when conditions are trueconditions
— just like in some popular programming languages, preprocessor conditions are based on constants declared by ad blockers. Authors of ad blockers define on their own what exact constants they declare. Possible values:adguard
always declared; shows maintainers that this is one of AdGuard products; should be enough in 95% of cases- product-specific constants for cases when you need a rule to work (or not work — then
!
should be used before constant) in a specific product only:adguard_app_windows
— AdGuard for Windowsadguard_app_mac
— AdGuard for Macadguard_app_android
— AdGuard for Androidadguard_app_ios
— AdGuard for iOSadguard_ext_safari
— AdGuard for Safariadguard_ext_chromium
— AdGuard Browser Extension for Chrome (and chromium-based browsers, e.g. new Microsoft Edge)adguard_ext_chromium_mv3
— AdGuard for Chrome MV3adguard_ext_firefox
— AdGuard Browser Extension for Firefoxadguard_ext_edge
— AdGuard Browser Extension for Edge Legacyadguard_ext_opera
— AdGuard Browser Extension for Operaadguard_ext_android_cb
— AdGuard Content Blocker for mobile Samsung and Yandex browsersext_ublock
— special case; this one is declared when a uBlock version of a filter is compiled by the FiltersRegistrycap_html_filtering
— products that support HTML filtering rules: AdGuard for Windows, AdGuard for Mac, and AdGuard for Android
!#else
— start of the block when conditions are falserules_list
,true_conditions_rules_list
,false_conditions_rules_list
— lists of rules!#endif
— end of the block
Beispiele
! for all AdGuard products except AdGuard for Safari
!#if (adguard && !adguard_ext_safari)
||example.org^$third-party
domain.com##div.ad
!#endif
! directives even can be combined
!#if (adguard_app_android)
!#include /androidspecific.txt
!#endif
!#if (adguard && !adguard_ext_safari)
! for all AdGuard products except AdGuard for Safari
||example.org^$third-party
domain.com##div.ad
!#else
! for AdGuard for Safari only
||subdomain.example.org^$third-party
!#endif
The !#else
directive is supported by the FiltersDownloader v1.1.20 or later.
It is already supported for filter lists compiled by the FiltersRegistry, but it still may not be supported by AdGuard products when adding a filter list with !#else
as a custom one. The following products will support it in the mentioned versions or later:
- AdGuard for Windows, Mac, and Android with CoreLibs v1.13;
- AdGuard Browser Extension v4.2.208;
- AdGuard v1.11.16 for Safari.
Safari affinity
Safari's limit for each content blocker is 150,000 active rules. But in AdGuard for Safari and AdGuard for iOS, we've split the rules into 6 content blockers, thus increasing the rule limit to 900,000.
Here is the composition of each content blocker:
- AdGuard General — Ad Blocking, Language-specific
- AdGuard Privacy — Privacy
- AdGuard Social — Social Widgets, Annoyances
- AdGuard Security — Security
- AdGuard Other — Other
- AdGuard Custom — Custom
User rules and allowlist are added to every content blocker.
The main disadvantage of using multiple content blockers is that rules from different blockers are applied independently. Blocking rules are not affected by this, but unblocking rules may cause problems. If a blocking rule is in one content blocker and an exception is in another, the exception will not work. Filter maintainers use !#safari_cb_affinity
to define Safari content blocker affinity for the rules inside of the directive block.
Syntax
!#safari_cb_affinity(content_blockers)
rules_list
!#safari_cb_affinity
mit:
!#safari_cb_affinity(content_blockers)
— start of the blockcontent_blockers
— comma-separated list of content blockers. Possible values:general
— AdGuard General content blockerprivacy
— AdGuard Privacy content blockersocial
— AdGuard Social content blockersecurity
— AdGuard Security content blockerother
— AdGuard Other content blockercustom
— AdGuard Custom content blockerall
— special keyword that means that the rules must be included into all content blockers
rules_list
— list of rules!#safari_cb_affinity
— end of the block
Beispiele
! to unhide specific element which is hidden by AdGuard Base filter:
!#safari_cb_affinity(general)
example.org#@#.adBanner
!#safari_cb_affinity
! to allowlist basic rule from AdGuard Tracking Protection filter:
!#safari_cb_affinity(privacy)
@@||example.org^
!#safari_cb_affinity
Hints
"Hint" is a special comment, instruction to the filters compiler used on the server side (see FiltersRegistry).
Syntax
!+ HINT_NAME1(PARAMS) HINT_NAME2(PARAMS)
Multiple hints can be applied.
NOT_OPTIMIZED
hint
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. But filters optimization is based on more than that — some filters have specific configuration. This is how it looks like for Base filter:
"filter": AdGuard Base filter,
"percent": 30,
"minPercent": 20,
"maxPercent": 40,
"strict": true
mit:
- filter — filter identifier
- percent — expected optimization percent
~= (rules count in optimized filter) / (rules count in original filter) * 100
- minPercent — lower bound of
percent
value - maxPercent — upper bound of
percent
value - strict — if
percent < minPercent
ORpercent > maxPercent
and strict mode is on then filter compilation should fail, otherwise original rules must be used
In other words, percent
is the "compression level". For instance, for the Base filter it is configured to 40%. It means that optimization algorithm should strip 60% of rules.
Eventually, here are the two versions of the Base filter for AdGuard Browser Extension:
- full: https://filters.adtidy.org/extension/chromium/filters/2.txt
- optimized: https://filters.adtidy.org/extension/chromium/filters/2_optimized.txt
If you want to add a rule which should not be removed at optimization use the NOT_OPTIMIZED
hint:
!+ NOT_OPTIMIZED
||example.org^
And this rule will not be optimized only for AdGuard for Android:
!+ NOT_OPTIMIZED PLATFORM(android)
||example.org^
PLATFORM
and NOT_PLATFORM
hints
Used to specify the platforms to apply the rules. List of existing platforms and links to Base filter, for example, for each of them:
windows
— AdGuard for Windows — https://filters.adtidy.org/windows/filters/2.txtmac
— AdGuard for Mac — https://filters.adtidy.org/mac_v2/filters/2.txtandroid
— AdGuard for Android — https://filters.adtidy.org/android/filters/2.txtios
— AdGuard for iOS — https://filters.adtidy.org/ios/filters/2.txtext_chromium
— AdGuard Browser Extension for Chrome — https://filters.adtidy.org/extension/chromium/filters/2.txtext_chromium_mv3
— AdGuard Browser Extension for Chrome MV3 — https://filters.adtidy.org/extension/chromium-mv3/filters/2.txtext_ff
— AdGuard Browser Extension for Firefox — https://filters.adtidy.org/extension/firefox/filters/2.txtext_edge
— AdGuard Browser Extension for Edge — https://filters.adtidy.org/extension/edge/filters/2.txtext_opera
— AdGuard Browser Extension for Opera — https://filters.adtidy.org/extension/opera/filters/2.txtext_safari
— AdGuard for Safari — https://filters.adtidy.org/extension/safari/filters/2.txtext_android_cb
— AdGuard Content Blocker — https://filters.adtidy.org/extension/android-content-blocker/filters/2.txtext_ublock
— uBlock Origin — https://filters.adtidy.org/extension/ublock/filters/2.txt
Beispiele
This rule will be available only in AdGuard for Windows, Mac, Android:
!+ PLATFORM(windows,mac,android)
||example.org^
Except for AdGuard for Safari, AdGuard Content Blocker, and AdGuard for iOS, this rule is available on all platforms:
!+ NOT_PLATFORM(ext_safari, ext_android_cb, ios)
||example.org^
How to debug filtering rules
It may be possible to create simple filtering rules "in your head" but for anything even slightly more complicated you will need additional tools to debug and iterate them. There are tools to assist you with that. You can use DevTools in Chrome and its analogs in other browsers but most AdGuard products provide another one — Filtering log.
Filtering log
Filtering log is an advanced tool that will be helpful mostly to filter developers. It lists all web requests that pass through AdGuard, gives you exhaustive information on each of them, offers multiple sorting options, and has other useful features.
Depending on which AdGuard product you are using, Filtering log can be located in different places.
- In AdGuard for Windows, you can find it in the Ad Blocker tab or via the tray menu
- In AdGuard for Mac, it is located in Settings → Advanced → Filtering log
- In AdGuard for Android, you can find it under Statistics → Recent activity. Recent activity can also be accessed from the Assistant
- In AdGuard Browser Extension, it is accessible from the Miscellaneous settings tab or by right-clicking the extension icon. Only Chromium- and Firefox-based web browsers show applied element hiding rules (including CSS, ExtCSS) and JS rules and scriptlets in their Filtering logs
In AdGuard for iOS and AdGuard for Safari, Filtering log does not exist because of the way content blockers are implemented in Safari. AdGuard does not see the web requests and therefore cannot display them.
Selectors debugging mode
Sometimes, you might need to check the performance of a given selector or a stylesheet. In order to do it without interacting with JavaScript directly, you can use a special debug
style property. When ExtendedCss
meets this property, it enables the debugging mode either for a single selector or for all selectors, depending on the debug
value.
Open the browser console while on a web page to see the timing statistics for selector(s) that were applied there. Debugging mode displays the following stats as object where each of the debugged selectors are keys, and value is an object with such properties:
Always printed:
selectorParsed
— text of the parsed selector, may differ from the input onetimings
— list of DOM nodes matched by the selectorappliesCount
— total number of times that the selector has been applied on the pageappliesTimings
— time that it took to apply the selector on the page, for each of the instances that it has been applied (in milliseconds)meanTiming
— mean time that it took to apply the selector on the pagestandardDeviation
— standard deviationtimingsSum
— total time it took to apply the selector on the page across all instances
Printed only for remove pseudos:
removed
— flag to signal if elements were removed
Printed if elements are not removed:
matchedElements
— list of DOM nodes matched by the selectorstyleApplied
— parsed rule style declaration related to the selector
Beispiele
Debugging a single selector:
When the value of the debug
property is true
, only information about this selector will be shown in the browser console.
#$?#.banner { display: none; debug: true; }
Enabling global debug:
When the value of the debug
property is global
, the console will display information about all extended CSS selectors that have matches on the current page, for all the rules from any of the enabled filters.
#$?#.banner { display: none; debug: global; }
Testing extended selectors without AdGuard
ExtendedCss can be executed on any page without using any AdGuard product. In order to do that you should copy and execute the following code in a browser console:
!function(e,t,d){C=e.createElement(t),C.src=d,C.onload=function(){alert("ExtendedCss loaded successfully")},s=e.getElementsByTagName(t)[0],s?s.parentNode.insertBefore(C,s):(h=e.getElementsByTagName("head")[0],h.appendChild(C))}(document,"script","https://AdguardTeam.github.io/ExtendedCss/extended-css.min.js");
Alternatively, install the ExtendedCssDebugger userscript.
Now you can now use the ExtendedCss
from global scope, and run its method query()
as Document.querySelectorAll()
.
Beispiele
const selector = 'div.block:has=(.header:matches-css(after, content: Ads))';
// array of HTMLElements matched the `selector` is to be returned
ExtendedCss.query(selector);
Debugging scriptlets
If you are using AdGuard Browser Extension and want to debug a scriptlet or a trusted scriptlet rule, you can get additional information by opening the Filtering log. In that case, scriptlets will switch to debug mode and there will be more information in the browser console.
The following scriptlets are especially developed for debug purposes:
debug-current-inline-script
debug-on-property-read
debug-on-property-write
log-addEventListener
log-on-stack-trace
log-eval
log
The following scriptlets also may be used for debug purposes:
json-prune
prevent-fetch
prevent-requestAnimationFrame
prevent-setInterval
prevent-setTimeout
prevent-window-open
with specifiedreplacement
parameterprevent-xhr
trusted-replace-fetch-response
trusted-replace-xhr-response
Compatibility tables legend
Product shortcuts
CoreLibs apps
— AdGuard for Windows, AdGuard for Mac, and AdGuard for AndroidAdGuard for Chromium
— AdGuard Browser Extension for Chrome and other Chromium-based browsers such as Microsoft Edge, OperaAdGuard for Chrome MV3
— AdGuard Browser Extension for Chrome MV3AdGuard for Firefox
— AdGuard Browser Extension for FirefoxAdGuard for iOS
— AdGuard for iOS and AdGuard Pro for iOS (for mobile Safari browser)AdGuard for Safari
— AdGuard for desktop Safari browserAdGuard Content Blocker
— Content Blocker for Android mobile browsers: Samsung Internet and Yandex Browser
Compatibility shortcuts
- ✅ — vollständig unterstützt
- ✅ * — unterstützt, aber die Zuverlässigkeit kann variieren oder es können Einschränkungen auftreten; weitere Einzelheiten finden Sie in der Beschreibung des Modifikators
- 🧩 — may already be implemented in nightly or beta versions but is not yet supported in release versions
- ⏳ — Funktion, deren Implementierung geplant ist, die aber noch in keinem Produkt verfügbar ist
- ❌ — nicht unterstützt
- 👎 — veraltet; wird noch unterstützt, aber in Zukunft entfernt
- 🚫 — entfernt und nicht mehr unterstützt