Jak vytvářet vlastní filtry reklam
V tomto článku vysvětlíme, jak napsat vlastní pravidla filtrování pro použití v produktech AdGuardu. Chcete-li otestovat svá pravidla, stáhněte si aplikaci AdGuard
Filtr je sada pravidel filtrování aplikovaných na konkrétní obsah, například bannery nebo vyskakovací okna. AdGuard má seznam standardních filtrů vytvořených naším týmem. Neustále je vylepšujeme, aktualizujeme a snažíme se vyhovět potřebám většiny našich uživatelů.
AdGuard zároveň umožňuje vytvářet vlastní filtry pomocí stejných typů pravidel, které máme v našich filtrech.
K popisu syntaxe našich pravidel filtrování používáme Augmented BNF for Syntax Specifications, ale ne vždy se touto specifikací striktně řídíme.
Původně byla syntaxe AdGuardu založena na syntaxi pravidel Adblock Plus. Později jsme ji rozšířili o nové typy pravidel pro lepší filtrování reklam. Některé části tohoto článku o pravidlech společných pro AdGuard i ABP byly převzaty z příručka Adblock Plus o tom, jak psát filtry.
Komentáře
Každý řádek začínající vykřičníkem je komentář. V seznamu pravidel je zobrazen šedou barvou. AdGuard bude tento řádek ignorovat, takže můžete napsat cokoli chcete. Komentáře se obvykle umísťují nad pravidla a slouží k popisu toho, co pravidlo dělá.
Např:
! Toto je komentář. Pod tímto řádkem se nachází skutečné pravidlo filtrování.
||example.org^
Příklady
Blokování podle názvu domény
Toto pravidlo blokuje:
http://example.org/ad1.gif
http://subdomain.example.org/ad1.gif
https://ads.example.org:8000/
Toto pravidlo neblokuje:
http://ads.example.org.us/ad1.gif
http://example.com/redirect/http://ads.example.org/
Ve výchozím nastavení tato pravidla pro žádosti o dokumenty nefungují. To znamená, že pravidlo ||example.org^
zablokuje požadavek na example.org
při pokusu o přechod na tuto doménu z jiné webové stránky, ale pokud do adresního řádku zadáte example.org
a pokusíte se na doménu přejít, webová stránka se otevře. Chcete-li zablokovat žádost o dokument, budete muset použít pravidlo s modifikátorem $document
: ||example.org^$document
.
Blokování přesné adresy
Toto pravidlo blokuje:
http://example.org/
Toto pravidlo neblokuje:
https://example.org/banner/img
Modifikátory základních pravidel
Pravidla filtrování podporují řadu modifikátorů, které umožňují doladit chování pravidla. Zde je příklad pravidla s několika jednoduchými modifikátory.
Toto pravidlo blokuje:
http://example.org/script.js
, pokud je tento skript načten zexample.com
.
Toto pravidlo neblokuje:
https://example.org/script.js
, pokud je tento skript načten zexample.org
.https://example.org/banner.png
, protože se nejedná o skript.
Odblokování adresy
Toto pravidlo odblokuje:
http://example.org/banner.png
, i když pro tuto adresu existuje pravidlo blokování.
Pravidla blokování s modifikátorem $important
mohou přepsat výjimky.
Odblokování celé webové stránky
Toto pravidlo odblokuje
- Zakáže všechna kosmetická pravidla na
example.com
. - Odblokuje všechny požadavky odeslané z této webové stránky, i když existují pravidla blokování odpovídající těmto požadavkům.
Kosmetické pravidlo
Kosmetická pravidla jsou založena na použití speciálního jazyka CSS, kterému rozumí každý prohlížeč. V podstatě přidává na webové stránky nový styl CSS, jehož účelem je skrýt určité prvky. Více o CSS obecně se můžete dozvědět zde.
AdGuard rozšiřuje CSS a umožňuje tak vývojářům filtrů řešit mnohem složitější případy. Abyste však mohli tato rozšířená pravidla používat, musíte ovládat běžný jazyk CSS.
Oblíbené selektory CSS
Název | Selektor CSS | Popis |
---|---|---|
ID selector | #banners | Shoduje se se všemi prvky s atributem id rovným banners . |
Class selector | .banners | Shoduje se se všemi prvky s atributem class obsahujícím banners . |
Attribute selector | div[class="banners"] | Shoduje se se všemi prvky div s atributem class přesně rovným k banners . |
Attribute substring selector | div[class^="advert1"] | Shoduje se se všemi prvky div s atributem class začínajícím na řetězec advert1 . |
Attribute substring selector | div[class$="banners_ads"] | Shoduje se se všemi prvky div s atributem class končícím na řetězec banners_ads . |
Attribute substring selector | a[href^="http://example.com/"] | Shoduje se se všemi odkazy načtenými z domény http://example.com/ . |
Attribute selector | a[href="http://example.com/"] | Shoduje se se všemi odkazy exactly adresy http://example.com/ . |
Omezení a restrikce
Důvěryhodné filtry
Některá pravidla lze použít pouze v důvěryhodných filtrech. Tato kategorie zahrnuje:
- seznamy filtrů vytvořené týmem AdGuard,
- seznamy vlastních filtrů nainstalované jako
trusted
, - uživatelská pravidla.
Blokátor obsahu AdGuard
Blokátor obsahu AdGuard je rozšíření pro prohlížeče Samsung a Yandex, které lze nainstalovat z Google Play. Nesmí se zaměňovat s plně funkčním nástrojem AdGuard pro Android, který lze stáhnout pouze z našich stránek. Bohužel, funkce Blokátoru obsahu AdGuard jsou omezeny tím, co prohlížeče umožňují a podporují pouze starou syntaxi filtrů Adblock Plus:
- Základní pravidla blokování s následujícími modifikátory:
$domain
,$third-party
, modifikátory typu obsahu. - Základní pravidla výjimek s následujícími modifikátory:
$document
,$elemhide
. - Základní pravidla pro skrývání prvků bez rozšířené podpory CSS.
Vzhledem k výše uvedeným omezením nebude Blokátor obsahu AdGuard uveden v poznámkách ke kompatibilitě.
Základní pravidla
Nejjednoduššími pravidly jsou tzv. základní pravidla. Slouží k blokování požadavků na konkrétní adresy URL. Nebo je odblokují, pokud je na začátku pravidla speciální znak "@@". Základní princip tohoto typu pravidel je poměrně jednoduchý: je třeba zadat adresu a další parametry, které omezují nebo rozšiřují rozsah pravidla.
Základní pravidla pro blokování požadavků se vztahují pouze na dílčí požadavky. To znamená, že nebudou blokovat načítání stránky, pokud není výslovně zadána pomocí modifikátoru $document
.
Prohlížeč rozpozná zablokovaný požadavek jako dokončený s chybou.
Pravidla kratší než 4 znaky jsou považována za nesprávná a budou ignorována.
Syntaxe základních pravidel
rule = ["@@"] pattern [ "$" modifiers ]
modifiers = [modifier0, modifier1[, ...[, modifierN]]]
pattern
— maska adresy. Každá adresa URL požadavku je přiřazena k této masce. V šabloně můžete také použít speciální znaky popsané níže. Vezměte na vědomí, že AdGuard zkracuje adresy URL na délku 4096 znaků, aby urychlil porovnávání a předešel problémům s nesmyslně dlouhými adresami URL.@@
— znak, který se používá v pravidlech výjimek. Chcete-li filtrování požadavku vypnout, začněte pravidlo touto značkou.modifiers
— parametry, které "objasňují" základní pravidlo. Některé z nich omezují rozsah pravidel a některé mohou zcela změnit jejich fungování.
Speciální znaky
*
— zástupný znak. Používá se k reprezentaci libovolné sady znaků. Může to být také prázdný řetězec nebo řetězec libovolné délky.||
— indikace o použití pravidla na zadanou doménu a její subdomény. S tímto znakem nemusíte v masce adresy zadávat konkrétní protokol a subdoménu. Tj., že||
znamenáhttp://*.
,https://*.
,ws://*.
,wss://*.
najednou.^
— oddělovací znak. Oddělovací znak je libovolný znak, mimo písmeno, číslice nebo jeden z následujících znaků:_
-
.
%
. V tomto příkladu jsou oddělovací znaky zobrazeny tučně:http:
//
example.com
/?
t=1
&
t2=t3
. Konec adresy je také akceptován jako oddělovací znak.|
— ukazatel na začátku nebo konci adresy. Hodnota závisí na umístění znaku v masce. Např. pravidloswf|
odpovídáhttp://example.com/annoyingflash.swf
, ale neodpovídáhttp://example.com/swf/index.html
.|http://example.org
odpovídáhttp://example.org
, ale nehttp://domain.com?url=http://example.org
.
|
, ||
, ^
lze použít pouze u pravidel se vzorem URL. Např. ||example.com##.advert
je nesprávný a bude blokátorem ignorován.
Doporučujeme také seznámit se s přehledem filtrů Adblock Plus, abyste lépe pochopili, jak taková pravidla vytvářet.
Podpora regulárních výrazů
Pokud chcete ještě větší flexibilitu při vytváření pravidel, můžete použít regulární výrazy namísto výchozí zjednodušené masky se speciálními znaky.
Pravidla s regulárními výrazy pracují pomaleji, proto se jim doporučuje vyhnout nebo omezit jejich rozsah na určité domény.
Pokud chcete, aby blokátor určil regulární výraz, musí pattern
vypadat takto:
pattern = "/" regexp "/"
Např. pravidlo /banner\d+/$third-party
použije regulární výraz banner\d+
na všechny požadavky třetích stran. Pravidlo výjimky s regulárním výrazem vypadá takto: @@/banner\d+/
.
AdGuard pro Safari a AdGuard pro iOS plně nepodporují regulární výrazy kvůli omezení API pro blokování obsahu (hledejte sekci "Formát regulárního výrazu").
Podpora zástupných znaků pro TLD (domény nejvyšší úrovně)
Zástupné znaky jsou podporovány pro TLD domén ve vzorech kosmetických, filtrování HTML a pravidel JavaScript.
V případě kosmetických pravidel, např. example.*##.banner
, je díky znaku .*
, tj. example.com
, sub.example.net
, example.co.uk
, atd. přiřazeno více domén.
Pro základní pravidla platí popsaná logika pouze pro domény uvedené v $domain
modifikátoru, např. ||*/banners/*$image,domain=example.*
.
V AdGuardu pro Windows, Mac, Android a v pravidlech rozšíření prohlížeče AdGuard se zástupným znakem .*
, odpovídá jakékoli veřejné příponě (nebo eTLD). Pro AdGuard pro Safari a iOS je však seznam podporovaných domén nejvyšší úrovně omezen kvůli omezením v Safari.
Pravidla se zástupným znakem pro TLD nejsou podporována Blokátorem obsahu AdGuard.
Příklady základních pravidel
||example.com/ads/*
— jednoduché pravidlo, které odpovídá adresám typuhttp://example.com/ads/banner.jpg
a dokonce ihttp://subdomain.example.com/ads/otherbanner.jpg
.||example.org^$third-party
— this rule blocks third-party requests toexample.org
and its subdomains.@@||example.com$document
— obecné pravidlo výjimky. Zcela vypne filtrování proexample.com
a všechny subdomény. V pravidlech pro výjimky lze použít řadu modifikátorů. Pro více podrobností klikněte na odkaz níže.
Modifikátory základních pravidel
Funkce popsané v této části jsou určeny pro zkušené uživatele. Rozšiřují možnosti "základních pravidel", ale abyste je mohli používat, musíte mít základní znalosti o fungování prohlížeče.
Chování "základního pravidla" můžete změnit pomocí dalších modifikátorů. Modifikátory by měly být umístěny na konci pravidla za znakem $
a odděleny čárkami.
Příklad:
||domain.com^$popup,third-party
Základní modifikátory
Následující modifikátory jsou nejjednodušší a nejčastěji používané. V podstatě jen omezují rozsah použití pravidel.
Modifikátor \ Produkty | Aplikace CoreLibs | AdGuard pro Chromium | AdGuard pro Firefox | AdGuard pro iOS | AdGuard pro Safari | Blokátor obsahu AdGuard |
---|---|---|---|---|---|---|
$app | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$denyallow | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$domain | ✅ | ✅ | ✅ | ✅ * | ✅ * | ✅ |
$header | ✅ | 🧩 ** | 🧩 ** | ❌ | ❌ | ❌ |
$important | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$match-case | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$method | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$popup | ✅ *** | ✅ | ✅ | ✅ *** | ✅ *** | ❌ |
$third-party | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$to | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — plně podporováno
- ✅ * — podporováno, ale spolehlivost se může lišit nebo se mohou vyskytnout omezení; více informací naleznete v popisu modifikátoru
- 🧩 — může být již implementováno ve verzích nightly nebo beta, ale není ještě podporováno ve verzích pro vydání
- ❌ — nepodporováno
$app
Tento modifikátor umožňuje zúžit pokrytí pravidla na konkrétní aplikaci (nebo seznam aplikací). V systémech Windows a Mac to nemusí být příliš důležité, ale v mobilních zařízeních, kde některá pravidla filtrování musí být specifická pro konkrétní aplikaci, je to velmi důležité.
- Android — použijte název balíčku aplikace, např.
org.example.app
. - Windows — použijte název procesu, např.
chrome.exe
. - Mac — použijte ID svazku nebo název procesu, např.
com.google.Chrome
.
V případě počítače Mac můžete ID svazku nebo název procesu aplikace zjistit zobrazením příslušných podrobností o požadavku v záznamu filtrování.
Příklady
||baddomain.com^$app=org.example.app
— pravidlo pro blokování požadavků, které odpovídají zadané masce a jsou odeslány z Android aplikaceorg.example.app
.||baddomain.com^$app=org.example.app1|org.example.app2
— stejné pravidlo, ale funguje jak proorg.example.app1
, tak i proorg.example.app2
.
Pokud chcete, aby se pravidlo nevztahovalo na určité aplikace, začněte název aplikace znakem ~
.
||baddomain.com^$app=~org.example.app
— pravidlo pro blokování požadavků, které odpovídají zadané masce a jsou odeslány z jakékoli aplikace kroměorg.example.app
.||baddomain.com^$app=~org.example.app1|~org.example.app2
— stejně jako výše, ale nyní jsou vyloučeny dvě aplikace:org.example.app1
aorg.example.app2
.
Aplikace v hodnotě modifikátoru nemohou mít zástupný znak, např. $app=com.*.music
. Pravidla s takovým modifikátorem jsou považována za neplatná.
- Pouze AdGuard pro Windows, Mac a Android jsou technicky schopné používat pravidla s modifikátorem
$app
. - On Windows the process name is case-insensitive starting with AdGuard for Windows with CoreLibs v1.12 or later.
$denyallow
Modifikátor $denyallow
umožňuje vyhnout se vytváření dalších pravidel, pokud je potřeba zakázat určité pravidlo pro konkrétní domény. $denyallow
odpovídá pouze cílovým doménám, nikoli doménám odkazujícím.
Přidání tohoto modifikátoru k pravidlu je ekvivalentní vyloučení domén podle shodného vzoru pravidla nebo přidání odpovídajících pravidel výjimek. To add multiple domains to one rule, use the |
character as a separator.
Příklady
Toto pravidlo:
*$script,domain=a.com|b.com,denyallow=x.com|y.com
odpovídá tomuto:
/^(?!.*(x.com|y.com)).*$/$script,domain=a.com|b.com
nebo kombinaci těchto tří:
*$script,domain=a.com|b.com
@@||x.com$script,domain=a.com|b.com
@@||y.com$script,domain=a.com|b.com
- Vzor shody pravidla se nemůže zaměřit na žádné konkrétní domény, např. nemůže začínat
||
. - 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
cannot be used together with$to
. It can be expressed with inverted$to
:$denyallow=a.com|b.com
is equivalent to$to=~a.com|~b.com
.
Pravidla, která tato omezení porušují, jsou považována za neplatná.
Pravidla s modifikátorem $denyallow
nejsou AdGuardem pro iOS, Safari a Blokátorem obsahu AdGuard podporována.
$domain
$domain
omezuje rozsah pravidla na požadavky ze zadaných domén a jejich subdomén (jak je uvedeno v záhlaví Referer HTTP).
Syntaxe
Modifikátor je seznam jednoho nebo více výrazů oddělených symbolem |
, z nichž každý je porovnáván s doménou určitým způsobem v závislosti na svém typu (viz níže).
domains = ["~"] entry_0 ["|" ["~"] entry_1 ["|" ["~"]entry_2 ["|" ... ["|" ["~"]entry_N]]]]
entry_i = ( regular_domain / any_tld_domain / regexp )
regular_domain
— běžný název domény (domain.com
). Odpovídá zadané doméně a jejím subdoménám. Shoduje se lexikograficky.any_tld_domain
— název domény zakončený zástupným znakem jako veřejná přípona, např. proexample.*
je toco.uk
vexample.co.uk
. Odpovídá zadané doméně a jejím subdoménám s libovolnou veřejnou příponou. Shoduje se lexikograficky.regexp
— regulární výraz, který začíná a končí znakem/
. Vzor funguje stejně jako v základních pravidlech pro URL adresy, ale znaky/
,$
a,
musí být uvozeny pomocí\
.
Pravidla s modifikátorem $domain
jako regular_domain
nebo any_tld_domain
jsou podporována všemi AdGuard produkty.
Příklady
Jen $domain
:
||baddomain.com^$domain=example.org
blokuje požadavky, které odpovídají zadané masce a jsou odeslány z doményexample.org
nebo jejích subdomén.||baddomain.com^$domain=example.org|example.com
— stejné pravidlo, ale funguje jak proexample.org
, tak i proexample.com
.
Pokud chcete, aby se pravidlo nevztahovalo na určité domény, začněte název domény znakem ~
.
$domain
a negace ~
:
||baddomain.com^$domain=example.org
blokuje požadavky, které odpovídají zadané masce a jsou odeslány z doményexample.org
nebo jejích subdomén.||baddomain.com^$domain=example.org|example.com
— stejné pravidlo, ale funguje jak proexample.org
, tak i proexample.com
.||baddomain.com^$domain=~example.org
blokuje požadavky, které odpovídají vzoru a jsou odeslané z jakékoli domény kroměexample.org
a jejích subdomén.||baddomain.com^$domain=example.org|~foo.example.org
blokuje požadavky odeslané zexample.org
a jích subdomén, kromě subdoményfoo.example.org
.||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/
blokuje požadavky odeslané zexample.org
aexample.com
a všech jejích subdomén.||baddomain.com^$domain=~a.com|~b.*|~/(^\|.+\.)c\.(com\|org)\$/
blokuje požadavky odeslané za.com
,b
s libovolnou veřejnou příponou (b.com
,b.co.uk
, etc.),c.com
,c.org
, a jejich subdomén.
$domain
modifikátor odpovídající cílové doméně:
V některých případech může modifikátor $domain
odpovídat nejen doméně odkazovače, ale také cílové doméně. K tomu dojde, pokud jsou splněny všechny následující podmínky:
- Požadavek má typ obsahu
document
- Vzor pravidla neodpovídá žádné konkrétní doméně
- Vzor pravidla neobsahuje regulární výrazy
- Modifikátor
$domain
obsahuje pouze domény ve výjimkách, např.$domain=~example.org|~example.com
Následující predikát by měl být splněn, aby bylo možné provést porovnání cílové domény:
1 AND ((2 AND 3) OR 4)
To znamená, že pokud modifikátor $domain
obsahuje pouze domény ve výjimkách, pak pravidlo nemusí splňovat druhou a třetí podmínku, aby se cílová doména shodovala s modifikátorem $domain
.
Pokud některé z výše uvedených podmínek nejsou splněny, ale pravidlo obsahuje modifikátor $cookie
nebo $csp
, cílová doména bude přesto přiřazena.
Pokud odkazující doména odpovídá pravidlu s $domain
, které výslovně vylučuje doménu odkazujícího serveru, pravidlo se nepoužije, i když cílová doména také odpovídá pravidlu. To má vliv i na pravidla s modifikátory $cookie
a $csp
.
Příklady
*$cookie,domain=example.org|example.com
zablokuje soubory cookie pro všechny požadavky do a z doményexample.org
aexample.com
.*$document,domain=example.org|example.com
zablokuje všechny požadavky do a z doményexample.org
aexample.com
.
V následujících příkladech se předpokládá, že požadavky jsou odesílány z adresy http://example.org/page
(odkazující adresa), cílová adresa URL je http://targetdomain.com/page
.
page$domain=example.org
bude přiřazena, protože odpovídá doméně odkazu.page$domain=targetdomain.com
bude přiřazena, protože odpovídá cílové doméně a splňuje všechny výše uvedené požadavky.||*page$domain=targetdomain.com
nebude přiřazena, protože vzor||*page
odpovídá konkrétním doménám, např.example.page
.||*page$domain=targetdomain.com,cookie
bude přiřazena, protože pravidlo obsahuje modifikátor$cookie
, přestože vzor||*page
může odpovídat konkrétním doménám./banner\d+/$domain=targetdomain.com
nebude přiřazena, protože obsahuje regulární výraz.page$domain=targetdomain.com|~example.org
nebude přiřazena, protože doména odkazu je výslovně vyloučena.
omezení modifikátoru $domain
Safari nepodporuje současné použití povolených a zakázaných domén, takže pravidla jako ||baddomain.com^$domain=example.org|~foo.example.org
nebudou v AdGuardu pro iOS a AdGuardu pro Safari fungovat.
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
Modifikátor $header
umožňuje porovnat odpověď HTTP se specifickým záhlavím s (volitelně) specifickou hodnotou.
Syntaxe
$header "=" h_name [":" h_value]
h_value = string / regexp
kde:
h_name
— povinný název záhlaví HTTP. It is matched case-insensitively.h_value
— nepovinný výraz odpovídající hodnotě záhlaví HTTP, může to být jeden z následujících výrazů:string
— posloupnost znaků. Porovnává se s hodnotou záhlaví lexikograficky;regexp
— regulární výraz, který začíná a končí znakem/
. Vzor funguje stejně jako v základních pravidlech pro URL adresy, ale znaky/
,$
a,
musí být uvozeny pomocí\
.
Část modifikátoru ":" h_value
lze vynechat. V takovém případě modifikátor odpovídá pouze názvu záhlaví.
Příklady
||example.com^$header=set-cookie:foo
blokuje požadavky, jejichž odpovědi mají hlavičkuSet-Cookie
s hodnotou odpovídajícífoo
.||example.com^$header=set-cookie
blokuje požadavky, jejichž odpovědi mají hlavičkuSet-Cookie
s libovolnou hodnotou.@@||example.com^$header=set-cookie:/foo\, bar\$/
odblokuje požadavky, jejichž odpovědi mají hlavičkuSet-Cookie
s hodnotou odpovídající regulárnímu výrazufoo, bar$
.@@||example.com^$header=set-cookie
odblokuje požadavky, jejichž odpovědi mají hlavičkuSet-Cookie
s libovolnou hodnotou.
$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
Modifikátor $important
použitý na pravidlo zvyšuje jeho prioritu oproti pravidlům bez stejného modifikátoru. Dokonce i přes základní pravidla výjimek.
Další podrobnosti najdete v prioritách pravidel.
Příklady
! pravidlo blokování zablokuje všechny požadavky navzdory pravidlu výjimky
||example.org^$important
@@||example.org^
! pokud má pravidlo výjimky také modifikátor `$important`, bude mít přednost a žádné požadavky nebudou blokovány
||example.org^$important
@@||example.org^$important
$match-case
Tento modifikátor definuje pravidlo, které se vztahuje pouze na adresy odpovídající danému případu. Výchozí pravidla nerozlišují velká a malá písmena.
Příklady
*/BannerAd.gif$match-case
— toto pravidlo zablokujehttp://example.com/BannerAd.gif
, ale nehttp://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.
Všechny ostatní produkty již tento modifikátor podporují.
$method
Tento modifikátor omezuje rozsah pravidla na požadavky, které používají zadanou sadu metod HTTP. Negované metody jsou povoleny. Metody musí být zadány malými písmeny, ale při porovnávání se nerozlišují velká a malá písmena. Chcete-li do jednoho pravidla přidat více metod, použijte jako oddělovací znak svislou čáru |
.
Příklady
||evil.com^$method=get|head
blokuje pouze požadavky GET a HEAD na doméněevil.com
.||evil.com^$method=~post|~put
blokuje všechny požadavky na doméněevil.com
kromě POST nebo PUT.@@||evil.com$method=get
odblokuje pouze požadavky GET na doméněevil.com
.@@||evil.com$method=~post
odblokuje jakékoliv požadavky na doméněevil.com
kromě POST.
Pravidla se smíšenými negovanými a negovanými hodnotami jsou považována za neplatná. Takže např. pravidlo ||evil.com^$method=get|~head
bude zamítnuto.
Rules with $method
modifier are supported by AdGuard for Windows, Mac, and 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 se pokusí zavřít kartu prohlížeče s jakoukoli adresou, která odpovídá pravidlu blokování s tímto modifikátorem. Upozorňujeme, že ne všechny karty lze zavřít.
Příklady
||domain.com^$popup
— pokud se pokusíte přejít nahttp://domain.com/
z libovolné stránky v prohlížeči, nová karta, ve které má být zadaný web otevřen, bude tímto pravidlem zavřena.
$popup
modifier limitations
- The
$popup
modifier works best in AdGuard Browser Extension. - In AdGuard for iOS and AdGuard for Safari,
$popup
rules simply block the page right away. - In AdGuard for Windows, AdGuard for Mac, and AdGuard for Android, the
$popup
modifier may not detect a popup in some cases and it will not be blocked. The$popup
modifier applies thedocument
content type with a special flag which is passed to a blocking page. Samotná blokovací stránka může provést některé kontroly a zavřít okno, pokud se skutečně jedná o vyskakovací okno. V opačném případě by se stránka měla načíst. Lze to kombinovat s dalšími modifikátory typu požadavku, jako je$third-party
a$important
.
Rules with the $popup
modifier are not supported by AdGuard Content Blocker.
$third-party
Omezení požadavků třetích stran a vlastních požadavků. Požadavek třetí strany je požadavek z jiné domény. Např. požadavek na example.org
z domain.com
je požadavek třetí strany.
Aby mohla být žádost třetí strany považována za takovou, měla by splňovat jednu z následujících podmínek:
- Její odkazující doména není subdoménou cílové domény nebo naopak. Např. požadavek na
subdomain.example.org
zexample.org
není požadavek třetí strany - Její záhlaví
Sec-Fetch-Site
je nastaveno nacross-site
Příklady
$third-party
:
||domain.com^$third-party
— toto pravidlo bude použito na všechny domény, kromědomain.com
a její subdomény. Příklad požadavku třetí strany:http://example.org/banner.jpg
.
Pokud existuje modifikátor $third-party
, pravidlo se použije pouze na požadavky, které nejsou od třetích stran. To znamená, že musí být odeslány ze stejné domény.
$~third-party
:
||domain.com$~third-party
— toto pravidlo se vztahuje výhradně nadomain.com
. Příklad požadavku která není podán třetí stranou:http://domain.com/icon.ico
.
Místo plného názvu modifikátoru můžete použít kratší název (alias): $3p
.
$to
$to
omezuje rozsah pravidla na požadavky na zadané domény a jejich subdomény. To add multiple domains to one rule, use the |
character as a separator.
Příklady
/ads$to=evil.com|evil.org
zablokuje jakýkoliv požadavek naevil.com
neboevil.org
a jejich subdomény s cestou, která odpovídá/ads
./ads$to=~not.evil.com|evil.com
zablokuje jakýkoliv požadavek naevil.com
a její subdomény s cestou, která odpovídá/ads
, kromě požadavků nanot.evil.com
a její subdomény./ads$to=~good.com|~good.org
zablokuje všechny požadavky s cestou, která odpovídá/ads
, kromě požadavků nagood.com
nebogood.org
a jejich subdomény.
$denyallow
cannot be used together with $to
. 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, Mac, and Android with CoreLibs v1.12 or later and AdGuard Browser Extension with TSUrlFilter v2.1.3 or later.
Modifikátory typu obsahu
Existuje sada modifikátorů, které lze použít k omezení oblasti použití pravidla na určitý typ obsahu. Tyto modifikátory lze také kombinovat, aby zahrnovaly například obrázky i skripty.
V tom, jak AdGuard určuje typ obsahu na různých platformách, je velký rozdíl. U Rozšíření prohlížeče AdGuard je typ obsahu pro každý požadavek poskytován prohlížečem. AdGuard pro Windows, Mac a Android používají následující metodu: nejprve se aplikace pokusí určit typ požadavku podle záhlaví požadavku Sec-Fetch-Dest
nebo podle přípony názvu souboru. Pokud není požadavek v této fázi zablokován, určí se typ pomocí záhlaví Content-Type
na začátku odpovědi serveru.
Příklady modifikátorů typu obsahu
||example.org^$image
— odpovídá všem obrázkům zexample.org
.||example.org^$script,stylesheet
— odpovídá všem skriptům a stylům zexample.org
.||example.org^$~image,~script,~stylesheet
— odpovídá všem požadavkům naexample.org
kromě obrázků, skriptů a stylů.
Modifikátor \ Produkty | Aplikace CoreLibs | AdGuard pro Chromium | AdGuard pro Firefox | AdGuard pro iOS | AdGuard pro Safari | Blokátor obsahu AdGuard |
---|---|---|---|---|---|---|
$document | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$font | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$image | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$media | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$object | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$other | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$ping | ✅ * | ✅ | ✅ | ❌ | ❌ | ✅ |
$script | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$stylesheet | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$subdocument | ✅ * | ✅ | ✅ | ✅ | ✅ | ❌ |
$websocket | ✅ | ✅ | ✅ | ✅ * | ✅ * | ✅ |
$xmlhttprequest | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$webrtc 🚫 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$object-subrequest 🚫 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
- ✅ — plně podporováno
- ✅ * — podporováno, ale spolehlivost se může lišit nebo se mohou vyskytnout omezení; více informací naleznete v popisu modifikátoru
- ❌ — nepodporováno
- 🚫 — odstraněno a již nepodporováno
$document
Pravidlo odpovídá požadavkům na dokument hlavního rámce, tj. dokumenty HTML načtené na kartě prohlížeče. Neodpovídá hodnotám iframe, pro ten existuje modifikátor $subdocument
.
Ve výchozím nastavení AdGuard neblokuje požadavky, které se načítají na kartě prohlížeče (např. "obcházení hlavního rámce"). Cílem není zabránit načtení stránek, protože uživatel jasně uvedl, že chce, aby se tato stránka načetla. Pokud je však modifikátor $document
zadán explicitně, AdGuard tuto logiku nepoužije a zabrání načtení stránky. Místo toho se zobrazí "blokační stránka".
Pokud je tento modifikátor použit s pravidlem výjimky (@@
), zcela zakáže blokování na příslušných stránkách. Je to ekvivalentní použití modifikátorů $elemhide
, $content
, $urlblock
, $jsinject
, $extension
současně.
Příklady
@@||example.com^$document
zcela zakáže filtrování všech stránek naexample.com
a všech subdoménách.||example.com^$document
zablokuje požadavek na dokument HTML naexample.com
pomocí blokační stránky.||example.com^$document,redirect=noopframe
přesměruje požadavek na HTML dokument naexample.com
na prázdný HTML dokument.||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
.
Místo plného názvu modifikátoru můžete použít kratší název (alias): $doc
.
$font
Pravidlo odpovídá požadavkům na písma, např. s příponou .woff
.
$image
Pravidlo odpovídá požadavkům na obrázky.
$media
Pravidlo odpovídá požadavkům na mediální soubory — hudbu a video, např. soubory .mp4
.
$object
Pravidlo odpovídá prostředkům pluginů prohlížeče, např. Java nebo Flash.
$other
Pravidlo se vztahuje na požadavky, jejichž typ nebyl určen nebo neodpovídá výše uvedeným typům.
$ping
Pravidlo odpovídá požadavkům vyvolaným buď navigator.sendBeacon()
, nebo atributem ping
v odkazech.
AdGuard pro Windows, Mac a Android často nedokáží přesně detekovat navigator.sendBeacon()
. V seznamech filtrů, které mají používat AdGuard produkty založené na knihovně CoreLibs, se nedoporučuje používat $ping
.
Pravidla s modifikátorem $ping
nejsou podporována AdGuardem pro iOS a Safari.
$script
Pravidlo odpovídá požadavkům na skripty, např. javascript, vbscript.
$stylesheet
Pravidlo odpovídá požadavkům na soubory CSS.
Místo plného názvu modifikátoru můžete použít kratší název (alias): $css
.
$subdocument
Pravidlo odpovídá požadavkům na vestavěné stránky — značky HTML frame
a iframe
.
Příklady
||example.com^$subdocument
blokuje integrované požadavky (frame
aiframe
) naexample.com
a všechny její subdomény kdekoli.||example.com^$subdocument,domain=domain.com
blokuje integrované požadavky (frame
иiframe
) naexample.com
(a její subdomény) zdomain.com
a všech jejích subdomén.
Místo plného názvu modifikátoru můžete použít kratší název (alias): $frame
.
V AdGuardu pro Windows, macOS a Android jsou vnořené dokumenty detekovány hlavičkou Sec-Fetch-Dest pokud je přítomna. V opačném případě mohou být některé hlavní stránky považovány za dílčí dokumenty.
Pravidla s modifikátorem $subdocument
nejsou Blokátorem obsahu AdGuard podporována.
$websocket
Pravidlo se vztahuje pouze na připojení WebSocket.
Modifikátor $websocket
je podporován ve všech produktech AdGuardu kromě Blokátoru obsahu AdGuard. Pokud jde o AdGuard pro Safari a AdGuard pro iOS, je podporován v zařízeních s macOS Monterey (verze 12) a iOS 16 nebo novějším.
$xmlhttprequest
Pravidlo se vztahuje pouze na požadavky ajax (požadavky odeslané prostřednictvím objektu javascript XMLHttpRequest
).
Místo plného názvu modifikátoru můžete použít kratší název (alias): $xhr
.
AdGuard pro Windows, Mac a Android při filtrování starších prohlížečů nedokáže přesně detekovat tento typ a někdy jej detekuje jako $other
nebo $script
. Tento typ obsahu mohou spolehlivě detekovat pouze při filtrování moderních prohlížečů, které podporují Záhlaví požadavku na načtení metadat.
$object-subrequest
(odstraněno)
Modifikátor $object-subrequest
je odstraněn a již není podporován. Pravidla s tímto modifikátorem jsou považována za neplatná. Pravidlo odpovídá požadavkům pluginů prohlížeče (obvykle se jedná o Flash).
$webrtc
(odstraněno)
Tento modifikátor je odstraněn a již není podporován. Pravidla s tímto modifikátorem jsou považována za neplatná. Pokud potřebujete potlačit WebRTC, zvažte použít nowebrtc
scriptlet.
Pravidlo se vztahuje pouze na připojení WebRTC.
Příklady
||example.com^$webrtc,domain=example.org
blokuje připojení webRTC naexample.com
zexample.org
.@@*$webrtc,domain=example.org
zakáže RTC wrapper proexample.org
.
Modifikátory pravidel pro výjimky
Pravidla výjimek deaktivují ostatní základní pravidla pro adresy, kterým odpovídají. Začínají značkou @@
. Lze na ně aplikovat všechny výše uvedené základní modifikátory a mají také několik speciálních modifikátorů.
Doporučujeme také seznámit se s přehledem filtrů Adblock Plus, abyste lépe pochopili, jak pravidla výjimek vytvářet.
Modifikátor \ Produkty | Aplikace CoreLibs | AdGuard pro Chromium | AdGuard pro Firefox | AdGuard pro iOS | AdGuard pro Safari | Blokátor obsahu AdGuard |
---|---|---|---|---|---|---|
$content | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
$elemhide | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$extension | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$jsinject | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$stealth | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$urlblock | ✅ | ✅ | ✅ | ✅ * | ✅ * | ❌ |
$genericblock | ✅ | ✅ | ✅ | ✅ * | ✅ * | ❌ |
$generichide | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$specifichide | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — plně podporováno
- ✅ * — podporováno, ale spolehlivost se může lišit nebo se mohou vyskytnout omezení; více informací naleznete v popisu modifikátoru
- ❌ — nepodporováno
$content
Zakáže filtrování HTML, pravidla $hls
, $replace
a $jsonprune
na stránkách, které odpovídají pravidlu.
Příklady
@@||example.com^$content
zakáže všechna pravidla pro úpravu obsahu na stránkáchexample.com
a všech jích subdoménách.
$elemhide
Zakáže jakákoliv kosmetická pravidla na stránkách odpovídajících pravidlu.
Příklady
@@||example.com^$elemhide
zakáže všechna kosmetická pravidla naexample.com
a všech subdoménách.
Místo plného názvu modifikátoru můžete použít kratší název (alias): $ehide
.
$extension
Zakáže konkrétní uživatelské skripty nebo všechny uživatelské skripty pro danou doménu.
Syntaxe
$extension[="userscript_name1"[|"userscript_name2"[|"userscript_name3"[...]]]]
userscript_name(i)
označuje konkrétní název uživatelského skriptu, který má být modifikátorem zakázán. Modifikátor může obsahovat libovolný počet názvů uživatelských skriptů nebo žádný. V druhém případě modifikátor zakáže všechny uživatelské skripty.
Názvy uživatelských skriptů obvykle obsahují mezery nebo jiné speciální znaky, proto byste měli název uzavřít do uvozovek. Podporovány jsou jednoduché ('
) i dvojité ("
) uvozovky ASCII. Více názvů uživatelských skriptů by mělo být odděleno svislou čarou (|
). Pokud je však název uživatelského skriptu tvořen jedním slovem bez speciálních znaků, lze jej použít bez uvozovek.
Uživatelské skripty můžete také vyloučit přidáním znaku ~
před hodnotu. V tomto případě nebude uživatelský skript modifikátorem zakázán.
$extension=~"userscript name"
Když vyloučíte uživatelský skript, musíte umístit znak ~
mimo uvozovky.
Pokud název uživatelského skriptu obsahuje uvozovky ("
), čárky (,
) nebo svislé čáry (|
), musí být uvozen zpětným lomítkem (\
).
$extension="userscript name\, with \"quote\""
Příklady
@@||example.com^$extension="AdGuard Assistant"
zakáže uživatelský skriptAdGuard asistent
naexample.com
.@@||example.com^$extension=MyUserscript
zakáže uživatelský skriptMyUserscript
naexample.com
.@@||example.com^$extension='AdGuard Assistant'|'Popup Blocker'
zakáže uživatelské skriptyAdGuard asistent
aBlokátor vyskakovacích oken
naexample.com
.@@||example.com^$extension=~"AdGuard Assistant"
zakáže všechny uživatelské skripty naexample.com
, kroměAdGuard asistenta
.@@||example.com^$extension=~"AdGuard Assistant"|~"Popup Blocker"
zakáže všechny uživatelské skripty naexample.com
, kroměAdGuard asistenta
aBlokátor vyskakovacích oken
.@@||example.com^$extension
žádné uživatelské skripty nebudou fungovat naexample.com
.@@||example.com^$extension="AdGuard \"Assistant\""
zakáže uživatelský skriptAdGuard "Asistant"
naexample.com
.
- Pouze AdGuard pro Windows, Mac a Android jsou technicky schopné používat pravidla s modifikátorem
$extension
. - Rules with
$extension
modifier with specific userscript name are supported by AdGuard for Windows, Mac, and Android with CoreLibs v1.13 or later.
$jsinject
Zakazuje přidávání javascriptového kódu na stránku. O pravidlech skripletů a javascriptu si můžete přečíst dále.
Příklady
@@||example.com^$jsinject
zakáže javasript naexample.com
a všech subdoménách.
$stealth
Zakáže modul Režim utajení pro všechny odpovídající stránky a požadavky.
Syntax
$stealth [= opt1 [| opt2 [| opt3 [...]]]]
opt(i)
znamená určité možnosti Režimu utajení deaktivované modifikátorem. The modifier can contain any number of specific options (see below) or none. V druhém případě modifikátor vypne všechny funkce Režimu utajení.
Seznam dostupných možností modifikátoru:
searchqueries
zakáže možnost Skrýt vyhledávací dotazydonottrack
zakáže možnost Požádat webové stránky, aby vás nesledovaly3p-cookie
zakáže možnost Automatické odstranění cookies třetích stran1p-cookie
zakáže možnost Automatické odstranění cookies aktuální stránky3p-cache
zakáže možnost Zakázat mezipaměť pro požadavky třetích stran3p-auth
zakáže možnost Blokovat autorizační hlavičku třetích stranwebrtc
zakáže možnost Blokovat WebRTCpush
zakáže možnost Blokovat Push APIlocation
zakáže možnost Blokovat lokalizační APIflash
zakáže možnost Blokovat Flashjava
zakáže možnost Blokovat Javareferrer
zakáže možnost Skrýt třetím stranám referenční IDuseragent
zakáže možnost Skrýt agenta (identifikaci) Vašeho prohlížečeip
zakáže možnost Skrýt IP adresuxclientdata
zakáže možnost Odstranit X-Client-Data hlavičku z požadavků HTTPdpi
zakáže možnost Ochrana před DPI
Příklady
@@||example.com^$stealth
zakáže Režim utajení pro požadavkyexample.com
(a subdomény) s výjimkou blokování cookies a skrytí sledovacích parametrů (viz níže).@@||domain.com^$script,stealth,domain=example.com
zakáže Režim utajení pouze pro požadavky skriptů nadomain.com
(a subdoménách) naexample.com
a subdoménách.@@||example.com^$stealth=3p-cookie|dpi
zakáže blokování cookies třetích stran a opatření pro oklamání DPI proexample.com
.
Blokování cookies a odstranění sledovacích parametrů se provádí pomocí pravidel s modifikátory $cookie
, $urltransform
a $removeparam
. Pravidla výjimek, která obsahují pouze modifikátor $stealth
, tyto věci neprovedou. Pokud chcete pro danou doménu zcela zakázat všechny funkce Režimu utajení, musíte uvést všechny tři modifikátory: @@||example.org^$stealth,removeparam,cookie
.
- Možnosti modifikátoru musí být psány malými písmeny, tj.
$stealth=DPI
budou zamítnuty. - Možnosti modifikátoru nelze negovat, tj.
$stealth=~3p-cookie
bude zamítnuto. - AdGuard Browser Extension supports only
searchqueries
,donottrack
,referrer
,xclientdata
,1p-cookie
and3p-cookie
options.
- Stealth Mode is available in AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard Browser Extension. Všechny ostatní produkty budou ignorovat pravidla s modifikátorem
$stealth
. - 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
Zakáže blokování všech požadavků odeslaných ze stránek, které odpovídají pravidlu a zakáže všechna pravidla $cookie
.
Příklady
@@||example.com^$urlblock
— nebudou blokovány žádné požadavky odeslané zexample.com
a ze všech subdomén.
V AdGuardu pro iOS a AdGuardu pro Safari fungují pravidla $urlblock
jako $document exclusion — odblokování všeho.
Pravidla s modifikátorem $urlblock
nejsou Blokátorem obsahu AdGuard podporována.
Generická pravidla
Než budeme moci přistoupit k dalším modifikátorům, musíme provést definici generických pravidel. Pravidlo je generické, pokud není omezeno na konkrétní domény. Podporován je také zástupný znak *
.
Například tato pravidla jsou generická:
###banner
*###banner
#@#.adsblock
*#@#.adsblock
~domain.com###banner
||domain.com^
||domain.com^$domain=~example.com
A tato nejsou:
domain.com###banner
||domain.com^$domain=example.com
$genericblock
Zakáže generická základní pravidla na stránkách, které odpovídají pravidlu výjimky.
Příklady
@@||example.com^$genericblock
zakáže generická základní pravidla naexample.com
a všech subdoménách.
V AdGuardu pro iOS a AdGuardu pro Safari fungují pravidla $genericblock
jako $document exclusion — odblokování všeho.
Pravidla s modifikátorem $genericblock
nejsou Blokátorem obsahu AdGuard podporována.
$generichide
Zakáže všechna generická kosmetická pravidla na stránkách, které odpovídají pravidlu výjimky.
Příklady
@@||example.com^$generichide
zakáže všechna kosmetická pravidla naexample.com
a jejích subdoménách.
Místo plného názvu modifikátoru můžete použít kratší název (alias): $ghide
.
specifichide
Zakáže všechna specifická pravidla pro skrývání prvků a CSS, ale ne obecná pravidla. Má opačný účinek než $generichide
.
Příklady
@@||example.org^$specifichide
zakážeexample.org##.banner
, ale ne##.banner
.
Místo plného názvu modifikátoru můžete použít kratší název (alias): $shide
.
Všechna kosmetická pravidla — nejen ta specifická — lze zakázat pomocí modifikátoru $elemhide
.
Pravidla s modifikátorem $specifichide
nejsou AdGuardem pro iOS, Adguardem pro Safari a Blokátorem obsahu AdGuard podporována.
Pokročilé schopnosti
Tyto modifikátory mohou zcela změnit chování základních pravidel.
Modifikátor \ Produkty | Aplikace CoreLibs | AdGuard pro Chromium | AdGuard pro Firefox | AdGuard pro iOS | AdGuard pro Safari | Blokátor obsahu AdGuard |
---|---|---|---|---|---|---|
$all | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$badfilter | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$cookie | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$csp | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$hls | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$inline-font | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$inline-script | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$jsonprune | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$xmlprune | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$network | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$permissions | ✅ * | 🧩 | 🧩 * | ❌ | ❌ | ❌ |
$redirect | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$redirect-rule | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$referrerpolicy | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$removeheader | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$removeparam | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$replace | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
$urltransform | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
noop | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$empty 👎 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$mp4 👎 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — plně podporováno
- ✅ * — podporováno, ale spolehlivost se může lišit nebo se mohou vyskytnout omezení; více informací naleznete v popisu modifikátoru
- 🧩 — může být již implementováno ve verzích nightly nebo beta, ale není ještě podporováno ve verzích pro vydání
- ❌ — nepodporováno
- 👎 — deprecated; still supported but will be removed in the future
$all
$all
modifier is made of all content-types modifiers and $popup
. E.g. 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.
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).
Příklady
||example.com$badfilter
zakáže||example.com
||example.com$image,badfilter
zakáže||example.com$image
@@||example.com$badfilter
zakáže@@||example.com
||example.com$domain=domain.com,badfilter
zakáže||example.com$domain=domain.com
Rules with $badfilter
modifier can disable other basic rules for specific domains if they fulfill the following conditions:
- Pravidlo má modifikátor
$domain
- Pravidlo nemá hodnotu modifikátoru negované domény
~
v$domain
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.
Příklady
/some$domain=example.com|example.org|example.io
je zakázána proexample.com
pomocí/some$domain=example.com,badfilter
/some$domain=example.com|example.org|example.io
ije zakázána proexample.com
aexample.org
pomocí/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org
a/some$domain=example.io
jsou kompletně zakázány pomocí/some$domain=example.com|example.org|example.io,badfilter
/some$domain=example.com|example.org|example.io
je kompletně zakázána pomocí/some$domain=example.*,badfilter
/some$domain=example.*
je zakázána proexample.com
aexample.org
pomocí/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org|example.io
NENÍ zakázána proexample.com
pomocí/some$domain=example.com|~example.org,badfilter
, protože hodnota modifikátoru$domain
obsahuje negovanou doménu
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 ]]]
kde:
name
— nepovinné, řetězec nebo regulární výraz pro přiřazení názvu cookie.seconds
— počet sekund aktuálního času pro posunutí data vypršení platnosti souboru cookie.strategy
— řetězec pro strategii použití cookie Same-Site.
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:
- Nastaví datum vypršení platnosti na aktuální čas plus
3600
sekund - Přiměje cookie použít "laxní" strategii Same-Site.
Escaping special characters
If regular expression name
is used for matching, two characters must be escaped: comma ,
and dollar sign $
. Use backslash \
escape each of them. For example, escaped comma looks like this: \,
.
Příklady
||example.org^$cookie
blokuje všechny soubory cookie nastavené doménouexample.org
; to je ekvivalent nastavenímaxAge=0
$cookie=__cfduid
blokuje všude soubory cookie CloudFlare$cookie=/__utm[a-z]/
blokuje všude soubory cookie Google Analytics||facebook.com^$third-party,cookie=c_user
brání Facebooku ve sledování, i když jste přihlášeni
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
). Here's how it works:
@@||example.org^$cookie
odblokuje všechny soubory cookie nastavené doménouexample.org
@@||example.org^$urlblock
odblokuje všechny cookies nastavené doménouexample.org
a zakáže blokování všech požadavků odeslaných zexample.org
@@||example.org^$cookie=concept
odblokuje jeden soubor cookie s názvemconcept
@@||example.org^$cookie=/^_ga_/
odblokuje každý soubor cookie, který odpovídá regulárnímu výrazu
$cookie
rules support three types of modifiers: $domain
, $~domain
, $important
, $third-party
, and $~third-party
.
Rules with $cookie
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
$csp
This modifier completely changes the rule behavior. If it is applied to a rule, the rule will not block the matching request. 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. See examples section below.
Příklady
||example.org^$csp=frame-src 'none'
blokuje všechny obrázky na example.org a jejích subdoménách.@@||example.org/page/*$csp=frame-src 'none'
zakáže všechna pravidla s modifikátorem$csp
přesně odpovídajícím příznakemframe-src 'none'
na všech stránkách odpovídajících vzoru pravidla. Např. výše uvedené pravidlo.@@||example.org/page/*$csp
zakáže všechna pravidla$csp
na všech stránkách odpovídajících vzoru pravidla.||example.org^$csp=script-src 'self' 'unsafe-eval' http: https:
zakáže vložené skripty na všech stránkách odpovídajících vzoru pravidla.@@||example.org^$document
nebo@@||example.org^$urlblock
zakáží všechna pravidla$csp
na všech stránkách odpovídajících vzoru pravidla.
- V hodnotě
$csp
je zakázáno několik znaků:,
,$
. - Pravidla
$csp
podporují omezený seznam modifikátorů:$domain
,$important
,$subdocument
. - Pravidla s direktivami
report-*
jsou považována za neplatná.
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
odstraní segmenty, jejichž adresa URL odpovídá vzoru adresy URLurlpattern
. Vzor funguje stejně jako v základních pravidlech pro URL adresy, ale znaky/
,$
a,
musí být uvozeny pomocí\
uvnitřurlpattern
.||example.org^$hls=/regexp/options
odstraní segmenty, kde URL nebo jeden ze znaků (u určitých možností, pokud jsou přítomny) odpovídá regulárnímu výrazuregexp
. K dispozici jsou tyto možnostioptions
:t
— namísto testování adresy URL segmentu otestujte každý znak segmentu podle regulárního výrazu. Segment se shodným znakem je odstraněn;i
— regulární výraz nerozlišuje velká a malá písmena.
The characters /
, $
and ,
must be escaped with \
inside regexp
.
Výjimky
Basic URL exceptions shall not disable rules with $hls
modifier. They can be disabled as described below:
@@||example.org^$hls
zakáže všechna pravidla$hls
pro odpovědi z URL odpovídajících||example.org^
.@@||example.org^$hls=text
zakáže všechna pravidla$hls
s hodnotou modifikátoru$hls
shodným stext
pro odpovědi z URL odpovídajících||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.
Příklady
||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads
odstraní všechny segmenty se shodnou URL.||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i
dosáhne víceméně téhož pomocí regulárního výrazu namísto vzoru URL.||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
odstraní všechny segmenty, které mají odpovídající znak.
Anatomy of an HLS playlist
A quick summary of the specification:
- Seznam stop HLS je kolekce textových řádků
- Řádek může být prázdný, komentář (začíná
#
), znak (také začíná#
, lze jej rozpoznat pouze podle názvu) nebo URL - Řádek URL se nazývá "segment"
- Znaky se mohou vztahovat na jeden segment, tj. první řádek adresy URL za znakem, na všechny segmenty následující za znakem až do znaku se stejným názvem nebo na celý seznam skladeb
Some points specific to the operation of $hls
rules:
- Při odstranění segmentu se odstraní také všechny znaky, které se vztahují pouze k tomuto segmentu
- Pokud se znak vztahuje na více segmentů a všechny tyto segmenty jsou odstraněny, je odstraněna i znak
- Protože neexistuje způsob, jak rozpoznat různé druhy znaků podle syntaxe, rozpoznáváme všechny znaky uvedené v RFC a některé nestandardní znaky, se kterými jsme se setkali v praxi. Všechny řádky začínající na
#
. Ty, které nejsou rozpoznány jako znak, jsou předány bez úprav a nejsou porovnávány s pravidly - Značky nebudou přiřazeny, pokud se vztahují na celý seznam stop a k jejich odstranění nelze použít pravidla
$hls
, protože tyto typy pravidel jsou určeny pro odstraňování segmentů. Pokud víte, co děláte, můžete pomocí pravidel$replace
odstranit nebo přepsat pouze jeden znak ze seznamu skladeb
An example of a transformation done by the rules:
Original response
#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
Applied rules
||example.org^$hls=preroll
||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
Modified response
#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
- Pravidla
$hls
lze použít pouze v důvěryhodných filtrech. - Pravidla
$hls
jsou kompatibilní pouze s modifikátory$domain
,$third- party
,$app
,$important
,$match- case
a$xmlhttprequest
. $hls
pravidla platí pouze pro seznamy stop HLS, což je text kódovaný v UTF-8 začínající řádkem#EXTM3U
. Jakákoli jiná odpověď nebude těmito pravidly upravena.- Pravidla
$hls
neplatí, pokud je velikost původní odpovědi větší než 10 MB.
Rules with the $hls
modifier are supported by AdGuard for Windows, Mac, and 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. The rule ||example.org^$inline-script
is converting into the CSP-syntax rule:
||example.org^$csp=script-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
$inline-font
The $inline-font
modifier is designed to block inline fonts embedded into the web page, using Content Security Policy (CSP). 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
odstraní z odpovědi položky, které odpovídají upravenému výrazu JSONPathexpression
.
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:
- Výrazy skriptů nejsou podporovány
- Podporované výrazy filtrů jsou:
?(has <key>)
— "true", pokud má aktuální objekt zadaný klíč?(key-eq <key> <value>)
— "true", pokud má aktuální objekt zadaný klíč a jeho hodnota se rovná zadané hodnotě?(key-substr <key> <value>)
— "true", pokud je zadaná hodnota podřetězcem hodnoty zadaného klíče aktuálního objektu
- Mezery mimo řetězce s dvojitými nebo jednoduchými uvozovkami nemají žádný význam
- Lze použít řetězce s dvojitými i jednoduchými uvozovkami
- Výrazy končící na
..
nejsou podporovány - V hranatých závorkách lze zadat vícero dílků pole
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.
Výjimky
Basic URL exceptions shall not disable rules with the $jsonprune
modifier. They can be disabled as described below:
@@||example.org^$jsonprune
zakáže všechna pravidla$jsonprune
pro odpovědi z URL odpovídajících||example.org^
.@@||example.org^$jsonprune=text
zakáže všechna pravidla$jsonprune
s hodnotou modifikátoru$jsonprune
shodným stext
pro odpovědi z URL odpovídajících||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.
Příklady
||example.org^$jsonprune=\$..[one\, "two three"]
odstraní všechny výskyty klíčů "one" a "two three" kdekoli v dokumentu JSON.
Input
{
"one": 1,
"two": {
"two three": 23,
"four five": 45
}
}
Output
{
"two": {
"four five": 45
}
}
||example.org^$jsonprune=\$.a[?(has ad_origin)]
odstraní všechny potomkya
, které mají klíčad_origin
.
Input
{
"a": [
{
"ad_origin": "https://example.org",
"b": 42
},
{
"b": 1234
}
]
}
Output
{
"a": [
{
"b": 1234
}
]
}
||example.org^$jsonprune=\$.*.*[?(key-eq 'Some key' 'Some value')]
odstraní všechny položky, které jsou na úrovni vnoření 3 a mají vlastnost "Some key" rovnu "Some value".
Input
{
"a": {"b": {"c": {"Some key": "Some value"}, "d": {"Some key": "Other value"}}},
"e": {"f": [{"Some key": "Some value"}, {"Some key": "Other value"}]}
}
Output
{
"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[?(má "\$.abc")]
odstraní všechny potomkyelems
, které mají vlastnost volitelnou výrazem JSONPath$.abc
.
Input
{
"elems": [
{
"a": {"b": {"c": 123}},
"k": "v"
},
{
"d": {"e": {"f": 123}},
"k1": "v1"
}
]
}
Output
{
"elems": [
{
"d": {"e": {"f": 123}},
"k1": "v1"
}
]
}
||example.org^$jsonprune=\$.elems[?(key-eq "\$.a.b.c" "abc")]
odstraní všechny potomkyelems
, které mají vlastnost volitelnou pomocí výrazu JSONPath$.a.b.c
s hodnotou rovnou"abc"
.
Input
{
"elems": [
{
"a": {"b": {"c": 123}},
},
{
"a": {"b": {"c": "abc"}}
}
]
}
Output
{
"elems": [
{
"a": {"b": {"c": 123}}
}
]
}
$jsonprune
pravidla jsou kompatibilní pouze s těmito modifikátory:$domain
,$third-party
,$app
,$important
,$match-case
a$xmlhttprequest
.- Pravidla
$jsonprune
neplatí, pokud je velikost původní odpovědi větší než 10 MB.
Rules with the $jsonprune
modifier are supported by AdGuard for Windows, Mac, and 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
odstraní z odpovědi položky, které odpovídají výrazu XPathexpression
.
Due to the way rule parsing works, the characters $
and ,
must be escaped with \
inside expression
.
Výjimky
Basic URL exceptions shall not disable rules with the $xmlprune
modifier. They can be disabled as described below:
@@||example.org^$xmlprune
zakáže všechna pravidla$xmlprune
pro odpovědi z URL odpovídajících||example.org^
.@@||example.org^$xmlprune=text
zakáže všechna pravidla$xmlprune
s hodnotou modifikátoru$xmlprune
shodným stext
pro odpovědi z URL odpovídajících||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.
Příklady
||example.org^$xmlprune=/bookstore/book[position() mod 2 = 1]
odstraní z knihkupectví knihy s lichými čísly.
Input
<?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>
Output
<?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]
odstraní knihy z roku 2003 z knihkupectví.
Input
<?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>
Output
<?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=//*/@*
odstraní všechny atributy ze všech prvků.
Input
<?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>
Output
<?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
pravidla jsou kompatibilní pouze s těmito modifikátory:$domain
,$third-party
,$app
,$important
,$match-case
a$xmlhttprequest
.- Pravidla
$xmlprune
neplatí, pokud je velikost původní odpovědi větší než 10 MB.
Rules with the $xmlprune
modifier are supported by AdGuard for Windows, Mac, and 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.
- Pravidla
$network
odpovídají pouze IP adresám! Nelze je použít k zablokování nebo odblokování přístupu k doméně. - Chcete-li se shodovat s adresou IPv6, musíte použít sbalenou syntaxi, např.
[2001:4860:4860::8888]$network
namísto[2001:4860:4860:0:0:0:0:8888]$network
. - Pravidlo seznamu povolených
$network
způsobí, že AdGuard bude obcházet data odpovídajícího koncového bodu, proto nebude provádět žádné další filtrování. - Pokud část IP začíná a končí znakem
/
, je považována za regulární výraz.
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.
Příklady
174.129.166.49:3478^$network
blokuje přístup k174.129.166.49:3478
(ale ne k174.129.166.49:34788
).[2001:4860:4860::8888]:443^$network
blokuje přístup k[2001:4860:4860::8888]:443
.174.129.166.49$network
blokuje přístup k174.129.166.49:*
.@@174.129.166.49$network
způsobí, že AdGuard bude koncovému bodu předávat data. Žádná jiná pravidla se neuplatňují./.+:3[0-9]{4}/$network
blokuje přístup k libovolnému portu od 30000 do 39999./8.8.8.(:?8|4)/$network
blokuje přístup k8.8.8.8
a8.8.8.4
.
Only AdGuard for Windows, Mac, and Android are technically capable of using rules with $network
modifier.
$permissions
This modifier completely changes the rule behavior. If it is applied to a rule, the rule will not block the matching request. 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 to separate features instead of a comma.
The list of available directives is available here.
$permissions
value can be empty in the case of exception rules — see examples below.
Příklady
||example.org^$permissions=autoplay=()
zakáže automatické přehrávání médií vyžádaných prostřednictvím rozhraníHTMLMediaElement
v rámciexample.org
.@@||example.org/page/*$permissions=autoplay=()
zakáže všechna pravidla s modifikátorem$permissions
přesně odpovídajícím příznakemautoplay=()
na všech stránkách odpovídajících vzoru pravidla. Např. výše uvedené pravidlo. 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
zakáže všechna pravidla$permissions
na všech stránkách odpovídajících vzoru pravidla.$domain=example.org|example.com,permissions=storage-access=()\, camera=()
zakáže použití API pro přístup k úložišti pro vyžádání přístupu k nerozděleným souborům cookies a používání vstupních zařízení videa napříčexample.org
aexample.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
nebo@@||example.org^$urlblock
zakáží všechna pravidla$permission
na všech stránkách odpovídajících vzoru pravidla.
$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, Mac, and 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, Mac, and 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.
Zakázání pravidel $redirect
||example.org/script.js$script,redirect=noopjs
— toto pravidlo přesměruje všechny požadavky naexample.org/script.js
na zdroj s názvemnoopjs
.||example.org/test.mp4$media,redirect=noopmp4-1s
— toto pravidlo přesměruje všechny požadavky naexample.org/test.mp4
na zdroj s názvemnoopmp4-1s
.@@||example.org^$redirect
zakáže všechna pravidla$redirect
pro URL adresy, které odpovídají||example.org^
.@@||example.org^$redirect=nooptext
zakáže všechna pravidla s$redirect=nooptext
pro všechny požadavky, které odpovídají||example.org^
.
More information on redirects and their usage is available on GitHub.
Priority pravidel $redirect
$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
.
Další podrobnosti najdete v prioritách pravidel.
- Pravidla s modifikátorem
$redirect
nejsou podporována Blokátorem obsahu AdGuard, AdGuardem pro iOS a AdGuardem pro Safari. $redirect
v uBlock Origin podporuje zadané priority, např.$redirect=noopjs:42
. AdGuard to nepodporuje a místo toho pouze zahodí prioritní 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.
Další podrobnosti najdete v prioritách pravidel.
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.
Příklady
||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, and AdGuard for Safari.
$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.
Příklady
||example.com^$referrerpolicy=unsafe-url
přepíše zásady odkazování proexample.com
pomocíunsafe-url
.@@||example.com^$referrerpolicy=unsafe-url
zakáže předchozí pravidlo.@@||example.com/abcd.html^$referrerpolicy
zakáže všechna pravidla$referrerpolicy
naexample.com/abcd.html
.
Rules with the $referrerpolicy
modifier are supported by AdGuard for Windows, Mac, and 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
Basic syntax
||example.org^$removeheader=header-name
odstraní odpověď záhlaví s názvemheader-name
||example.org^$removeheader=request:header-name
odstraní požadavek záhlaví s názvemheader-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
neguje všechna pravidla$removeheader
pro URL adresy, které odpovídají||example.org^
.@@||example.org^$removeheader=header
neguje všechna pravidla s$removeheader=header
pro jakýkoliv požadavek, který odpovídá||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.
Příklady
||example.org^$removeheader=refresh
odstraní záhlavíRefresh
ze všech HTTP odpovědí vrácených doménouexample.org
a jejími subdoménami.||example.org^$removeheader=request:x-client-data
odstraní záhlavíX-Client-Data
ze všech požadavků HTTP.Další blok pravidel odstraní záhlaví
Refresh
aLocation
ze všech odpovědí HTTP vrácených doménouexample.org
s výjimkou požadavků naexample.org/path/*
, u kterých nebudou odstraněny žádné záhlaví:||example.org^$removeheader=refresh
||example.org^$removeheader=location
@@||example.org/path/$removeheader
This type of rules can be used only in trusted filters.
Aby nedošlo k narušení bezpečnosti, nelze z níže uvedeného seznamu odstranit záhlaví
$removeheader
: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
Pravidla
$removeheader
jsou kompatibilní s$domain
,$third-party
,$app
,$important
,$match-case
, a modifikátory typu obsahu, jako např.$script
a$stylesheet
. Pravidla s jinými modifikátory jsou považována za neplatná a budou vyřazena.
Rules with $removeheader
modifier are supported by AdGuard for Windows, Mac, and 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.
$removeparam
rules that do not have any content type modifiers will match only requests where content type is document
.
Syntax
Basic syntax
$removeparam=param
odstraní parametr dotazu s názvemparam
z URL libovolného požadavku, např. požadavek nahttp://example.com/page?param=1&another=2
bude transformován nahttp://example.com/page?another=2
.
Rules with $removeparam
modifier are supported by AdGuard for Windows, Mac and, Android with CoreLibs v1.7 or later and AdGuard Browser Extension v3.6 or later.
Regular expressions
You can also use regular expressions to match query parameters and/or their values:
$removeparam=/regexp/[options]
— odstraní parametry dotazu, které odpovídají regulárnímu výrazuregexp
z adres URL jakéhokoli požadavku. Na rozdíl od základní syntaxe to znamená "odebrat parametry dotazu normalizované na řetězecname=value
, který odpovídá regulárnímu výrazuregexp
".[options]
zde je seznam možností regulárních výrazů. V současné době je jedinou podporovanou možnostíi
, díky čemuž se nerozlišují malá a velká písmena.
Escaping special characters
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:
- Vypadá to jako
$/
- Nalevo od něj je další znak lomítka
/
- Nalevo od tohoto znaku lomítka je další znak dolaru bez uvození
$
Remove all query parameters
Specify naked $removeparam
to remove all query parameters:
||example.org^$removeparam
— odstraní všechny parametry dotazu z adres URL odpovídajících||example.org^
.
Inversion
Use ~
to apply inversion:
$removeparam=~param
— odstraní všechny parametry dotazu s názvem odlišným odparam
.$removeparam=~/regexp/
— odstraní všechny parametry dotazu, které neodpovídají regulárnímu výrazuregexp
.
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
neguje všechna pravidla$removeparam
pro URL adresy, které odpovídají||example.org^
.@@||example.org^$removeparam=param
neguje všechna pravidla s$removeparam=param
pro jakýkoliv požadavek, který odpovídá||example.org^
.@@||example.org^$removeparam=/regexp/
neguje všechna pravidla s$removeparam=/regexp/
pro jakýkoliv požadavek, který odpovídá||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.
Příklady
$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
odstraní parametr dotazuutm_source
ze všech požadavků.$removeparam=/utm_.*/
odstraní všechny parametryutm_* query
z URL libovolného požadavku, např. požadavek nahttp://example.com/page?utm_source=test
bude transformován nahttp://example.com/page
.$removeparam=/^utm_source=campaign$/
odstraní parametr dotazuutm_source
s hodnotou rovnoucampaign
. Nemá vliv na ostatní parametryutm_source
.
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.
- Pravidla s modifikátorem
$removeparam
lze použít pouze v důvěryhodných filtrech. - Pravidla
$removeparam
jsou kompatibilní se základními modifikátory, modifikátory typu obsahu a s modifikátory$important
a$app
. Pravidla s jinými modifikátory jsou považována za neplatná a budou vyřazena.
- Pravidla s modifikátorem
$removeparam
podporuje AdGuard pro Windows, Mac, Android a Rozšíření prohlížeče AdGuard pro Chrome, Firefox a Edge. $removeparam
syntax for regular expressions is supported by AdGuard Browser Extension v4.0 and AdGuard for Windows, Mac, and Android with CoreLibs v1.8 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
This modifier completely changes the rule behavior. 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.
Features
- Pravidla
$replace
platí pro jakoukoli textovou odpověď, ale neplatí pro binární (media
,image
,object
atd.). - Pravidla
$replace
neplatí, pokud je velikost původní odpovědi větší než 10 MB. - Pravidla
$replace
mají vyšší prioritu než ostatní základní pravidla (včetně pravidel výjimek). Pokud tedy požadavek odpovídá dvěma různým pravidlům, z nichž jedno má modifikátor$replace
, použije se toto pravidlo. - Pravidla výjimek na úrovni dokumentu s modifikátory
$content
nebo$document
zakáží pravidla$replace
pro požadavky, které jim odpovídají. - Ostatní pravidla výjimek na úrovni dokumentu (
$generichide
,$elemhide
nebo modifikátory$jsinject
) se uplatňují vedle pravidel$replace
. To znamená, že můžete upravit obsah stránky pomocí pravidla$replace
a zároveň zde zakázat kosmetická pravidla.
$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
— regulární výraz.replacement
— řetězec, který bude použit k nahrazení řetězce odpovídajícíhoregexp
.modifiers
— příznaky regulárního výrazu. Napříkladi
— necitlivé vyhledávání nebos
— jednořádkový režim.
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: \,
.
Příklady
||example.org^$replace=/(<VAST[\s\S]*?>)[\s\S]*<\/VAST>/\$1<\/VAST>/i
There are three parts in this rule:
regexp
—(<VAST(.|\s)*?>)(.|\s)*<\/VAST>
;replacement
—\$1<\/VAST>
kde$
je uvozeno;modifikátory
—i
pro necitlivé vyhledávání.
You can see how this rule works here: http://regexr.com/3cesk
Multiple $replace
rules
||example.org^$replace=/X/Y/
||example.org^$replace=/Z/Y/
@@||example.org/page/*$replace=/Z/Y/
- Jak pravidlo 1, tak pravidlo 2 se použijí na všechny požadavky odeslané na
example.org
. - Pravidlo 2 je zakázáno pro požadavky odpovídající na
||example.org/page/
, ale pravidlo 1 stále funguje!
Disabling $replace
rules
@@||example.org^$replace
zakáže všechna pravidla$replace
odpovídající na||example.org^
.@@||example.org^$document
nebo@@||example.org^$content
zakáže všechna pravidla$replace
pocházející ze stránekexample.org
včetně stránky samotné.
Rules with $replace
modifier can be used only in trusted filters.
Rules with $replace
modifier are supported by AdGuard for Windows, Mac, and 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 the text matched by the regular expression.
Features
$urltransform
pravidla platí pro jakýkoli text URL požadavku.$urltransform
pravidla mohou také upravit část dotazu URL.$urltransform
nebude použito, pokud je původní URL blokována jinými pravidly.$urltransform
se použije před pravidly$removeparam
.
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
— regulární výraz.replacement
— řetězec, který bude použit k nahrazení řetězce odpovídajícíhoregexp
.modifiers
— příznaky regulárního výrazu. Napříkladi
— necitlivé vyhledávání nebos
— jednořádkový režim.
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: \,
.
Příklady
||example.org^$urltransform=/(pref\/).*\/(suf)/\$1\$2/i
There are three parts in this rule:
regexp
—(pref\/).*\/(suf)
;replacement
—\$1\$2
kde$
je uvozeno;modifikátory
—i
pro necitlivé vyhledávání.
Multiple $urltransform
rules
||example.org^$urltransform=/X/Y/
||example.org^$urltransform=/Z/Y/
@@||example.org/page/*$urltransform=/Z/Y/
- Jak pravidlo 1, tak pravidlo 2 se použijí na všechny požadavky odeslané na
example.org
. - Pravidlo 2 je zakázáno pro požadavky odpovídající na
||example.org/page/
, ale pravidlo 1 stále funguje!
Re-matching rules after transforming the URL
If the $urltransform
rule is applied to a request, all the rules will be re-evaluated against the new URL.
E.g., with the following rules:
||example.com^$urltransform=/firstpath/secondpath/
||example.com/secondpath^
the request to https://example.com/firstpath
will be blocked before it is sent.
However, $urltransform
rules will not be re-applied in this case to avoid infinite recursion, e.g., with the following rules:
||example.com/firstpath^$urltransform=/firstpath/secondpath/
||example.com/secondpath^$urltransform=/secondpath/firstpath/
the request to https://example.com/fisrtpath
will be transformed to https://example.com/secondpath
and the second rule will not be applied.
Disabling $urltransform
rules
@@||example.org^$urltransform
zakáže všechna pravidla$urltransform
odpovídající na||example.org^
.@@||example.org^$urltransform=/Z/Y/
zakáže pravidlo s$urltransform=/Z/Y/
pro jakýkoliv požadavek, který odpovídá||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 be used only 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 any length and can appear in a rule as many times as needed.
Příklady
||example.com$_,removeparam=/^ss\\$/,_,image
||example.com$replace=/bad/good/,___,~third-party
Rules with noop
modifier are not supported by AdGuard Content Blocker.
$empty
(zastaralé)
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.
Příklady
||example.org^$empty
vrátí prázdnou odpověď na všechny požadavky naexample.org
a všechny subdomény.
Rules with $empty
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
$mp4
(zastaralé)
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.
Příklady
||example.com/videa/$mp4
zablokuje všechna stahování videa z||example.com/videa/*
a změní odpověď na zástupný videoklip.
Rules with $mp4
modifier are not supported by AdGuard Content Blocker, AdGuard for iOS, and AdGuard for Safari.
Priority pravidel
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, it depends on the filtering engine implementation which one will be selected.
The concept of rule priorities becomes increasingly important in light of Manifest V3 as the existing rules need to be converted to declarativeNetRequest rules.
Výpočet priority
To calculate priority, we've categorized modifiers into different groups. These groups are ranked based on their priority, from lowest to highest. 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.
The base priority of any rule is 1. If the calculated priority is a floating-point number, it will be rounded up to the smallest integer greater than or equal to the calculated priority.
- The concept of priority has been introduced in TSUrlFilter v2.1.0 and CoreLibs v1.13. Dříve neměl AdGuard žádný speciální algoritmus pro výpočet priorit a zpracování kolizí se mohlo lišit v závislosti na produktu a verzi AdGuardu.
- Aplikace AdGuard pro iOS, Safari a Blokátor obsahu AdGuard se spoléhají na implementaci prohlížečů a nemohou dodržovat zde uvedená pravidla.
Modifier aliases (1p
, 3p
, etc.) are not included in these categories, however, they are utilized within the engine to compute the rule priority.
Základní modifikátory, přítomnost každého z nich přidává 1 k prioritě
$app
s negovanými aplikacemi pomocí~
,$denyallow
,$domain
s negovanými doménami pomocí~
,$match-case
,$method
s negovanými metodami pomocí~
,$third-party
,$to
,- omezené typy obsahu s
~
.
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.
Definované modifikátory typu obsahu, definované metody, definovaná záhlaví, $all, $popup, specifické výjimky
All allowed 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
nebo $app
s povolenými doménami nebo aplikacemi
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
.
Pravidla $redirect
Each of which adds 10^3
to rule priority.
Specifické výjimky
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
.
Pravidla seznamu povolených
Modifier @@
adds 10^5
to rule priority.
Pravidla $important
Modifier $important
adds 10^6
to rule priority.
Pravidla, pro která není stanovena váha priority
Other modifiers, which are supposed to perform additional post- or pre-processing of requests, do not add anything to the rules priority.
Příklady
||example.com^
Váha pravidla bez modifikátorů:
1
.||example.com^$match-case
Váha pravidla: základní + váha modifikátoru z kategorie 1:
1 + 1 = 2
.||example.org^$removeparam=p
Váha pravidla: základní váha + 0, protože $removeparam není zahrnuto do výpočtu priority:
1 + 0 = 1
.||example.org^$document,redirect=nooptext
Váha pravidla: základní + povolený typ obsahu, kategorie 3 + $redirect z kategorie 6:
1 + (100 + 100 / 1) + 1000 = 1201
.@@||example.org^$removeparam=p,document
Váha pravidla: základní váha + pravidlo seznamu povolených kategorie 5 + 0, protože $removeparam není zapojeno do výpočtu priority + povolený typ obsahu kategorie 2:
1 + 10000 + 0 + (50 + 50 / 1) = 10101
.@@||example.com/ad/*$domain=example.org|example.net,important
Váha pravidla: základní váha + pravidlo seznamu povolených kategorie 5 + důležité pravidlo kategorie 7 + povolené domény kategorie 3:
1 + 10000 + 1000000 + (100 + 100 / 2) = 1010152
.@@||example.org^$document
bez dalších modifikátorů je aliasem pro@@||example.com^$elemhide,content,jsinject,urlblock,extension
Váha pravidla: základní váha + specifické výjimky, kategorie 4 + dva povolené typy obsahu (dokument a subdokument) kategorie 2:
1 + 10000 * 4 + (50 + 50 / 2) = 40076
.*$script,domain=a.com,denyallow=x.com|y.com
Váha pravidla: základní váha + povolený typ obsahu kategorie 2 + povolená doména, kategorie 3 + denyallow kategorie 1:
1 + (50 + 50/1) + (100 + 100 / 1) + 1 = 303
.||example.com^$all
— alias na||example.com^$document,subdocument,image,script,media,etc. + $popup
Váha pravidla: základní váha + vyskakovací okno (kategorie 1) + povolené typy obsahu (kategorie 2):
1 + 1 + (50 + 50/12) = 55
.
Ostatní pravidla
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.
Kategorie \ Produkty | Aplikace CoreLibs | AdGuard pro Chromium | AdGuard pro Firefox | AdGuard pro iOS | AdGuard pro Safari | Blokátor obsahu AdGuard |
---|---|---|---|---|---|---|
Skrytí prvků | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Pravidla CSS | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
Rozšířené CSS | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
HTML filtrování | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
JavaScript | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
Scriptlety | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
- ✅ — plně podporováno
- ❌ — nepodporováno
Kosmetická pravidla
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.
Pravidla pro skrytí prvků
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 selektor definuje prvky, které mají být skryty.domains
— omezení domény pro dané pravidlo.
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
.
Pokud chcete, aby se pravidlo nevztahovalo na určité domény, začněte název domény znakem ~
. 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.
Příklady
example.com##div.textad
— skryjediv
s třídoutextad
na doméněexample.com
a všech subdoménách.example.com,example.org###adblock
— skryje prvek s atributemid
, který se rovnáadblock
naexample.com
,example.org
a všech subdoménách.~example.com##.textad
— skryje prvek s třídoutextad
na všech doménách kroměexample.com
a jejích subdomén.
Omezení
Safari does not support both permitted and restricted domains. So the rules like example.org,~foo.example.org##.textad
are invalid in AdGuard for Safari.
Výjimky
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.
Pravidla CSS
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
— selektor CSS, který definuje prvky, na které chceme styl použít.domains
— omezení domény pro dané pravidlo. Stejné zásady jako v pravidlech pro skrývání prvků.style
— styl CSS, který chceme použít na vybrané prvky.
Příklady
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.
Výjimky
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.
Rozšířené CSS selektory
- Omezení
- Pseudo-třída
:has()
- Pseudo-třída
:contains()
- Pseudo-třída
:matches-css()
- Pseudo-třída
:matches-attr()
- Pseudo-třída
:matches-property()
- Pseudo-třída
:xpath()
- Pseudo-třída
:nth-ancestor()
- Pseudo-třída
:upward()
- Pseudo-třída
:remove()
a pseudo-vlastnostremove
- Pseudo-třída
:is()
- Pseudo-třída
:not()
- Pseudo-třída
:if-not()
(odstraněno)
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.
Application area
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:
#?#
— pro skrytí prvku,#@?#
— pro výjimky#$?#
— pro pravidlo CSS,#@$?#
— pro výjimky
We strongly recommend using these markers any time when you use an extended CSS selector.
Příklady
example.org#?#div:has(> a[target="_blank"][rel="nofollow"])
— toto pravidlo blokuje všechny prvkydiv
obsahující podřízený uzel, který má odkaz s atributy[target="_blank"][rel="nofollow"]
. Pravidlo platí pouze proexample.org
a její subdomény.example.com#$?#h3:contains(cookies) { display: none!important; }
— toto pravidlo nastaví styldisplay: none!important
všem prvkůmh3
, které obsahují slovocookies
. Pravidlo platí pouze proexample.com
a všechny její subdomény.example.net#?#.banner:matches-css(width: 360px)
— toto pravidlo blokuje všechny prvky.banner
s vlastností styluwidth: 360px
. Pravidlo platí pouze proexample.net
a její subdomény.example.net#@?#.banner:matches-css(width: 360px)
— toto pravidlo zakáže předchozí pravidlo.
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 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.
Limitace ExtendedCss
Konkrétní pseudo-třída může mít svá vlastní omezení:
:has()
,:xpath()
,:nth-ancestor()
,:upward()
,:is()
,:not()
, and:remove()
.
Pseudo-třída :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
— nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvkuselector
— povinný, standardní nebo rozšířený selektor CSS
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):
- zakazuje
:has()
uvnitř pseudo akceptující pouze složené selektory; - zakazuje
:has()
po běžných pseudoprvcích.
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.
Příklady
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-třída :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
— nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvkushoda
— povinný, řetězec nebo regulární výraz pro shodu prvkutextContent
. Příznaky regulárních výrazů jsou podporovány.
Příklady
For such 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:
! prostý text
div:contains(banner)
! regulární výraz
div:contains(/as .* banner/)
! regulární výraz s příznaky
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-třída :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
— nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvkupseudo-element
— volitelný, platný standardní pseudoprvek, např.before
,after
,first-line
atd.property
— povinný, název vlastnosti CSS, pro kterou se má prvek zkontrolovatpattern
— required, a value pattern that is using the same simple wildcard matching as in the basic url filtering rules OR a regular expression. Při tomto typu porovnávání, AdGuard vždy porovnává bez ohledu na velikost písmen. V případě regulárního výrazu vypadá vzor takto:/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.+/)
.
Příklady
For such 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-třída :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
— nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvkuname
— povinný, jednoduchý řetězec nebo řetězec se zástupným znakem nebo regulární výraz pro shodu názvu atributuvalue
— volitelný, jednoduchý řetězec nebo řetězec se zástupným znakem nebo regulární výraz pro shodu hodnoty atributu
Escaping special characters
For regexp patterns "
and \
should be escaped, e.g. div:matches-attr(class=/[\\w]{5}/)
.
Příklady
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-třída :matches-property()
The :matches-property()
pseudo-class allows selecting an element by matching its properties.
Syntax
[target]:matches-property("name"[="value"])
target
— nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvkuname
— povinný, jednoduchý řetězec nebo řetězec se zástupným znakem nebo regulární výraz pro porovnávání názvů vlastností prvkůvalue
— volitelný, jednoduchý řetězec nebo řetězec se zástupným znakem nebo regulární výraz pro porovnávání názvů vlastností prvků
Escaping special characters
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
.
Příklady
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:
- Zkontrolujte prvek stránky nebo jej vyberte na kartě
Elements
v nástroji DevTools prohlížeče - Spusťte
console.dir($0)
na kartěConsole
Regexp patterns do not support flags.
Pseudo-třída :xpath()
The :xpath()
pseudo-class allows selecting an element by evaluating an XPath expression.
Syntax
[target]:xpath(expression)
target
— volitelný, standardní nebo rozšířený selektor CSSexpression
— povinný, platný výraz XPath
: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().
Příklady
: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-třída :nth-ancestor()
The :nth-ancestor()
pseudo-class allows to lookup the nth ancestor relative to the previously selected element.
subject:nth-ancestor(n)
subjectr
— povinný, standardní nebo rozšířený selektor CSSn
— povinné, číslo >= 1 a < 256, vzdálenost k potřebnému předkovi od prvku vybraného pomocísubject
Syntax
subject:nth-ancestor(n)
subjectr
— povinný, standardní nebo rozšířený selektor CSSn
— povinné, číslo >= 1 a < 256, vzdálenost k potřebnému předkovi od prvku vybraného pomocísubject
:nth-ancestor()
limitations
The :nth-ancestor()
pseudo-class is not supported inside the argument of the :not()
pseudo-class.
Příklady
For such 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-třída :upward()
The :upward()
pseudo-class allows to lookup the ancestor relative to the previously selected element.
Syntax
subject:upward(ancestor)
subjectr
— povinný, standardní nebo rozšířený selektor CSSancestor
— povinný, specifikace pro předka prvku vybraného pomocísubject
, lze nastavit jako:- číslo >= 1 a < 256 pro vzdálenost k požadovanému předkovi, stejně jako u položky
:nth-ancestor()
- standardní selektor CSS pro shodu nejbližšího předka
- číslo >= 1 a < 256 pro vzdálenost k požadovanému předkovi, stejně jako u položky
:upward()
limitations
The :upward()
pseudo-class is not supported inside the argument of the :not()
pseudo-class.
Příklady
For such 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-třída :remove()
a pseudo-vlastnost 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
— povinný, standardní nebo rozšířený selektor CSS
:remove()
a 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.
Příklady
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-třída :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
— nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvkuselectors
— odpouštějící seznam selektorů standardních nebo rozšířených selektorů. U rozšířených selektorů jsou podporovány pouze složené selektory, nikoli komplexní.
: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.
Příklady
#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-třída :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
— nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvkuselectors
— seznam standardních nebo rozšířených selektorů
: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.
Příklady
#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-třída :if-not()
(odstraněno)
The :if-not()
pseudo-class is removed and is no longer supported. Pravidla s tímto modifikátorem jsou považována za neplatná.
This pseudo-class was basically a shortcut for :not(:has())
. It was supported by ExtendedCss for better compatibility with some filters subscriptions.
Přednost kosmetických pravidel
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 pravidla filtrování
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, Mac, 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
— název prvku s malými písmeny, např.div
neboscript
.domains
— omezení domény pro dané pravidlo. Stejné zásady jako v syntaxi pravidel pro skrývání prvků.attributes
— seznam atributů, které limitují výběr prvků.name
— název atributu,value
— podřetězec, který je obsažen v hodnotě atributu.pseudoName
— název pseudotřídy.pseudoArgs
— argumenty pseudotřídy typu funkce.combinator
— operátor, který funguje podobně jako podřízený kombinátor CSS: to znamená, žeselector
napravo odcombinator
bude odpovídat pouze prvku, jehož přímý původce odpovídáselector
vlevo zcombinator
.
Příklady
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.
Speciální atributy
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
This special attribute may become unsupported in the future. 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
This special attribute may become unsupported in the future. 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
This special attribute may become unsupported in the future. 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.
Např:
$$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
This special attribute may become unsupported in the future. 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.
Např:
$$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.
Pseudotřídy
:contains()
Syntax
:contains(unquoted text)
nebo
: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.
Výjimky
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.
Pravidla JavaScript
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
— omezení domény pro dané pravidlo. Stejné zásady jako v pravidlech pro skrývání prvků.skript
— libovolný kód JavaScript v jednom řetězci.
Příklady
example.org#%#window.__gaq = undefined;
spustí kódwindow.__gaq = undefined;
na všech stránkách naexample.org
a jejích subdoménách.
Výjimky
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 be used only in trusted filters.
JavaScript rules are not supported by AdGuard Content Blocker.
Pravidla skriptlet
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
rule = [domains] "#%#//scriptlet(" scriptletName arguments ")"
scriptletName
— povinný, název skriptletu z knihovny skripletů AdGuardarguments
— volitelnýný, seznam argumentůstring
(jiné typy argumentů nejsou podporovány)
Příklady
example.org#%#//scriptlet("abort-on-property-read", "alert")
This rule will be applied to example.org
and subdomains pages and will execute the abort-on-property-read
scriptlet with the alert
parameter.
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.
Důvěryhodné skriptlety
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 be used only 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.
Modifikátory pro ostatní typ pravidel
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
— sada modifikátorů popsaných níže.rule text
— pravidlo, které je třeba změnit.
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: \]
.
Modifikátor \ Produkty | Aplikace CoreLibs | AdGuard pro Chromium | AdGuard pro Firefox | AdGuard pro iOS | AdGuard pro Safari | Blokátor obsahu AdGuard |
---|---|---|---|---|---|---|
$app | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$domain | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$path | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$url | ✅ | 🧩 * | 🧩 * | ❌ | ❌ | ❌ |
- ✅ — plně podporováno
- 🧩 — může být již implementováno ve verzích nightly nebo beta, ale není ještě podporováno ve verzích pro vydání
- ❌ — nepodporováno
$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.
Příklady
[$app=org.example.app]example.com##.textad
skryjediv
s třídoutextad
naexample.com
a všech subdoménách v požadavcích odeslaných zorg.example.app
v aplikaci Android.[$app=~org.example.app1|~org.example.app2]example.com##.textad
skryjediv
s třídoutextad
naexample.com
a všech subdoménách v požadavcích odeslaných z jakékoli aplikace kroměorg.example.app1
aorg.example.app2
.[$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300')
použije skripletprevent-setInterval
pouze v prohlížeči Safari na počítači Mac.[$app=org.example.app]#@#.textad
zakáže všechna pravidla##.textad
pro všechny domény při použitíorg.example.app
.
Such rules with $app
modifier are supported by AdGuard for Windows, Mac, and 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.
Příklady
[$domain=example.com]##.textad
— skryjediv
s třídoutextad
na doméněexample.com
a všech subdoménách.[$domain=example.com|example.org]###adblock
— skryje prvek s atributemid
, který se rovnáadblock
naexample.com
,example.org
a všech subdoménách.[$domain=~example.com]##.textad
— toto pravidlo skryje prvekdiv
se třídoutextad
na všech doménách kroměexample.com
a jejích subdomén.
There are 2 ways to specify domain restrictions for non-basic rules:
- "klasický" způsob je zadat domény před masku pravidla a atributy:
example.com##.textad
; - přístup modifikátoru spočívá v určení domén pomocí modifikátoru
$domain
:[$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.
Such rules with $domain
modifier are supported by AdGuard for Windows, Mac, Android, and AdGuard Browser Extension for Chrome, Firefox, 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.
Příklady
[$path=page.html]##.textad
skryjediv
se třídoutextad
na/page.html
nebo/page.html?<query>
nebo/sub/page.html
nebo/another_page.html
[$path=/page.html]##.textad
skryjediv
se třídoutextad
na/page.html
nebo/page.html?<query>
nebo/sub/page.html
jakékoliv domény kromě/another_page.html
[$path=|/page.html]##.textad
skryjediv
se třídoutextad
na/page.html
nebo/page.html?<query>
jakékoliv domény kromě/sub/page.html
[$path=/page.html|]##.textad
skryjediv
se třídoutextad
na/page.html
nebo/sub/page.html
jakékoliv domény kromě/page.html?<query>
[$path=/page*.html]example.com##.textad
skryjediv
se třídoutextad
na/page1.html
nebo/page2.html
nebo jiné cestě shodné s/page<...>.html
doményexample.com
[$path]example.com##.textad
skryjediv
se třídoutextad
na hlavní stránce doményexample.com
[$domain=example.com,path=/page.html]##.textad
skryjediv
se třídoutextad
napage.html
doményexample.com
a všech subdoménách kroměanother_page.html
[$path=/\\/(sub1|sub2)\\/page\\.html/]##.textad
skryjediv
se třídoutextad
na/sub1/page.html
a/sub2/page.html
jakékoliv domény (vezměte prosím na vědomí, že uvozuje speciální znak)
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.
Příklady
[$url=||example.com/content/*]##div.textad
skryjediv
se třídoutextad
na adrese jakohttps://example.com/content/article.html
a dokonce ihttps://subdomain.example.com/content/article.html
.[$url=||example.org^]###adblock
skryje prvek s atributemid
, který se rovnáadblock
naexample.org
a jejích subdoménách.[$url=/\[az\]+\\.example\\.com^/]##.textad
skryje prvky třídydiv
textad
pro všechny domény odpovídající regulárnímu výrazu[a-z]+\. example\.com^
.
$url
modifier limitations
Rules with the $url
modifier are supported by AdGuard for Windows, Mac, and Android with CoreLibs v1.11 or later, and AdGuard Browser Extension with TSUrlFilter v3.0.0 or later.
Informace pro správce filtrů
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.
Direktivy preprocesoru
We provide preprocessor directives that can be used by filters maintainers to improve compatibility with different ad blockers and provide:
- zahrnutý soubor
- použití pravidel podmíněně podle typu blokátoru reklam
- zadání blokátor obsahu pro pravidla platná v 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.
Zahrnutý soubor
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.
Příklady
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
Podmínky
Filters 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.
There are two possible scenarios:
Pokud blokátor reklamy narazí na direktivu
!#if
a ne!#else
, zkompiluje kód mezi direktivami!#if
a!#endif
pouze v případě, že je zadaná podmínka pravdivá.Pokud existuje direktiva
!#else
, bude zkompilován kód mezi!#if
a!#else
, pokud je podmínka pravdivá; v opačném případě bude zkompilován kód mezi!#else
a!#endif
.
Whitespaces matter. !#if
is a valid directive, while !# if
is not.
Syntax
!#if (conditions)
rules_list
!#endif
nebo
!#if (conditions)
true_conditions_rules_list
!#else
false_conditions_rules_list
!#endif
kde:
!#if (conditions)
— začátek bloku při splnění podmínekconditions
— stejně jako v některých populárních programovacích jazycích jsou podmínky preprocesoru založeny na konstantách deklarovaných blokátory reklamy. Autoři blokátorů reklam si sami určují, jaké konstanty přesně deklarují. Přípustné hodnoty:adguard
vždy deklarováno; ukazuje správcům, že se jedná o jeden z produktů AdGuard; mělo by to stačit v 95 % případů- konstanty specifické pro daný produkt pro případy, kdy potřebujete, aby pravidlo fungovalo (nebo nefungovalo — pak je třeba před konstantou použít
!
) pouze v konkrétním produktu:adguard_app_windows
— AdGuard pro Windowsadguard_app_mac
— AdGuard pro Macadguard_app_android
— AdGuard pro Androidadguard_app_ios
— AdGuard pro iOSadguard_ext_safari
— AdGuard pro Safariadguard_ext_chromium
— Rozšíření prohlížeče AdGuard pro Chrome (a prohlížeče založené na chromium, např. nový Microsoft Edge.)adguard_ext_firefox
— Rozšíření prohlížeče AdGuard pro Firefoxadguard_ext_edge
— Rozšíření prohlížeče AdGuard pro starší Edgeadguard_ext_opera
— Rozšíření prohlížeče AdGuard pro Operuadguard_ext_android_cb
— Blokátor obsahu AdGuard pro mobilní prohlížeče Samsung a Yandexext_ublock
— speciální případ; ten je deklarován, když je verze filtru uBlock kompilována pomocí FiltersRegistrycap_html_filtering
— produkty, které podporují pravidla filtrování HTML: AdGuard pro Windows, AdGuard pro macOS a AdGuard pro Android
!#else
— začátek bloku při nesplnění podmínekrules_list
,true_conditions_rules_list
,false_conditions_rules_list
— seznamy pravidel!#endif
— konec blokování
Příklady
! 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)
! pro všechny produkty AdGuardu kromě AdGuardu pro Safari
||example.org^$third-party
domain.com##div.ad
!#else
! pouze pro AdGuard pro Safari
||subdomena.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;
- Rozšíření prohlížeče AdGuard v4.2.208;
- AdGuard v1.11.16 pro Safari.
Afinita Safari
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 — Blokování reklam, jazykově specifické filtry
- AdGuard Privacy — Soukromí
- AdGuard Social — sociální widgety, obtěžování
- AdGuard Security — Zabezpečení
- AdGuard Other — Jiné
- AdGuard Custom — Vlastní
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
kde:
!#safari_cb_affinity(content_blockers)
— počátek blokovánícontent_blockers
— seznam blokátorů obsahu oddělený čárkami. Přípustné hodnoty:general
— blokátor obsahu AdGuard Generalprivacy
— blokátor obsahu AdGuard Privacysocial
— blokátor obsahu AdGuard Socialsecurity
— blokátor obsahu AdGuard Securityother
— blokátor obsahu AdGuard Othercustom
— blokátor obsahu AdGuard Customall
— speciální klíčové slovo, které znamená, že pravidla musí být zahrnuta do všech blokátorů obsahu
rules_list
— seznam pravidel!#safari_cb_affinity
— konec blokování
Příklady
! 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
Nápovědy
"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.
Nápověda NOT_OPTIMIZED
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
kde:
- filter — identifikátor filtru
- percent — očekávané procento optimalizace
~= (počet pravidel v optimalizovaném filtru) / (počet pravidel v původním filtru) * 100
- minPercent — dolní mez hodnoty
percent
- maxPercent — horní mez hodnoty
percent
value - strict — pokud je
percent < minPercent
NEBOpercent > maxPercent
a je zapnutý přísný režim, pak by kompilace filtru měla selhat, jinak je nutné použít původní pravidla
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:
- úplná: https://filters.adtidy.org/extension/chromium/filters/2.txt
- optimalizovaná: 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^
Nápověda PLATFORM
a NOT_PLATFORM
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 pro Windows — https://filters.adtidy.org/windows/filters/2.txtmac
— AdGuard pro Mac — https://filters.adtidy.org/mac_v2/filters/2.txtandroid
— AdGuard pro Android — https://filters.adtidy.org/android/filters/2.txtios
— AdGuard pro iOS — https://filters.adtidy.org/ios/filters/2.txtext_chromium
— Rozšíření prohlížeče AdGuard pro 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
— Rozšíření prohlížeče AdGuard pro Firefox — https://filters.adtidy.org/extension/firefox/filters/2.txtext_edge
— Rozšíření prohlížeče AdGuard pro Edge — https://filters.adtidy.org/extension/edge/filters/2.txtext_opera
— Rozšíření prohlížeče AdGuard pro Operu — https://filters.adtidy.org/extension/opera/filters/2.txtext_safari
— AdGuard pro Safari — https://filters.adtidy.org/extension/safari/filters/2.txtext_android_cb
— Blokátor obsahu AdGuard — https://filters.adtidy.org/extension/android-content-blocker/filters/2.txtext_ublock
— uBlock Origin — https://filters.adtidy.org/extension/ublock/filters/2.txt
Příklady
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^
Jak ladit pravidla filtrování
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.
Záznam filtrování
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.
- V AdGuardu pro Windows jej najdete na kartě Blokátor reklam nebo prostřednictvím nabídky na hlavním panelu
- V AdGuardu pro Mac je pod Nastavení → Pokročilé → Záznam filtrování
- V AdGuardu pro Android je pod Statistiky → Nedávná aktivita. Nedávná aktivita je také přístupná z Asistenta
- V Rozšíření prohlížeče AdGuard je přístupný z karty Různé nebo kliknutím pravým tlačítkem myši na ikonu rozšíření. Pouze prohlížeče založené na platformě Chromium a Firefox zobrazují použití pravidel skrývání prvků (včetně CSS, ExtCSS) a pravidel JS a skripletů v jejich záznamech filtrování
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.
Režim ladění selektorů
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 případně parsovaného selektorutimings
— seznam uzlů DOM odpovídajících selektoruappliesCount
— celkový počet použití selektoru na stránceappliesTimings
— doba, po kterou byl selektor na stránce použit, pro každý případ, kdy byl použit (v milisekundách)meanTiming
— průměrná doba, po kterou byl selektor na stránce použitstandardDeviation
— standardní odchylkatimingsSum
— celkový čas potřebný k použití selektoru na stránce ve všech instancích
Printed only for remove pseudos:
removed
— příznak signalizující, zda byly prvky odstraněny
Printed if elements are not removed:
matchedElements
— seznam uzlů DOM odpovídajících selektorustyleApplied
— parsovaná deklarace stylu pravidla související se selektorem
Příklady
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()
.
Příklady
const selector = 'div.block:has=(.header:matches-css(after, content: Ads))';
// array of HTMLElements matched the `selector` is to be returned
ExtendedCss.query(selector);
Ladění skriptletů
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
se specifikovaným parametremreplacement
prevent-xhr
trusted-replace-fetch-response
trusted-replace-xhr-response
Legenda tabulek kompatibility
Zkratky produktů
aplikací CoreLibs
— AdGuard pro Windows, AdGuard pro Mac a AdGuard pro AndroidAdGuard pro Chromium
— Rozšíření prohlížeče AdGuard pro Chrome a další prohlížeče založené na Chromium, např. nový Microsoft Edge, OperaAdguard pro Firefox
— Rozšíření prohlížeče AdGuard pro FirefoxAdGuard pro iOS
— AdGuard pro iOS a AdGuard pro iOS Pro (pro mobilní prohlížeč Safari)AdGuard pro Safari
— AdGuard pro stolní prohlížeč SafariAdGuard Content Blocker
— Content Blocker pro mobilní prohlížeče Android: Samsung Internet a Yandex Browser
Zkratky kompatibility
- ✅ — plně podporováno
- ✅ * — podporováno, ale spolehlivost se může lišit nebo se mohou vyskytnout omezení; více informací naleznete v popisu modifikátoru
- 🧩 — může být již implementováno ve verzích nightly nebo beta, ale není ještě podporováno ve verzích pro vydání
- ⏳ — funkce, která byla implementována nebo jejíž implementace se plánuje, ale zatím není k dispozici v žádném produktu
- ❌ — nepodporováno
- 👎 — deprecated; still supported but will be removed in the future
- 🚫 — odstraněno a již nepodporováno