Přejít k hlavnímu obsahu

Jak vytvářet vlastní filtry reklam

informace

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.

informace

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​

Blocking by domain name

Toto pravidlo blokuje:

  • https://example.org/ad1.gif
  • https://subdomain.example.org/ad1.gif
  • https://ads.example.org:8000/

Toto pravidlo neblokuje:

  • https://ads.example.org.us/ad1.gif
  • https://example.com/redirect/https://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​

Blocking exact address

Toto pravidlo blokuje:

  • https://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.

Modifikátory základních pravidel

Toto pravidlo blokuje:

  • https://example.org/script.js, pokud je tento skript načten z example.com.

Toto pravidlo neblokuje:

  • https://example.org/script.js, pokud je tento skript načten z example.org.
  • https://example.org/banner.png, protože se nejedná o skript.

Odblokování adresy​

Odblokování adresy

Toto pravidlo odblokuje:

  • https://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​

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​

Cosmetic rule

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ázevSelektor CSSPopis
ID selector#bannersShoduje se se všemi prvky s atributem id rovným banners.
ID selector
Class selector.bannersShoduje se se všemi prvky s atributem class obsahujícím banners.
Class selector
Attribute selectordiv[class="banners"]Shoduje se se všemi prvky div s atributem class přesně rovným k banners.
Attribute selector
Attribute substring selectordiv[class^="advert1"]Shoduje se se všemi prvky div s atributem class začínajícím na řetězec advert1.
Attribute substring selector
Attribute substring selectordiv[class$="banners_ads"]Shoduje se se všemi prvky div s atributem class končícím na řetězec banners_ads.
Attribute substring selector
Attribute substring selectora[href^="https://example.com/"]Shoduje se se všemi odkazy načtenými z domény https://example.com/.
Attribute substring selector
Attribute selectora[href="https://example.com/"]Shoduje se se všemi odkazy exactly adresy https://example.com/.
Attribute selector

Omezení a restrikce​

Důvěryhodné filtry​

Některá pravidla lze použít pouze v důvěryhodných filtrech. Tato kategorie zahrnuje:

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ě.

SafariConverterLib​

Safari Converter se snaží co nejvíce podporovat syntaxi pravidel filtrování AdGuard, ale stále existují omezení a nedostatky, které je těžké překonat.

Základní (síťová) pravidla​

Safari Converter podporuje podstatnou podmnožinu základních pravidel a určitě podporuje nejdůležitější typy těchto pravidel.

Podporováno s omezeními​

  • Pravidla regulárních výrazů jsou omezena na podmnožinu regex podporovanou prohlížečem Safari.

  • $domain - modifikátor domén je podporován s několika omezeními:

    • Není možné míchat povolené a zakázané domény (například $domain=example.org|~sub.example.org). Dejte prosím pozitivní hodnocení žádosti o funkci pro WebKit, aby toto omezení zrušil.
    • "Libovolná TLD" (tj. domain.*) není plně podporována. V současné implementaci konvertor pouze nahrazuje .* 100 nejoblíbenějšími TLD. Tato implementace bude v budoucnu vylepšena.
    • Použití regulárních výrazů v $domain není podporováno, ale i to bude v budoucnu vylepšeno.

  • $denyallow - tento modifikátor je podporován převodem pravidla $denyallow na sadu pravidel (jedno pravidlo blokování + několik pravidel pro odblokování).

    Vzhledem k tomuto omezení $denyallow je povoleno pouze v případě, že pravidlo má také modifikátor $domain.

    • Generické pravidlo *$denyallow=x.com,image,domain=a.com bude převedeno na:
    *$image,domain=a.com
    @@||x.com$image,domain=a.com
    • Pravidlo /banner.png$image,denyallow=test1.com|test2.com,domain=example.org bude převedeno na:
    /banner.png$image,domain=example.org
    @@||test1.com/banner.png$image,domain=example.org
    @@||test1.com/*/banner.png$image,domain=example.org
    @@||test2.com/banner.png$image,domain=example.org
    @@||test2.com/*/banner.png$image,domain=example.org
    • Pravidlo bez $domainnení podporováno: $denyallow=a.com|b.com.

  • $popup - jsou podporována pravidla vyskakovacích oken, ale jsou v podstatě stejná jako pravidla pro $document-pravidla blokování a nepokusí se kartu zavřít.

  • Pravidla výjimek(@@) zakazují kosmetické filtrování odpovídajících domén.

    Pravidla výjimek v Safari se spoléhají na typ pravidla ignore-previous-rules, takže aby to fungovalo, musíme pravidla seřadit v určitém pořadí. Pravidla výjimek bez modifikátorů jsou umístěna na konci seznamu a proto znemožňují nejen blokování URL, ale i kosmetická pravidla.

    Toto omezení může být zrušeno, pokud bude implementována položka #70.

  • $urlblock, $genericblock je v podstatě stejné jako $document, tj. zakáže všechny druhy filtrování webových stránek.

    Tato omezení mohou být zrušena, až budou zavedeny položky #69 a #71.

  • $content nemá v případě Safari smysl, protože pravidla filtrování HTML nejsou podporována, takže je zde pouze pro účely kompatibility. Pravidla s $content jsou omezena na typ zdroje document.

  • $specifichide je implementováno prohledáním existujících pravidel pro skrývání prvků a odstraněním cílové domény z jejich řady if-domain.

    • $specifichide pravidlo MUSÍ být zaměřeno na doménu, tj. musí vypadat takto: ||example.org^$specifichide. Pravidla s konkrétnějšími vzory budou vyřazena, tj. ||example.org/path$specifichide nebude podporováno.
    • $specifichide se vztahuje pouze na pravidla, která jsou zaměřena na stejnou doménu jako samotné pravidlo, subdomény jsou ignorovány. Tj. pravidlo @@||example.org^$specifichide zakáže example.org##.banner, ale bude ignorovat sub.example.org##.banner. Toto omezení může být zrušeno, pokud bude implementována položka #72.

  • Modifikátory urlblock, genericblock, generichide, elemhide, specifichide a jsinject lze v pravidle použít pouze jako jeden modifikátor. Toto omezení může být v budoucnu zrušeno: #73.

  • $websocket (plně podporováno od Safari 15).

  • $ping (plně podporováno od Safari 14).

Nepodporováno​
  • $app
  • $header
  • $method
  • $strict-first-party (bude podporováno v budoucnu: #64)
  • $strict-third-party (bude podporováno v budoucnu: #65)
  • $to (bude podporováno v budoucnu: #60)
  • $extension
  • $stealth
  • $cookie (bude částečně podporováno v budoucnu: #54)
  • $csp
  • $hls
  • $inline-script
  • $inline-font
  • $jsonprune
  • $xmlprune
  • $network
  • $permissions
  • $redirect
  • $redirect-rule
  • $referrerpolicy
  • $removeheader
  • $removeparam
  • $replace
  • $urltransform

Kosmetická pravidla​

Safari Converter podporuje většinu kosmetických pravidel ačkoli jsou nativně podporována pouze pravidla skrývání prvků se základními selektory CSS prostřednictvím blokování obsahu v Safari, vše ostatní je třeba interpretovat dalším rozšířením.

Omezení kosmetických pravidel​

Pravidla script/scriptlet​

Safari Converter plně podporuje pravidla script a pravidla scriplet. Tato pravidla však lze vykládat pouze pomocí samostatného rozšíření.

:::varování

Pro pravidla scriplet je velmi důležité spustit je co nejdříve po načtení stránky. Důvodem je to, že je důležité, aby se spustil dříve než skripty stránky. V prohlížeči Safari bohužel vždy dochází k mírnému zpoždění, které může snížit kvalitu blokování.

:::

HTML pravidla filtrování​

Pravidla filtrování HTML nejsou, a v budoucnu nebudou podporována. Safari bohužel neposkytuje potřebné technické možnosti pro jejich implementaci.

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.

Dílčí požadavky

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.

Stav odpovědi

Prohlížeč rozpozná zablokovaný požadavek jako dokončený s chybou.

Délka pravidla

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á https://*., 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ř. pravidlo swf| odpovídá https://example.com/annoyingflash.swf, ale neodpovídá https://example.com/swf/index.html. |https://example.org odpovídá https://example.org, ale ne https://domain.com?url=https://example.org.
poznámka

|, ||, ^ lze použít pouze u pravidel se vzorem URL. Např. ||example.com##.advert je nesprávný a bude blokátorem ignorován.

Vizuální znázorně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.

Výkon

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+/.

Kompatibilita

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.*.

Kompatibilita

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 typu https://example.com/ads/banner.jpg a dokonce i https://subdomain.example.com/ads/otherbanner.jpg.

  • ||example.org^$third-party — toto pravidlo blokuje požadavky třetích stran na example.org a jejím subdoménám.

  • @@||example.com$document — obecné pravidlo výjimky. Zcela vypne filtrování pro example.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​

poznámka

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 \ ProduktyAplikace CoreLibsAdGuard pro ChromiumAdGuard pro Chrome MV3AdGuard pro FirefoxAdGuard pro iOSAdGuard Mini pro MacBlokátor obsahu AdGuard
$app✅❌❌❌❌❌❌
$denyallow✅✅✅✅❌✅❌
$domain✅✅✅ *[1]✅✅ *[1]✅ *[1]✅
$header✅✅ *[2]✅ *[2]✅ *[2]❌❌❌
$important✅✅✅✅✅✅❌
$match-case✅✅✅✅✅✅✅
$method✅✅✅✅✅ *[2]✅ *[2]❌
$popup✅ *[3]✅✅ *[3]✅✅ *[3]✅ *[3]❌
$strict-first-party✅❌❌❌❌❌❌
$strict-third-party✅❌❌❌❌❌❌
$third-party✅✅✅✅✅✅✅
$to✅✅✅✅❌❌❌
poznámka
  • ✅ — 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

$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í.

Syntaxe

Modifikátor je seznam jednoho nebo více výrazů, z nichž každý je porovnáván s aplikací určitým způsobem v závislosti na svém typu. Tyto výrazy jsou odděleny symbolem |.

applications = ["~"] entry_0 ["|" ["~"] entry_1 ["|" ["~"]entry_2 ["|" ... ["|" ["~"]entry_N]]]]
entry_i = ( regular_app / wildcard_app / regexp )
  • regular_app — regulární název aplikace (example.app). Odpovídá zadané aplikaci a je přiřazen lexikograficky.
  • wildcard_app — název aplikace končící zástupným znakem *, např. org.example.* nebo com.ad*. Odpovídá všem aplikacím, jejichž názvy začínají zadanou předponou. Porovnání se provádí lexikograficky.
  • regexp — regulární výraz, který začíná a končí znakem /. Funguje stejně jako v základních pravidlech URL, ale znaky /, $, , a | musí být uvozeny pomocí \.

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 aplikace org.example.app.
  • ||baddomain.com^$app=org.example.app1|org.example.app2 — stejné pravidlo, ale funguje jak pro org.example.app1, tak i pro org.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 a org.example.app2.

Zástupné znaky můžete použít v modifikátoru $app:

  • ||baddomain.com^$app=org.example.* — použije se pro všechny aplikace, jejichž názvy balíčků začínají na org.example.

V modifikátoru $app můžete použít regulární výrazy, které uzavřete do lomítek /.../. To umožňuje flexibilnější párování — například cílení na skupinu aplikací od stejného vydavatele nebo párování složitých vzorů.

  • ||baddomain.com^$app=/org\.example\.[a-z0-9_]+/ — platí pro všechny aplikace, jejichž název balíčku začíná org.example (např. org.example.app1, org.example.utility atd.).
  • ||baddomain.com^$app=/^org\.example\.app\$\|^org\.example\.[ab].*/ — platí pro org.example.app a pro všechny aplikace, jejichž balíček začíná org.example.a nebo org.example.b.

Modifikátor $app podporuje kombinování všech tří typů záznamů — prostých názvů, zástupných znaků a regulárních výrazů — v rámci stejného pravidla, ale neumožňuje kombinovat negované a nenegované výrazy dohromady.

  • ||example.com^$app=org.example.app|org.example.*|/org\.example\.[a-z]+/ — platí pro org.example.app, všechny odpovídající aplikace org.example.* a org.example.[a-z]+.
Omezení
  • Aplikace v hodnotě modifikátoru nemohou obsahovat zástupný znak uvnitř řetězce, např. $app=com.*.music. Použijte místo toho regulární výraz: $app=/com\..*\.music/.
  • Nelze kombinovat negované (~) a nenegované výrazy ve stejném modifikátoru $app — bylo by to nejednoznačné.
Kompatibilita
  • Pouze AdGuard pro Windows, Mac a Android jsou technicky schopné používat pravidla s modifikátorem $app.
  • V systému Windows se v názvu procesu nerozlišují velká a malá písmena, počínaje AdGuard pro Windows s CoreLibs v1.12 nebo novější.
  • Podpora regulárních výrazů a kombinování různých typů záznamů (prosté názvy, zástupné znaky a regulární výrazy) v modifikátoru $app je k dispozici od verze CoreLibs v1.19 nebo novější.

$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. Chcete-li do jednoho pravidla přidat více domén, použijte jako oddělovací znak |.

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
Omezení
  • Vzor shody pravidla se nemůže zaměřit na žádné konkrétní domény, např. nemůže začínat ||.
  • Domény v hodnotě modifikátoru nemohou být negovány, např. $denyallow=~x.com, nebo mít zástupný znak TLD, např. $denyallow=x.*, nebo být regulárním výrazem, např. ;$denyallow=/\.(com\|org)/.
  • $denyallow nelze použít společně s $to. Lze ji vyjádřit pomocí invertovaného $to: $denyallow=a.com|b.com, což je je ekvivalent k $to=~a.com|~b.com.

Pravidla, která tato omezení porušují, jsou považována za neplatná.

Kompatibilita

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ř. pro example.* je to co.uk v example.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 URL, ale znaky /, $, , a | musí být uvozeny pomocí \.
informace

Pravidla s modifikátorem $domain jako regular_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ény example.org nebo jejích subdomén.
  • ||baddomain.com^$domain=example.org|example.com — stejné pravidlo, ale funguje jak pro example.org, tak i pro example.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ény example.org nebo jejích subdomén.
  • ||baddomain.com^$domain=example.org|example.com — stejné pravidlo, ale funguje jak pro example.org, tak i pro example.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é z example.org a jích subdomén, kromě subdomény foo.example.org.
  • ||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/ blokuje požadavky odeslané z example.org a example.com a všech jejích subdomén.
  • ||baddomain.com^$domain=~a.com|~b.*|~/(^\|.+\.)c\.(com\|org)\$/ blokuje požadavky odeslané z a.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 dochází, když pravidlo obsahuje jeden z následujících modifikátorů: $cookie, $csp, $permissions, $removeparam.

Tyto modifikátory nebudou použity, pokud odkazující doména odpovídá pravidlu s $domain, které výslovně vylučuje odkazující doménu, i když cílová doména také odpovídá pravidlu.

Příklady

  • *$cookie,domain=example.org|example.com zablokuje soubory cookie pro všechny požadavky do a z domény example.org a example.com.
  • *$document,domain=example.org|example.com zablokuje pouze požadavky z example.org a example.com, ale ne požadavky směřující na tyto domény.

V následujících příkladech se předpokládá, že požadavky jsou odesílány z adresy https://example.org/page (odkazující adresa), cílová adresa URL je https://targetdomain.com/page.

  • page$domain=example.org bude přiřazena, protože odpovídá doméně odkazu.
  • page$domain=targetdomain.com nebude odpovídat, protože neodpovídá doméně odkazujícího webu.
  • ||*page$domain=targetdomain.com,cookie bude odpovídat, protože pravidlo obsahuje modifikátor $cookie, i když vzor ||*page může odpovídat konkrétním doménám.
  • page$domain=targetdomain.com|~example.org,cookie nebude přiřazena, protože doména odkazu je výslovně vyloučena.
omezení modifikátoru $domain​
Omezení

V AdGuardu pro Chrome MV3 nejsou podporovány domény s regexp a any_tld_domain a modifikátory $removeparam.

AdGuard pro iOS a AdGuard pro Safari podporují modifikátor $domain, ale má některá omezení. Pro více informací navštivte sekci SafariConverterLib.

Pravidla s modifikátorem regexp v $domain nejsou podporována AdGuardem pro iOS a Safari.

Kompatibilita

Pravidla s regulárními výrazy v modifikátoru $domain jsou podporována AdGuardem pro Windows, AdGuardem pro Mac, AdGuardem pro Android a AdGuardem pro Linux s CoreLibs v1.11 nebo novějším a rozšířením prohlížeče AdGuard s TSUrlFilter v3.0.0 nebo novějším.

V AdGuardu pro Windows, Mac a Android s CoreLibs v1.12 nebo novějším může být modifikátor $domain alternativně zapsán jako $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. Je přizpůsoben případ od případu.
  • 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čku Set-Cookie s hodnotou odpovídající foo.
  • ||example.com^$header=set-cookie blokuje požadavky, jejichž odpovědi mají hlavičku Set-Cookie s libovolnou hodnotou.
  • @@||example.com^$header=set-cookie:/foo\, bar\$/ odblokuje požadavky, jejichž odpovědi mají hlavičku Set-Cookie s hodnotou odpovídající regulárnímu výrazu foo, bar$.
  • @@||example.com^$header=set-cookie odblokuje požadavky, jejichž odpovědi mají hlavičku Set-Cookie s libovolnou hodnotou.
omezení modifikátoru $header​
Omezení

  1. Modifikátor $header lze porovnat pouze v případě, že jsou přijata záhlaví. Pokud je tedy požadavek zablokován nebo přesměrován v dřívější fázi, nelze modifikátor použít.

  2. V Rozšíření prohlížeče AdGuard je modifikátor $header kompatibilní poze s $csp, $removeheader (pouze hlavičky odpovědí), $important, $badfilter, $domain, $third-party, $match-case s content-type modifiers jako $script a $stylesheet. Pravidla s jinými modifikátory jsou považována za neplatná a budou vyřazena.

  3. V Rozšíření prohlížeče AdGuard MV3 nejsou podporovány regulární výrazy v hodnotách modifikátoru $header.

Kompatibilita

Pravidla s modifikátorem $header jsou podporována AdGuardem pro Windows, AdGuardem pro Mac, AdGuardem pro Android a AdGuardem pro Linux s CoreLibs v1.11 nebo novějším a rozšířením prohlížeče AdGuard s TSUrlFilter v3.0.0 nebo novějším a rozšířením prohlížeče Adguard MV3 v5.3 a novějším.

$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 zablokuje https://example.com/BannerAd.gif, ale ne https://example.com/bannerad.gif.
Kompatibilita

Pravidla s $match-case jsou podporována aplikací AdGuard pro iOS a AdGuard pro Safari s SafariConverterLib v2.0.43 nebo novějším.

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.
Omezení

  1. V aplikacích AdGuard pro iOS a AdGuard Mini pro Mac modifikátor $method nepodporuje negaci. Proto nejsou podporována pravidla jako $method=~get.

  2. Pravidla s kombinací negovaných a nenegovaných hodnot jsou považována za neplatná. Takže např. pravidlo ||evil.com^$method=get|~head bude ignorováno.

Kompatibilita

Pravidla s modifikátorem $method jsou podporována AdGuardem pro Windows, Mac, Android a Linux s CoreLibs v1.12 nebo novější a Rozšířením prohlížeče AdGuard pro Chrome, Firefox a Edge s filtrem TSUrlFilter v2.1.1 nebo novějším.

V aplikacích AdGuard pro iOS (verze 4.5.15 nebo novější) a AdGuard Mini pro Mac (verze 2.1 nebo novější) je modifikátor $method podporován s omezeními.

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 na https://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.
Omezení
  1. Modifikátor $popup funguje nejlépe v rozšíření prohlížeče AdGuard pro prohlížeče založené na Chromiu a Firefox.
  2. V pravidlech AdGuard pro Chrome MV3 s modifikátorem $popup by nefungovaly, proto jsme zakázali jejich převod na deklarativní pravidla. Pokusíme se je použít pouze v našem enginu TSUrlFilter a zavírat nové karty programově.
  3. V AdGuardu pro Safari a AdGuardu pro iOS, pravidla $popup stránku jednoduše a okamžitě zablokují.
  4. V AdGuardu pro Windows, Mac, Android a Linux nemusí modifikátor $popup v některých případech detekovat vyskakovací okno a nebude zablokováno. Modifikátor $popup použije typ obsahu document se speciálním příznakem, který je předán blokovací stránce. 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 jej kombinovat s dalšími modifikátory typu požadavku, například $third-party, $strict-third-party, $strict-first-party a $important.
Kompatibilita

Pravidla s modifikátorem $popup nejsou Blokátorem obsahu AdGuard podporována.

$strict-first-party​

Funguje stejně jako modifikátor $~third-party, ale zachází s požadavkem jako s vlastním, pokud má odkazovač a původ naprosto stejný název hostitele.

Požadavky bez odkazovače jsou také považovány za vlastní požadavky a na tyto požadavky se vztahují pravidla s modifikátorem $strict-first-party.

Příklady

  • domain.com$strict-first-party' – toto pravidlo platí pouze pro domena.com. Např. požadavek z domain.com na https://domain.com/icon.ico je požadavek vlastní. Požadavek z sub.domain.com na https://domain.com/icon.ico je považován za požadavek třetí strany (na rozdíl od modifikátoru $~third-party).
poznámka

Místo plného názvu modifikátoru můžete použít kratší název (alias): $strict1p.

Kompatibilita

Pravidla s modifikátorem $strict-first-party jsou podporována AdGuardem pro Windows, Mac, Android a Linux s CoreLibs v1.16 nebo novější.

Požadavky bez odkazovače jsou porovnávány podle pravidel s $strict-first-party v AdGuardu pro Windows, AdGuardu pro Mac a AdGuardu pro Android s CoreLibs v1.18 nebo novější.

$strict-third-party​

Funguje stejně jako modifikátor $third-party, ale zpracovává požadavky z domény na její subdomény a naopak jako žádosti třetí strany.

Příklady

  • ||domain.com^$strict-thirdparty — toto pravidlo bude použito na všechny domény, kromě domain.com. Příklad požadavku třetí strany: https://sub.domain.com/banner.jpg (na rozdíl od modifikátoru $third-party).

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

Místo plného názvu modifikátoru můžete použít kratší název (alias): $strict3p.

:::

Kompatibilita

Pravidla s modifikátorem $strict-third-party jsou podporována AdGuardem pro Windows, Mac a Android s CoreLibs v1.16 nebo novější.

$third-party​

Omezení požadavků třetích stran a vlastních požadavků. Požadavek třetí strany je požadavek z externí domény. Např. požadavek na example.org z domain.com je požadavek třetí strany.

poznámka

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:

  1. Její odkazující doména není subdoménou cílové domény nebo naopak. Např. požadavek na subdomain.example.org z example.org není požadavek třetí strany
  2. Její záhlaví Sec-Fetch-Site je nastaveno na cross-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. Pravidlo se nikdy neuplatní, pokud neexistuje žádný odkazovač. Příklad požadavku třetí strany: https://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 nebo by neměly mít vůbec žádný odkazovač.

$~third-party:

  • ||domain.com$~third-party — toto pravidlo se vztahuje výhradně na domain.com. Příklad požadavku která není podán třetí stranou: https://sub.domain.com/icon.ico.

Požadavky bez odkazovače jsou rovněž považovány za požadavky, které nejsou požadavky třetích stran, a jsou na ně aplikována pravidla s modifikátorem $~third-party.

poznámka

Místo plného názvu modifikátoru můžete použít kratší název (alias): $3p.

Kompatibilita

Požadavky bez odkazovače jsou porovnávány podle pravidel s $~third-party v AdGuardu pro Windows, AdGuardu pro Mac a AdGuardu pro Android s CoreLibs v1.18 nebo novější.

$to​

$to omezuje rozsah pravidla na požadavky na zadané domény a jejich subdomény. Chcete-li do jednoho pravidla přidat více domén, použijte jako oddělovací znak |.

Příklady

  • /ads$to=evil.com|evil.org zablokuje jakýkoliv požadavek na evil.com nebo evil.org a jejich subdomény s cestou, která odpovídá /ads.
  • /ads$to=~not.evil.com|evil.com zablokuje jakýkoliv požadavek na evil.com a její subdomény s cestou, která odpovídá /ads, kromě požadavků na not.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ů na good.com nebo good.org a jejich subdomény.
Omezení

$denyallow nelze použít společně s $to. Lze ji vyjádřit pomocí invertovaného $to: $denyallow=a.com|b.com, což je je ekvivalent k $to=~a.com|~b.com.

Kompatibilita

Pravidla s modifikátorem $to jsou podporována AdGuardem pro Windows, AdGuardem pro Mac, AdGuardem pro Android a AdGuardem pro Linux s CoreLibs v1.12 nebo novějším a rozšířením prohlížeče AdGuard s TSUrlFilter v2.1.3 nebo novějším.

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.

Kompatibilita

V tom, jak AdGuard určuje typ obsahu na různých platformách, existuje 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 z example.org.
  • ||example.org^$script,stylesheet — odpovídá všem skriptům a stylům z example.org.
  • ||example.org^$~image,~script,~stylesheet — odpovídá všem požadavkům na example.org kromě obrázků, skriptů a stylů.
Modifikátor \ ProduktyAplikace CoreLibsAdGuard pro ChromiumAdGuard pro Chrome MV3AdGuard pro FirefoxAdGuard pro iOSAdGuard pro SafariBlokátor obsahu AdGuard
$document✅✅✅✅✅✅❌
$font✅✅✅✅✅✅✅
$image✅✅✅✅✅✅✅
$media✅✅✅✅✅✅✅
$object✅✅✅✅❌❌✅
$other✅✅✅✅✅✅❌
$ping✅ *[1]✅✅✅❌❌✅
$script✅✅✅✅✅✅✅
$stylesheet✅✅✅✅✅✅✅
$subdocument✅ *[2]✅✅✅✅✅❌
$websocket✅✅✅✅✅ *[3]✅ *[3]❌
$xmlhttprequest✅✅✅✅✅✅✅
$webrtc 🚫❌❌❌❌❌❌❌
$object-subrequest 🚫❌❌❌❌❌❌❌
poznámka
  • ✅ — 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 na example.com a všech subdoménách.

  • ||example.com^$document zablokuje požadavek na dokument HTML na example.com pomocí blokační stránky.

  • ||example.com^$document,redirect=noopframe přesměruje požadavek na HTML dokument na example.com na prázdný HTML dokument.

  • ||example.com^$document,removeparam=test odebere parametr dotazu test z požadavku dokumentu HTML na example.com.

  • ||example.com^$document,replace=/test1/test2/ nahradí test1 za test2 v požadavku na dokument HTML na example.com.

poznámka

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.

Kompatibilita

Pravidla s modifikátorem $object nejsou podporována AdGuardem pro iOS a Safari.

$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.

omezení modifikátoru $ping​
Omezení

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.

Kompatibilita

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.

poznámka

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 a iframe) na example.com a všechny její subdomény kdekoli.
  • ||example.com^$subdocument,domain=domain.com blokuje integrované požadavky (frame и iframe) na example.com (a její subdomény) z domain.com a všech jejích subdomén.
poznámka

Místo plného názvu modifikátoru můžete použít kratší název (alias): $frame.

omezení modifikátoru $subdocument​
Omezení

V AdGuardu pro Windows, Mac a Android jsou subdokumenty detekovány záhlavím Sec-Fetch-Dest, pokud je přítomno. V opačném případě mohou být některé hlavní stránky považovány za dílčí dokumenty.

Kompatibilita

Pravidla s modifikátorem $subdocument nejsou Blokátorem obsahu AdGuard podporována.

$websocket​

Pravidlo se vztahuje pouze na připojení WebSocket.

omezení modifikátoru $websocket​
Omezení

AdGuard pro Safari a AdGuard pro iOS je podporován na zařízeních se systémem macOS Monterey (verze 12), respektive iOS 16 a vyšší.

Kompatibilita

Modifikátor $websocket je podporován ve všech produktech AdGuardu kromě Blokátoru obsahu AdGuard.

$xmlhttprequest​

Pravidlo se vztahuje pouze na požadavky ajax (požadavky odeslané prostřednictvím objektu JavaScript XMLHttpRequest).

poznámka

Místo plného názvu modifikátoru můžete použít kratší název (alias): $xhr.

Kompatibilita

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)​

Upozornění na odstranění

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)​

Upozornění na odstranění

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 na example.com z example.org.
  • @@*$webrtc,domain=example.org zakáže RTC wrapper pro example.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ů.

Vizuální znázornění

Doporučujeme také seznámit se s přehledem filtrů Adblock Plus, abyste lépe pochopili, jak pravidla výjimek vytvářet.

Modifikátor \ ProduktyAplikace CoreLibsAdGuard pro ChromiumAdGuard pro Chrome MV3AdGuard pro FirefoxAdGuard pro iOSAdGuard pro SafariBlokátor obsahu AdGuard
$content✅❌❌✅❌❌❌
$elemhide✅✅✅✅✅✅✅
$extension✅❌❌❌❌❌❌
$jsinject✅✅✅ *[1]✅✅✅❌
$stealth✅✅❌✅❌❌❌
$urlblock✅✅❌✅✅ *[2]✅ *[2]❌
$genericblock✅✅✅✅✅ *[3]✅ *[3]❌
$generichide✅✅✅✅✅✅✅
$specifichide✅✅✅✅❌❌❌

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

  • ✅ — 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

:::

informace

Ve výchozím nastavení, bez zadání dalších modifikátorů typu obsahu, jsou modifikátory pravidel výjimek nadřazeny ostatním základním pravidlům pouze pro požadavky na dokument hlavního rámce (viz $document pro více informací o dokumentu hlavního rámve).

Např:

  • Webová stránka example.com obsahuje iframe odkazující na example1.com.
  • Použije se pravidlo #%#//console.log('test').

V tomto případě se log v konzole zobrazí dvakrát: jednou pro hlavní dokument rámce a jednou pro iframe.

Pokud přidáte pravidlo @@|||example.com^$jsinject, log se pro iframe zobrazí pouze jednou.

$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ách example.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 na example.com a všech subdoménách.
poznámka

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"
poznámka

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ý skript AdGuard asistent na example.com.
  • @@||example.com^$extension=MyUserscript zakáže uživatelský skript MyUserscript na example.com.
  • @@||example.com^$extension='AdGuard Assistant'|'AdGuard Popup Blocker' zakáže uživatelské skripty AdGuard asistent a Blokátor vyskakovacích okenAdGuard na example.com.
  • @@||example.com^$extension=~"AdGuard Assistant" zakáže všechny uživatelské skripty na example.com, kromě AdGuard asistenta.
  • @@||example.com^$extension=~"AdGuard Assistant"|~"AdGuard Popup Blocker" zakáže všechny uživatelské skripty na example.com, kromě AdGuard asistenta a Blokátor vyskakovacích oken AdGuard.
  • @@||example.com^$extension žádné uživatelské skripty nebudou fungovat na example.com.
  • @@||example.com^$extension="AdGuard \"Assistant\"" zakáže uživatelský skript AdGuard "Asistant" na example.com.
Kompatibilita
  • Pouze AdGuard pro Windows, Mac a Android jsou technicky schopné používat pravidla s modifikátorem $extension.
  • Pravidla s modifikátorem $extension s konkrétním názvem uživatelského skriptu jsou podporována AdGuardem pro Windows, AdGuardem pro Mac, AdGuardem pro Android a AdGuardem pro Linux s CoreLibs v1.13 nebo novější.

$jsinject​

Zakazuje přidávání JavaScript 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 na example.com a všech subdoménách.
omezení modifikátoru $jsinject​
Omezení

Pravidla s modifikátorem $jsinject nelze v AdGuard for Chrome MV3 převést na DNR. Používáme je pouze v enginu TSUrlFilter, abychom zakázali některá kosmetická pravidla.

Kompatibilita

Modifikátor $jsinject není podporován AdGuardem pro Chrome MV3 (zatím) a Blokátorem obsahu AdGuard.

$stealth​

Zakáže modul Ochrana před sledováním (dříve Režim utajení) pro všechny odpovídající stránky a požadavky.

Syntaxe

$stealth [= opt1 [| opt2 [| opt3 [...]]]]

opt(i) znamená určité možnosti Ochrany před sledováním deaktivované modifikátorem. Modifikátor může obsahovat libovolný počet specifických možností (viz níže) nebo žádnou. V druhém případě modifikátor vypne všechny funkce Ochrany před sledováním.

Seznam dostupných možností modifikátoru:

Příklady

  • @@||example.com^$stealth zakáže Ochranu před sledováním pro požadavky example.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 Ochranu před sledováním pouze pro požadavky skriptů na domain.com (a subdoménách) na example.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 pro example.com.
poznámka

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 Ochrany před sledováním, musíte uvést všechny tři modifikátory: @@||example.org^$stealth,removeparam,cookie.

Omezení
  • 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.
  • Rozšíření prohlížeče AdGuard podporuje pouze možnosti searchqueries, donottrack, referrer, xclientdata, 1p-cookie a 3p-cookie.
Kompatibilita
  • Ochrana před sledováním (dříve Režim utajení) je k dispozici v AdGuardu pro Windows, AdGuardu pro macOS, AdGuardu pro Android a Rozšíření prohlížeče AdGuard pro Firefox a prohlížeče založené na Chromium, kromě AdGuardu pro Chrome Manifest MV3. Všechny ostatní produkty budou ignorovat pravidla s modifikátorem $stealth.
  • Pravidla s modifikátorem $stealth jsou podporována AdGuardem pro Windows, AdGuardem pro Mac, AdGuardem pro Android a AdGuardem pro Linux s CoreLibs v1.10 nebo novějším a Rozšířením prohlížeče AdGuard s TSUrlFilter v3.0.0 nebo novějším.
  • V rozšíření prohlížeče AdGuard se příkaz Block WebRTC používá globálně a nelze jej ovládat pro jednotlivé stránky. Pravidla výjimek jako $stealth=webrtc nemají žádný účinek.

$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é z example.com a ze všech subdomén.
omezení modifikátoru $urlblock​
Omezení

V AdGuardu pro iOS a AdGuardu pro Safari fungují pravidla $urlblock jako $document exclusion — odblokování všeho.

Kompatibilita

Pravidla s modifikátorem $urlblock nejsou podporována Blokátorem obsahu AdGuard, AdGuardem pro Chrome MV3.

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 na example.com a všech subdoménách.
omezení modifikátoru $genericblock​
Omezení

V AdGuardu pro iOS a AdGuardu pro Safari fungují pravidla $genericblock jako $document exclusion — odblokování všeho.

Kompatibilita

Pravidla s modifikátorem $genericblock nejsou podporována Blokátorem obsahu AdGuard, AdGuardem pro Chrome MV3.

$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 na example.com a jejích subdoménách.
poznámka

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áže example.org##.banner, ale ne ##.banner.
poznámka

Místo plného názvu modifikátoru můžete použít kratší název (alias): $shide.

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

Všechna kosmetická pravidla — nejen ta specifická — lze zakázat pomocí modifikátoru $elemhide.

:::

Kompatibilita

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 \ ProduktyAplikace CoreLibsAdGuard pro ChromiumAdGuard pro Chrome MV3AdGuard pro FirefoxAdGuard pro iOSAdGuard pro SafariBlokátor obsahu AdGuard
$all✅✅✅ *[1]✅✅✅❌
$badfilter✅✅✅ *[2]✅✅✅❌
$cookie✅✅✅ *[3]✅❌❌❌
$csp✅✅✅✅❌❌❌
$hls✅❌❌❌❌❌❌
$inline-font✅✅✅✅❌❌❌
$inline-script✅✅✅✅❌❌❌
$jsonprune✅❌❌❌❌❌❌
$xmlprune✅❌❌❌❌❌❌
$network✅❌❌❌❌❌❌
$permissions✅ *[4]✅✅✅ *[4]❌❌❌
$redirect✅✅✅ *[5]✅❌❌❌
$redirect-rule✅✅❌✅❌❌❌
$referrerpolicy✅❌❌❌❌❌❌
$removeheader✅✅ *[7]✅ *[7]✅ *[7]❌❌❌
$removeparam✅✅✅ *[6]✅❌❌❌
$replace✅❌❌✅❌❌❌
$urltransform✅❌❌❌❌❌❌
$reason✅✅✅✅✅✅❌
noop✅✅✅✅✅✅❌
$empty 👎✅✅✅✅❌❌❌
$mp4 👎✅✅✅✅❌❌❌
poznámka
  • ✅ — 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
  • 👎 — zastaralé; stále podporovano, ale v budoucnu bude odstraněno

$all​

$all modifikátor je složen ze všech modifikátorů typů obsahu a $popup. Např. pravidlo ||example.org^$all se převádí na pravidlo:

||example.org^$document,subdocument,font,image,media,object,other,ping,script,stylesheet,websocket,xmlhttprequest,popup
Omezení

Tento modifikátor nelze použít jako výjimku se znakem @@.

omezení modifikátoru $all​
Omezení

Vzhledem k tomu, že modifikátor $popup je součástí $all, modifikátor $all není podporován AdGuardem pro Chrome MV3 kcůli $popup omezením modifikátoru.

Kompatibilita

Pravidla s modifikátorem $all nejsou Blokátorem obsahu AdGuard podporována.

$badfilter​

Pravidla s modifikátorem $badfilter vypnou ostatní základní pravidla, na která se vztahují. To znamená, že text vypnutého pravidla by měl odpovídat textu pravidla $badfilter (bez modifikátoru $badfilter).

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

Pravidla s modifikátorem $badfilter mohou zakázat další základní pravidla pro konkrétní domény, pokud splňují následující podmínky:

  1. Pravidlo má modifikátor $domain
  2. Pravidlo nemá hodnotu modifikátoru negované domény ~ v $domain

V takovém případě pravidlo $badfilter zakáže odpovídající pravidlo pro domény uvedené v pravidlech $badfilter i v základních pravidlech. Upozorňujeme, že logika zástupných znaků TLD funguje i zde.

Příklady

  • /some$domain=example.com|example.org|example.io je zakázána pro example.com pomocí /some$domain=example.com,badfilter
  • /some$domain=example.com|example.org|example.io ije zakázána pro example.com a example.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 pro example.com a example.org pomocí /some$domain=example.com|example.org,badfilter
  • /some$domain=example.com|example.org|example.io NENÍ zakázána pro example.com pomocí /some$domain=example.com|~example.org,badfilter, protože hodnota modifikátoru $domain obsahuje negovanou doménu
omezení modifikátoru $badfilter​
Omezení

V AdGuardu pro Chrome MV3 se pravidlo s modifikátorem $badfilter použije v DNR pouze v případě, že úplně zruší zdrojové pravidlo. Nemůžeme ho vypočítat, pokud je zrušeno pouze částečně. Příklady.

Kompatibilita

Pravidla s modifikátorem $badfilter nejsou Blokátorem obsahu AdGuard podporována.

Modifikátor $cookie zcela mění chování pravidla. Namísto blokování požadavku, tento modifikátor potlačí AdGuard nebo změní záhlaví Cookie a Set-Cookie.

Vícenásobná pravidla odpovídajících jednomu požadavku

V případě, že jednomu požadavku odpovídá více pravidel $cookie, použijeme každé z nich.

Syntaxe

$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 Same-Site, která se má použít na cookies.

Např.

||example.org^$cookie=NAME;maxAge=3600;sameSite=lax

pokaždé, když AdGuard narazí na cookie s názvem NAME v požadavku na example.org, provede následující kroky:

  • Nastaví datum vypršení platnosti na aktuální čas plus 3600 sekund
  • Přiměje cookie použít "laxní" strategii Same-Site.

Uvození speciálních znaků

Pokud je pro porovnání použit regulární výraz name, musí být dva znaky uvozeny: čárka , a znak dolaru $. Každý z nich označte zpětným lomítkem \. Např. uvozená čárka vypadá takto: \,.

Příklady

  • ||example.org^$cookie blokuje všechny soubory cookie nastavené doménou example.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

Existují dva způsoby, jak deaktivovat pravidla $cookie: primární metoda zahrnuje použití výjimky označené @@ — @@||example.org^$cookie. Alternativní metoda využívá výjimku $urlblock (také zahrnutou pod aliasem výjimky $document — $elemhide,jsinject,content,urlblock,extension). Funguje to takto:

  • @@||example.org^$cookie odblokuje všechny soubory cookie nastavené doménou example.org
  • @@||example.org^$urlblock odblokuje všechny cookies nastavené doménou example.org a zakáže blokování všech požadavků odeslaných z example.org
  • @@||example.org^$cookie=concept odblokuje jeden soubor cookie s názvem concept
  • @@||example.org^$cookie=/^_ga_/ odblokuje každý soubor cookie, který odpovídá regulárnímu výrazu
Omezení

V AdGuardu pro Chrome MV3 odstraňujeme soubory cookies 2 způsoby: ze strany content-script (ke které máme přístup) a z onBeforeSendHeaders posluchače. Vzhledem k tomu, že onBeforeSendHeaders a další posluchači již nejsou blokováni, je nemůžeme ve všech případech smazat. Pomocí tohoto testu můžete zkontrolovat, zda pravidlo funguje.

Omezení

Pravidla $cookie podporují tři typy modifikátorů: $domain, $~domain, $important, $third-party, $~third-party, strict-third-party a strict-first-party.

Kompatibilita

Pravidla s modifikátorem $cookie nejsou podporována Blokátorem obsahu AdGuard, AdGuardem pro iOS a AdGuardem pro Safari.

$csp​

Tento modifikátor zcela mění chování pravidla. Pokud je použitý na pravidlo, pravidlo nezablokuje odpovídající požadavek. Namísto toho se upraví záhlaví odpovědí.

informace

Pro použití tohoto typu pravidel je nutné mít základní znalosti o vrstvě zabezpečení Content Security Policy.

U požadavků, které odpovídají pravidlu $csp, posílíme zásady zabezpečení odezvy posílením zásad zabezpečení obsahu, podobně jako u zásad zabezpečení obsahu modifikátoru obsahu $csp. Pravidla $csp jsou aplikována nezávisle na jakémkoli jiném typu pravidla. Mohou je ovlivnit pouze výjimky na úrovni dokumentu (viz část s příklady), ale žádná jiná základní pravidla.

Vícenásobná pravidla odpovídajících jednomu požadavku

V případě, že jednomu požadavku odpovídá více pravidel $csp, použijeme každé z nich.

Syntaxe

Syntaxe hodnoty $csp je podobná syntaxi záhlaví Content Security Policy.

Hodnota $csp může být v případě pravidel pro výjimky prázdná. Viz níže uvedený oddíl s příklady.

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říznakem frame-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.
Omezení
  • V hodnotě $csp je zakázáno několik znaků: ,, $.
  • $csp pravidla podporují tři typy modifikátorů: $domain, $important, $subdocument.
  • Pravidla s direktivami report-* jsou považována za neplatná.
Kompatibilita

Pravidla s modifikátorem $csp nejsou podporována Blokátorem obsahu AdGuard, AdGuardem pro iOS a AdGuardem pro Safari.

$hls​

Pravidla $hls upravují odpověď na shodný požadavek. Jsou určena k pohodlnému odstraňování segmentů ze seznamů stop HLS playlists (RFC 8216).

poznámka

Slovo "segment" v tomto dokumentu znamená buď "mediální segment" nebo "seznam skladeb" jako součást "hlavního seznamu skladeb": pravidla $hls nerozlišují mezi "hlavním seznamem skladeb" a "mediálním seznamem skladeb".

Syntaxe

  • ||example.org^$hls=urlpattern odstraní segmenty, jejichž adresa URL odpovídá vzoru adresy URL urlpattern. 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ýrazu regexp. K dispozici jsou tyto možnosti options:
    • 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.

Znaky /, $ a , musí být uvnitř regexp uvozeny pomocí \.

Výjimky

Základní výjimky URL nesmí zakázat pravidla s modifikátorem $hls. Lze je zakázat, jak je popsáno níže:

  • @@||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 s text pro odpovědi z URL odpovídajících ||example.org^.
tip

Pravidla $hls lze také zakázat pravidly výjimek $document, $content a $urlblock.

poznámka

Když vícenásobná pravidla $hls odpovídají stejnému požadavku, jejich účinek je kumulativní.

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.

Anatomie seznamu stop HLS

Stručné shrnutí specifikace:

  1. Seznam stop HLS je kolekce textových řádků
  2. Řádek může být prázdný, komentář (začíná #), znak (také začíná #, lze jej rozpoznat pouze podle názvu) nebo URL
  3. Řádek URL se nazývá "segment"
  4. 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

Některé specifické body týkající se fungování pravidel $hls:

  1. Při odstranění segmentu se odstraní také všechny znaky, které se vztahují pouze k tomuto segmentu
  2. Pokud se znak vztahuje na více segmentů a všechny tyto segmenty jsou odstraněny, je odstraněna i znak
  3. 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
  4. 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

Příklad transformace provedené podle pravidel:

Původní odezva
#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
Použitá pravidla
||example.org^$hls=preroll
||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
Modifikovaná odpověď
#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
Omezení
  • Pravidla s modifikátorem $hls lze použít pouze v důvěryhodných filtrech.
  • $hls pravidla jsou kompatibilní pouze s těmito modifikátory: $domain, $third-party, $strict-third-party, $strict-first-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.
Kompatibilita

Pravidla s modifikátorem $hls jsou podporována AdGuardem pro Windows, Mac, Android a Linux s CoreLibs v1.10 nebo novější.

$inline-script​

Modifikátor $inline-script je určen k blokování in-line JavaScriptu vloženého do webové stránky pomocí zásad zabezpečení obsahu (CSP). Zlepšuje zabezpečení a soukromí tím, že zabraňuje použití in-line reklam nebo potenciálně škodlivých skriptů. Pravidlo ||example.org^$inline-script se převádí na syntaxi pravidel CSP:

||example.org^$csp=script-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:

$inline-font​

Modifikátor $inline-font je určen k blokování in-line fontů vložených do webové stránky pomocí zásad zabezpečení obsahu (CSP). Zlepšuje zabezpečení a soukromí tím, že zabraňuje použití in-line fontů, které by mohly být použity ke shromažďování dat a čtení digitálních otisků. Pravidlo ||example.org^$inline-font se převádí na syntaxi pravidel CSP:

||example.org^$csp=font-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:

$jsonprune​

Pravidla $jsonprune upravují odpověď na odpovídající požadavek odstraněním položek JSON, které odpovídají upravenému výrazu JSONPath. Nemění odpovědi, které nejsou platnými dokumenty JSON.

V AdGuardu pro Windows, Mac a Android s CoreLibs v1.11 nebo novější, $jsonprune podporuje také úpravu dokumentů JSONP (padded JSON).

Syntaxe

  • ||example.org^$jsonprune=expression odstraní z odpovědi položky, které odpovídají upravenému výrazu JSONPath expression.

Vzhledem ke způsobu zpracování pravidel musí být znaky $ a , uvnitř výrazu uvozeny pomocí \.

Upravená syntaxe JSONPath má oproti původní následující rozdíly:

  1. Výrazy skriptů nejsou podporovány
  2. 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
  3. Mezery mimo řetězce s dvojitými nebo jednoduchými uvozovkami nemají žádný význam
  4. Lze použít řetězce s dvojitými i jednoduchými uvozovkami
  5. Výrazy končící na .. nejsou podporovány
  6. V hranatých závorkách lze zadat vícero dílků pole

Existují různé online nástroje, které usnadňují práci s výrazy JSONPath:

https://www.site24x7.com/tools/jsonpath-finder-validator.html https://jsonpathfinder.com/ https://jsonpath.com/

Mějte však na paměti, že všechny implementace JSONPath mají jedinečné vlastnosti a jsou vzájemně nekompatibilní.

Výjimky

Základní výjimky URL nesmí zakázat pravidla s modifikátorem $jsonprune. Lze je zakázat, jak je popsáno níže:

  • @@||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 s text pro odpovědi z URL odpovídajících ||example.org^.

Pravidla $jsonprune lze také zakázat pravidly výjimek $document, $content a $urlblock.

poznámka

Když vícenásobná pravidla $jsonprune odpovídají stejnému požadavku, jsou seřazena v lexikografickém pořadí, první pravidlo je aplikováno na původní odpověď a každé ze zbývajících pravidel je aplikováno na výsledek použití předchozího.

Příklady

  • ||example.org^$jsonprune=\$..[one\, "two three"] odstraní všechny výskyty klíčů "one" a "two three" kdekoli v dokumentu JSON.
Vstup
{
    "one": 1,
    "two": {
        "two three": 23,
        "four five": 45
    }
}
Výstup
{
    "two": {
        "four five": 45
    }
}
  • ||example.org^$jsonprune=\$.a[?(has ad_origin)] odstraní všechny potomky a, které mají klíč ad_origin.
Vstup
{
    "a": [
        {
            "ad_origin": "https://example.org",
            "b": 42
        },
        {
            "b": 1234
        }
    ]
}
Výstup
{
    "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".
Vstup
{
    "a": {"b": {"c": {"Some key": "Some value"}, "d": {"Some key": "Other value"}}},
    "e": {"f": [{"Some key": "Some value"}, {"Some key": "Other value"}]}
}
Výstup
{
    "a": {"b": {"d": {"Some key": "Other value"}}},
    "e": {"f": [{"Some key": "Other value"}]}
}

Vnořené výrazy JSONPath

V AdGuardu pro Windows, Mac a Android s CoreLibs v1.11 nebo novější, lze výrazy JSONPath použít jako klíče ve výrazech filtru.

  • ||example.org^$jsonprune=\$.elems[?(má "\$.abc")] odstraní všechny potomky elems, které mají vlastnost volitelnou výrazem JSONPath $.abc.
Vstup
{
    "elems": [
        {
            "a": {"b": {"c": 123}},
            "k": "v"
        },
        {
            "d": {"e": {"f": 123}},
            "k1": "v1"
        }
    ]
}
Výstup
{
    "elems": [
        {
            "d": {"e": {"f": 123}},
            "k1": "v1"
        }
    ]
}
  • ||example.org^$jsonprune=\$.elems[?(key-eq "\$.a.b.c" "abc")] odstraní všechny potomky elems, které mají vlastnost volitelnou pomocí výrazu JSONPath $.a.b.c s hodnotou rovnou "abc".
Vstup
{
    "elems": [
        {
            "a": {"b": {"c": 123}}
        },
        {
            "a": {"b": {"c": "abc"}}
        }
    ]
}
Výstup
{
    "elems": [
        {
            "a": {"b": {"c": 123}}
        }
    ]
}
Omezení
  • $jsonprune pravidla jsou kompatibilní pouze s těmito modifikátory: $domain, $third-party, $strict-third-party, $strict-first-party, $app, $important, $match-case a $xmlhttprequest.
  • Pravidla $jsonprune neplatí, pokud je velikost původní odpovědi větší než 10 MB.
Kompatibilita

Pravidla s modifikátorem $jsonprune jsou podporována AdGuardem pro Windows, Mac, Android a Linux s CoreLibs v1.10 nebo novější.

$xmlprune​

Pravidla $xmlprune upravují odpověď na odpovídající požadavek odstraněním položek XML, které odpovídají upravenému výrazuXPath 1.0. Výraz musí vrátit node-set. $xmlprune pravidla neupravují odpovědi, které nejsou dobře formulovanými dokumenty XML.

Syntaxe

  • ||example.org^$xmlprune=expression odstraní z odpovědi položky, které odpovídají výrazu XPath expression.

Vzhledem ke způsobu zpracování pravidel musí být znaky $ a , uvnitř výrazu uvozeny pomocí \.

Výjimky

Základní výjimky URL nesmí zakázat pravidla s modifikátorem $xmlprune. Lze je zakázat, jak je popsáno níže:

  • @@||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 s text pro odpovědi z URL odpovídajících ||example.org^.

Pravidla $xmlprune lze také zakázat pravidly výjimek $document, $content a $urlblock.

poznámka

Když je více pravidel $xmlprune odpovídá stejnému požadavku, jsou použita v lexikografickém pořadí.

Příklady

  • ||example.org^$xmlprune=/bookstore/book[position() mod 2 = 1] odstraní z knihkupectví knihy s lichými čísly.
Vstup
<?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>
Výstup
<?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í.
Vstup
<?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>
Výstup
<?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ů.
Vstup
<?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>
Výstup
<?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>
Omezení
  • $xmlprune pravidla jsou kompatibilní pouze s těmito modifikátory: $domain, $third-party, $strict-third-party, $strict-first-party, $app, $important, $match-case a $xmlhttprequest.
  • Pravidla $xmlprune neplatí, pokud je velikost původní odpovědi větší než 10 MB.
Kompatibilita

Pravidla s modifikátorem $xmlprune jsou podporována AdGuardem pro Windows, Mac, Android a Linux s CoreLibs v1.15 nebo novější.

$network​

Jedná se v podstatě o pravidla typu brány Firewall, která umožňují plně zablokovat nebo odblokovat přístup na zadanou vzdálenou adresu.

  1. Pravidla $network odpovídají pouze IP adresám! Nelze je použít k zablokování nebo odblokování přístupu k doméně.
  2. 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.
  3. 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í.
  4. Pokud část IP začíná a končí znakem /, je považována za regulární výraz.

Pro lepší pochopení regulárních výrazů doporučujeme seznámit se s tímto článkem.

Omezení

Modifikátor $network lze v pravidlech použít pouze společně s modifikátory $app a $important, nikoli s žádnými jinými modifikátory.

Příklady

  • 174.129.166.49:3478^$network blokuje přístup k 174.129.166.49:3478 (ale ne k 174.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 k 174.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 k 8.8.8.8 a 8.8.8.4.
Kompatibilita

Pouze AdGuard pro Windows, Mac a Android jsou technicky schopné používat pravidla s modifikátorem $network.

$permissions​

Tento modifikátor zcela mění chování pravidla. Pokud je použitý na pravidlo, pravidlo nezablokuje odpovídající požadavek. Namísto toho se upraví záhlaví odpovědí.

informace

Pro použití tohoto typu pravidel je nutné mít základní znalosti o vrstvě zabezpečení Permissions Policy.

U požadavků, které odpovídají pravidlu $permissions, AdGuard posiluje zásady funkcí odpovědi přidáním dalších zásad oprávnění, které se rovnají obsahu modifikátoru $permissions. Pravidla $permissions jsou aplikována nezávisle na jakémkoli jiném typu pravidla. Mohou je ovlivnit pouze výjimky na úrovni dokumentu (viz část s příklady), ale žádná jiná základní pravidla.

Syntaxe

Hodnota syntaxe $permissions je shodná se syntaxí záhlaví Permissions-Policy s následujícími výjimkami:

  1. Čárka, která odděluje více prvků MUSÍ být uvozena – viz příklady níže.
  2. Místo čárky lze pro oddělení funkcí použít znak (|).

Seznam dostupných direktiv je k dispozici v Zásadách oprávnění.

Hodnota $permissions může být v případě pravidel pro výjimky prázdná — viz příklady níže.

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ámci example.org.
  • @@||example.org/page/*$permissions=autoplay=() zakáže všechna pravidla s modifikátorem $permissions přesně odpovídajícím příznakem autoplay=() na všech stránkách odpovídajících vzoru pravidla. Např. výše uvedené pravidlo. Je důležité si uvědomit, že pravidlo výjimky se projeví pouze v případě přesné shody hodnot. Pokud například chcete zakázat pravidlo $permissions=a=()\,b=(), potřebujete pravidlo výjimky @@$permissions=a=()\,b=() a ne @@$permissions=b=()\,a=() ani @@$permissions=b=(), protože b=()\,a=() nebo b=() neodpovídá a=()\,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 a example.com.
  • $domain=example.org|example.com,permissions=storage-access=()|camera=() dělá totéž — místo čárky lze k oddělení funkcí použít |.
  • @@||example.org^$document nebo @@||example.org^$urlblock zakáží všechna pravidla $permission na všech stránkách odpovídajících vzoru pravidla.
poznámka

Pravidla $permissions jsou účinná pouze pro požadavky hlavního rámce a vedlejšího rámce. To znamená, že se použijí při načtení stránky nebo iframe.

poznámka

Pokud existuje více pravidel $permissions, která odpovídají stejnému požadavku, bude do odpovědi přidáno více záhlaví Permissions-Policy pro každé pravidlo s jejich hodnotou $permissions. Pokud tedy máte dvě pravidla: ||example.org^$permissions=autoplay=() a ||example.org^$permissions=geolocation=()\,camera=(), která odpovídají stejnému požadavku, bude odpověď obsahovat dvě záhlaví Permissions-Policy: autoplay=() a geolocation=()\,camera=().

omezení modifikátoru $permissions​
Omezení

Firefox ignoruje záhlaví Permissions-Policy. Další informace naleznete v tomto hlášení.

Omezení
  1. Zakázané znaky v $permissions hodnotě: $.
  2. $permissions je kompatibilní s omezenou sadou modifikátorů: $domain, $important, $subdocument a modifikátory typu obsahu.
  3. Pravidla $permissions, která neobsahují žádné modifikátory typu obsahu , budou odpovídat pouze požadavkům, jejichž typem obsahu je document.
Kompatibilita
  • Pravidla s modifikátorem $permissions jsou podporována AdGuardem pro Windows, AdGuardem pro Mac, AdGuardem pro Android a AdGuardem pro Linux s CoreLibs v1.11 nebo novějším a rozšířením prohlížeče AdGuard s TSUrlFilter v3.0.0 nebo novějším.
  • Oddělovač | místo uvozené čárky je podporován AdGuardem pro Windows, AdGuardem pro macOS, AdGuardem pro Android a AdGuardem pro Linux s CoreLibs v1.14 nebo novějším a rozšířením prohlížeče AdGuard s TSUrlFilter v3.0.0 nebo novějším.

$redirect​

AdGuard je schopen přesměrovat webové požadavky na místní "zdroj".

Syntaxe

AdGuard používá stejnou syntaxi pravidel filtrování jako uBlock Origin. Je také kompatibilní s modifikátorem ABP $rewrite=abp-resource.

$redirect je modifikátor pro základní pravidla filtrování, takže pravidla s tímto modifikátorem podporují všechny ostatní základní modifikátory, jako jsou $domain, $third-party, $script atd.

Hodnota modifikátoru $redirect musí být název zdroje, který bude použit pro přesměrování.

Zakázání pravidel $redirect​
  • ||example.org/script.js$script,redirect=noopjs — toto pravidlo přesměruje všechny požadavky na example.org/script.js na zdroj s názvem noopjs.
  • ||example.org/test.mp4$media,redirect=noopmp4-1s — toto pravidlo přesměruje všechny požadavky na example.org/test.mp4 na zdroj s názvem noopmp4-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^.

Další informace o přesměrování a použití jsou k dispozici na GitHubu.

Priority pravidel $redirect​

Pravidla $redirect mají vyšší prioritu než běžná základní pravidla blokování. To znamená, že pokud existuje základní pravidlo blokování, pravidlo $redirect jej přepíše. Pravidla seznamu povolených se znakem @@ mají vyšší prioritu než pravidla $redirect. Pokud se základní pravidlo s modifikátorem $important a pravidlem $redirect shoduje se stejnou adresou URL, je druhé pravidlo přepsáno, pokud není též označeno jako $important.

Ve zkratce: $important > @@ > $redirect > basic rules.

Další podrobnosti najdete v prioritách pravidel.

omezení modifikátoru $redirect​
Omezení

V AdGuardu pro Chrome MV3 nejsou podporována pravidla $redirect.

Kompatibilita

$redirect-rule​

Toto je v podstatě alias $redirect, protože má stejné hodnoty "přesměrování" a logika je téměř podobná. Rozdíl je v tom, že $redirect-rule se použije pouze v případě, kdy je cílový požadavek blokován jiným základním pravidlem.

Další podrobnosti najdete v prioritách pravidel.

Negace $redirect-rule funguje úplně stejně jako u běžných pravidel $redirect. Ještě více než to, bude @@||example.org^$redirect negovat jak pravidla $redirect, tak $redirect-rule.

Příklady

||example.org/script.js
||example.org^$redirect-rule=noopjs

V tomto případě budou pouze požadavky na example.org/script.js "přesměrovány" na noopjs. Všechny ostatní požadavky na example.org zůstanou nedotčeny.

Kompatibilita

Pravidla s modifikátorem $redirect-rule nejsou podporována Blokátorem obsahu AdGuard, AdGuardem pro iOS, AdGuardem pro Safari a AdGuardem pro Chrome MV3. Diskuse o přidání podpory pro pravidla $redirect-rule v rozšířeních Chrome MV3 je aktuálně otevřená.

$referrerpolicy​

Tato pravidla umožňují přepsat zásady odkazovačů stránky. V odezvách na shodné požadavky budou všechny hlavičky Referrer-Policy nahrazeny jedinou hlavičkou s hodnotou rovnou hodnotě modifikátoru shodného pravidla. Pokud odezva obsahuje dokument HTML se značkou <meta name="referrer"..., atribut content značky bude také nahrazen hodnotou modifikátoru.

Pravidlo výjimky s hodnotou modifikátoru zakáže pravidlo blokování se stejnou hodnotou modifikátoru. Pravidlo výjimky bez hodnoty modifikátoru zakáže všechna odpovídající pravidla zásad odkazování.

Pokud požadavek odpovídá více pravidlům $referrerpolicy, která nejsou zakázána výjimkami, použije se pouze jedno z nich (není uvedeno, které). $referrerpolicy pravidla bez specifikovaných modifikátorů typu obsahu platí pro $document a $subdocument typy obsahu.

Příklady

  • ||example.com^$referrerpolicy=unsafe-url přepíše zásady odkazování pro example.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 na example.com/abcd.html.
Kompatibilita

Pravidla s modifikátorem $referrerpolicy jsou podporována AdGuardem pro Windows, Mac, Android a Linux s CoreLibs v1.12 nebo novější.

$removeheader​

Pravidla s modifikátorem $removeheader jsou určena k odstranění záhlaví z požadavků a odpovědí HTTP. Původní motivací pro tento typ pravidla je možnost zbavit se záhlaví Refresh, které se často používá k přesměrování uživatelů na nežádoucí místo. To však není jediný případ, kdy může být tento modifikátor užitečný.

Stejně jako $csp, $redirect, $removeparam a $cookie i tento modifikátor existuje samostatně, pravidla s ním nezávisí na běžných základních pravidlech, tj. pravidelná výjimka nebo pravidla blokování jej neovlivní. Ve výchozím nastavení ovlivňuje pouze záhlaví odpovědí. Můžete jej však také změnit tak, aby odstraňoval hlavičky z požadavků HTTP.

Syntaxe

Základní syntaxe

  • ||example.org^$removeheader=header-name odstraní odpověď záhlaví s názvem header-name
  • ||example.org^$removeheader=request:header-name odstraní požadavek záhlaví s názvem header-name

$removeheader nerozlišuje velká a malá písmena, doporučujeme vždy používat malá písmena.

Negace $removeheader

Tento typ pravidel funguje v podstatě stejně jako u modifikátorů $csp a $redirect.

K negaci $removeheader použijte @@:

  • @@||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^.

Pravidla $removeheader lze také zakázat pravidly výjimek $document a $urlblock. Základní pravidla pro výjimky bez modifikátorů to však nedělají. Např. @@||example.com^ nezakáže $removeheader=p pro požadavky na example.com, ale @@||example.com^$urlblock ano.

poznámka

V případě, že jednomu požadavku odpovídá více pravidel $removeheader, použijeme každé z nich.

Příklady

  • ||example.org^$removeheader=refresh odstraní záhlaví Refresh ze všech HTTP odpovědí vrácených doménou example.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 a Location ze všech odpovědí HTTP vrácených doménou example.org s výjimkou požadavků na example.org/path/*, u kterých nebudou odstraněny žádné záhlaví:

    ||example.org^$removeheader=refresh
    ||example.org^$removeheader=location
    @@||example.org/path/$removeheader
omezení modifikátoru $removeheader​
Omezení

AdGuard pro Chrome MV3 má některá omezení:

  • Pravidla negace a seznamu povolených nejsou podporována.

  • Skupina podobných $removeheader pravidel bude sloučena do jednoho dekorativního pravidla. Např:

    ||testcases.adguard.com$xmlhttprequest,removeheader=p1case1
    ||testcases.adguard.com$xmlhttprequest,removeheader=P2Case1
    $xmlhttprequest,removeheader=p1case2
    $xmlhttprequest,removeheader=P2case2

    je převedeno na

    [
      {
        "id": 1,
        "action": {
          "type": "modifyHeaders",
          "responseHeaders": [
            {
                "header": "p1case1",
                "operation": "remove"
            },
            {
                "header": "P2Case1",
                "operation": "remove"
            },
          ]
        },
        "condition": {
          "urlFilter": "||testcases.adguard.com",
          "resourceTypes": [
            "xmlhttprequest"
          ]
        }
      },
      {
        "id": 2,
        "action": {
          "type": "modifyHeaders",
          "responseHeaders": [
            {
                "header": "p1case2",
                "operation": "remove"
            },
            {
                "header": "P2case2",
                "operation": "remove"
            }
          ]
        },
        "condition": {
          "resourceTypes": [
            "xmlhttprequest"
          ]
        }
      }
    ]
Omezení

Tento typ pravidel lze použít pouze v důvěryhodných filtrech.

  1. 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

  2. $removeheader pravidla jsou kompatibilní pouze s těmito modifikátory: $domain, $third-party, $strict-third-party, $strict-first-party, $app, $important, $match-case a modifikátory typu obsahu jako $script a $stylesheet. Pravidla s jinými modifikátory jsou považována za neplatná a budou vyřazena.

Kompatibilita

Pravidla s modifikátorem $removeheader podporuje AdGuard pro Windows, Mac, Android a Rozšíření prohlížeče AdGuard pro Chrome, Firefox a Edge.

$removeparam​

poznámka

$queryprune je alias $removeparam. Protože je $queryprune zastaralý, nepoužívejte jej a místo něj použijte $removeparam.

Pravidla s modifikátorem $removeparam jsou určena k odstranění parametrů dotazu z požadavků adres URL. Upozorňujeme, že tato pravidla se vztahují pouze na požadavky GET, HEAD, OPTIONS a někdy POST.

Syntaxe

Základní syntaxe

  • $removeparam=param odstraní parametr dotazu s názvem param z URL libovolného požadavku, např. požadavek na https://example.com/page?param=1&another=2 bude transformován na https://example.com/page?another=2.

Regulární výrazy

Regulární výrazy můžete použít také k porovnání parametrů dotazu a/nebo jejich hodnot:

  • $removeparam=/regexp/[options] — odstraní parametry dotazu, které odpovídají regulárnímu výrazu regexp z adres URL jakéhokoli požadavku. Na rozdíl od základní syntaxe to znamená "odebrat parametry dotazu normalizované na řetězec name=value, který odpovídá regulárnímu výrazu regexp ". [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.

Uvození speciálních znaků

Speciální znaky by měly být v pravidle URL zakódovány, aby správně odpovídaly textu URL.

Například, pro odstranění ?$param=true byste měli použít pravidlo $removeparam=%24param.

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

Mezery a čárky by měly být také zakódovány v adrese URL, jinak pravidlo nebude odpovídat adrese URL. Nicméně, znaky ., -, _ a ~ by měly být používány tak, jak jsou, protože nejsou označeny jako rezervované znaky v kódování URL.

:::

Nezapomeňte v regulárních výrazech používat uvození speciálních znaků, jako je například .. K tomu použijte znak \. Např. uvozená tečka by měla vypadat takto: \..

poznámka

Pravidla typu regexp se vztahují na název i hodnotu parametru. Pro minimalizaci chyb je bezpečnější začínat každý regexp znakem /^, pokud se nezaměřujete konkrétně na hodnoty parametrů.

Odebrat všechny parametry dotazu

Chcete-li odebrat všechny parametry dotazu, zadejte samostatně $removeparam:

  • ||example.org^$removeparam — odstraní všechny parametry dotazu z adres URL odpovídajících ||example.org^.

Inverze

Pro použití inverze použijte ~:

  • $removeparam=~param — odstraní všechny parametry dotazu s názvem odlišným od param.
  • $removeparam=~/regexp/ — odstraní všechny parametry dotazu, které neodpovídají regulárnímu výrazu regexp.

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

Pokud se ~ neobjeví na začátku pravidla, považuje se za symbol v textu.

:::

Negace $removeparam

Tento druh pravidel funguje v podstatě stejně jako u modifikátorů $csp a $redirect.

K negaci $removeparam použijte @@:

  • @@||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^.

Vícenásobná pravidla odpovídajících jednomu požadavku

V případě, že jednomu požadavku odpovídá více pravidel $removeparam, bude každé z nich použito jedno po druhém.

Příklady

$removeparam=/^(utm_source|utm_medium|utm_term)=/
$removeparam=/^(utm_content|utm_campaign|utm_referrer)=/
@@||example.com^$removeparam

S těmito pravidly bude z jakéhokoli požadavku odstraněno UTM parametrů, kromě toho, že požadavky na example.com nebudou odstraněny vůbec, např. https://google.com/page?utm_source=s&utm_referrer= fb.com&utm_content=img bude transformováno na https://google.com/page, ale https://example.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img nebude ovlivněno pravidlem blokování.

  • $removeparam=utm_source odstraní parametr dotazu utm_source ze všech požadavků.

  • $removeparam=/utm_.*/ odstraní všechny parametry utm_* query z URL libovolného požadavku, např. požadavek na https://example.com/page?utm_source=test bude transformován na https://example.com/page.

  • $removeparam=/^utm_source=campaign$/ odstraní parametr dotazu utm_source s hodnotou rovnou campaign. Nemá vliv na ostatní parametry utm_source.

Negace pravidla $removeparam a jeho nahrazení jiným pravidlem

$removeparam=/^(gclid|yclid|fbclid)=/
@@||example.com^$removeparam=/^(gclid|yclid|fbclid)=/
||example.com^$removeparam=/^(yclid|fbclid)=/

Díky těmto pravidlům budou ze všech požadavků odstraněny identifikátory kliknutí Google, Yandex a Facebook. Existuje jedna výjimka: Z požadavků na example.com nebude odstraněno Google Click ID (gclid).

Negace pro všechny parametry $removeparam

$removeparam=/^(utm_source|utm_medium|utm_term)=/
$removeparam=/^(utm_content|utm_campaign|utm_referrer)=/
@@||example.com^$removeparam

Díky těmto pravidlům budou zadané parametry UTM odstraněny ze všech požadavků s výjimkou požadavků na example.org.

Pravidla $removeparam lze také zakázat pravidly výjimek $document a $urlblock. Základní pravidla pro výjimky bez modifikátorů to však nedělají. Např. @@||example.com^ nezakáže $removeparam=p pro požadavky na example.com, ale @@||example.com^$urlblock ano.

omezení modifikátoru $removeparam​
Omezení

AdGuard pro Chrome MV3 má některá omezení:

  • Regulární výrazy, negace a pravidla seznamu povolených nejsou podporovány.

  • Každé pravidlo $removeparam s pojmenovaným parametrem má své vlastní deklarativní pravidlo s parametrem urlFilter (například ^utm_source=). Chrome DNR provede přesměrování pouze jednou za relaci, takže bez této funkce by se uplatnilo pouze pravidlo s nejvyšší prioritou a ostatní by byla přeskočena. Param-aware urlFilter způsobí, že se každé pravidlo spustí pouze v případě, že je přítomen jeho cílový parametr a vytvoří řetězec přesměrování — na každý skok je odstraněn jeden parametr — dokud nejsou všechny odstraněny. Chrome umožňuje až 20 přesměrování na jednu navigaci, což je dost pro reálné sledovací URL. Tyto skoky nejsou pro uživatele viditelné. Příklad:

    ||testcases.adguard.com$xmlhttprequest,removeparam=p1case1
    ||testcases.adguard.com$xmlhttprequest,removeparam=p2case1
    ||testcases.adguard.com$xmlhttprequest,removeparam=P3Case1
    $xmlhttprequest,removeparam=p1case2

    je převedeno na

    [
    {
      "id": 1,
      "action": {
      "type": "redirect",
      "redirect": {
        "transform": {
        "queryTransform": {
          "removeParams": [
          "p1case1"
          ]
        }
        }
      }
      },
      "condition": {
      "urlFilter": "||testcases.adguard.com*^p1case1=",
      "resourceTypes": [
        "xmlhttprequest"
      ]
      }
    },
    {
      "id": 2,
      "action": {
      "type": "redirect",
      "redirect": {
        "transform": {
        "queryTransform": {
          "removeParams": [
          "p2case1"
          ]
        }
        }
      }
      },
      "condition": {
      "urlFilter": "||testcases.adguard.com*^p2case1=",
      "resourceTypes": [
        "xmlhttprequest"
      ]
      }
    },
    {
      "id": 3,
      "action": {
      "type": "redirect",
      "redirect": {
        "transform": {
        "queryTransform": {
          "removeParams": [
          "P3Case1"
          ]
        }
        }
      }
      },
      "condition": {
      "urlFilter": "||testcases.adguard.com*^P3Case1=",
      "resourceTypes": [
        "xmlhttprequest"
      ]
      }
    },
    {
      "id": 4,
      "action": {
      "type": "redirect",
      "redirect": {
        "transform": {
        "queryTransform": {
          "removeParams": [
          "p1case2"
          ]
        }
        }
      }
      },
      "condition": {
      "urlFilter": "^p1case2=",
      "resourceTypes": [
        "xmlhttprequest"
      ]
      }
    }
    ]
Omezení
  1. Pravidla s modifikátorem $removeparam lze použít pouze v důvěryhodných filtrech.
  2. 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.
  3. Ačkoli je modifikátor $domain klasifikován jako základní, není kompatibilní s pravidly $removeparam v rozšíření Manifest V3.
  4. Pravidla $removeparam, která neobsahují žádné modifikátory typu obsahu, budou odpovídat pouze požadavkům, jejichž typem obsahu je document.
Kompatibilita
  • Pravidla s modifikátorem $removeparam jsou podporována AdGuardem pro Windows, AdGuardem pro macOS, AdGuardem pro Android a AdGuardem pro Linux s CoreLibs v1.7 nebo novější a Rozšířením prohlížeče AdGuard v3.6 nebo novějším.
  • Syntaxe $removeparam pro regulární výrazy je podporována AdGuardem pro Windows, AdGuardem pro macOS a AdGuardem pro Android s CoreLibs v1.8 nebo novější a Rozšířením prohlížeče AdGuard v4.0 nebo novějším.
  • Typy požadavků POST podporuje pouze AdGuard pro Windows, Mac a Android s CoreLibs v1.10 nebo novější a rozšíření prohlížeče AdGuard s TSWebExtension v0.4.6 nebo novější.

$replace​

Tento modifikátor zcela mění chování pravidla. Pokud je použitý, pravidlo požadavek nezablokuje. Namísto toho bude odpověď upravena.

K použití modifikátoru $replace budete potřebovat určité znalosti regulárních výrazů.

Funkce

  • 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.

Hodnota $replace může být v případě pravidel pro výjimky prázdná. Další informace naleznete v části Příklady.

Vícenásobná pravidla odpovídajících jednomu požadavku

V případě, že jednomu požadavku odpovídá více pravidel $replace, použijeme každé z nich. Pořadí je stanoveno abecedně.

Syntaxe

Obecně je syntaxe $replace podobná nahrazování regulárními výrazy v Perl.

replace = "/" regexp "/" replacement "/" modifiers
  • regexp — regulární výraz.
  • replacement — řetězec, který bude použit k nahrazení řetězce odpovídajícího regexp.
  • modifiers — příznaky regulárního výrazu. Například i — necitlivé vyhledávání nebo s — jednořádkový režim.

V hodnotě $replace musí být dva znaky uvozeny: čárka , a znak dolaru $. Použijte pro to zpětné lomítko \. Např. uvozená čárka vypadá takto: \,.

Příklady

||example.org^$replace=/(<VAST[\s\S]*?>)[\s\S]*<\/VAST>/\$1<\/VAST>/i

Toto pravidlo má tři části:

  • regexp — (<VAST(.|\s)*?>)(.|\s)*<\/VAST>;
  • replacement — \$1<\/VAST> kde $ je uvozeno;
  • modifiers — i pro necitlivé vyhledávání.

Jak toto pravidlo funguje, se můžete podívat zde: https://regexr.com/3cesk

Vícenásobná pravidla $replace

  1. ||example.org^$replace=/X/Y/
  2. ||example.org^$replace=/Z/Y/
  3. @@||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!

Zakázání pravidel $replace

  • @@||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ánek example.org včetně stránky samotné.
Omezení
  • Pravidla s modifikátorem $replace lze použít pouze v důvěryhodných filtrech.
  • Pravidla $replace neplatí, pokud je velikost původní odpovědi větší než 10 MB. Pro rozšíření AdGuard platí toto omezení od verze 5.2 nebo novější.
Kompatibilita

Pravidla s modifikátorem $replace podporuje AdGuard pro Windows, Mac, Android a Rozšíření prohlížeče AdGuard pro Chrome, Firefox a Edge. Taková pravidla v rozšířeních pro jiné prohlížeče nefungují, protože nemohou měnit obsah na úrovni sítě.

$urltransform​

Pravidla $urltransform vám umožňují upravit URL požadavku nahrazením textu, který odpovídá regulárnímu výrazu.

Funkce

  • Pravidla $urltransform se obvykle vztahují pouze na části URL týkající se cesty a dotazu, viz níže jedna výjimka.
  • $urltransform nebude použito, pokud je původní URL blokována jinými pravidly.
  • $urltransform se použije před pravidly $removeparam.

Hodnota $urltransform může být pro pravidla výjimek prázdná.

Vícenásobná pravidla odpovídajících jednomu požadavku

Pokud jednomu požadavku odpovídá více pravidel $urltransform, použijeme každé z nich. Pořadí je stanoveno abecedně.

Syntaxe

Hodnota $urltransform je řada jedné nebo více transformací oddělených znakem |. První transformace se aplikuje na vstupní URL. Každá z následujících transformací se aplikuje na výstup předchozí transformace. Výstupem neúspěšné transformace (například pokud selhalo dekódování Base64 nebo pokud substituce nenašla žádné shody) je její vstup, beze změny. Formálně:

urltransform = transforms
transforms = transform | transform "|" transforms
transform = substitute | decode
substitute = "/" regexp "/" replacement "/" modifiers
decode = "b64" | "pct"
  • substitute je podobné nahrazení pomocí regulárních výrazů v Perl.
    • regexp — regulární výraz.
    • replacement — řetězec, který nahrazuje vše, co odpovídá regexp. $1, $2 atd. v náhradním řetězci jsou nahrazeny obsahem odpovídající zachycené skupiny.
    • modifiers — příznaky regulárních výrazů, např. i pro vyhledávání bez rozlišení velkých a malých písmen.
  • b64 — dekóduje řetězec kódovaný v Base64, podporovány jsou jak výchozí abecedy, tak abecedy bezpečné pro URL.
  • pct — dekóduje procenty kódovaný řetězec.

V hodnotě $urltransform musí být dva znaky uvozeny: čárka , a znak dolaru $. K tomu použijte znak zpětného lomítka \. Např. uvozená čárka vypadá takto: \,.

Kompatibilita

Produkty AdGuard, které používají verzi CoreLibs starší než 1.20, podporují pouze jednu substituční transformaci pro hodnotu modifikátoru $urltransform.

Změna původu

Kompatibilita

Tato část platí pouze pro AdGuard pro Windows, AdGuard pro Mac, AdGuard pro Android a Adguardem pro Linux s CoreLibs v1.17 nebo novější.

Jak bylo uvedeno výše, pravidla $urltransform mohou normálně měnit pouze část URL obsahující cestu a dotaz. Pokud však pravidlo regexp začíná řetězcem ^http, pak se prohledává celá adresa URL a pravidlo ji může upravit. Takové pravidlo se neuplatní, pokud transformace adresy URL nelze dosáhnout přesměrováním HTTP (například pokud je metoda požadavku POST).

Příklady

||example.org^$urltransform=/(pref\/).*\/(suf)/\$1\$2/i

Toto pravidlo má tři části:

  • regexp — (pref\/).*\/(suf);
  • replacement — \$1\$2 kde $ je uvozeno;
  • modifiers — i pro necitlivé vyhledávání.

Vícenásobná pravidla $urltransform

  1. ||example.org^$urltransform=/X/Y/
  2. ||example.org^$urltransform=/Z/Y/
  3. @@||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!

Opětovná shoda pravidel po transformaci URL

Po použití všech odpovídajících pravidel $urltransform bude transformovaný požadavek porovnán se všemi ostatními pravidly:

Např. s následujícími pravidly:

||example.com^$urltransform=/firstpath/secondpath/
||example.com/secondpath^

požadavek na https://example.com/firstpath bude zablokován.

Zakázání pravidel $urltransform

  • @@||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^.

Pravidla $urltransform lze také zakázat pravidly výjimek $document a $urlblock. Základní pravidla pro výjimky bez modifikátorů to však nedělají. Např. @@||example.com^ nezakáže $urltransform=/X/Y/ pro požadavky na example.com, ale @@||example.com^$urlblock ano.

Příklad pravidla pro čištění partnerských odkazů

Mnoho webových stránek používá sledovací URL ke sledování kliknutí před přesměrováním na skutečný cíl. Tyto URL obsahují marketingové parametry a analytické tokeny, které lze odstranit, aby se zvýšila ochrana osobních údajů.

Níže je uveden příklad, jak získat čistý odkaz na cíl, abyste obešli sledovací webové stránky a přešli přímo na cíl.

V našem příkladu:

  1. Počáteční URL (se sledováním kliknutí): https://www.aff.example.com/visit?url=https%3A%2F%2Fwww.somestore.com%2F%26referrer%3Dhttps%3A%2F%2Fwww.aff.example.com%2F%26ref%3Dref-123
  2. Sledování URL po dekódování speciálních znaků: https://www.aff.example.com/visit?url=https://www.somestore.com/
  3. Webové stránky, které chcete navštívit: https://www.somestore.com

Abychom mohli vyčistit URL, musíme nejprve dekódovat speciální znaky (jako %3A → :, %2F → /, atd.) a získat skutečnou URL z parametrů sledování. K tomu použijeme modifikátor $urltransform. Následující 4 pravidla nahrazují symboly URL jejich skutečnými znaky:

/^https?:\/\/(?:[a-z0-9-]+\.)*?aff\.example\.com\/visit\?url=/$urltransform=/%3A/:/ /^https?:\/\/(?:[a-z0-9-]+\.)*?aff\.example\.com\/visit\?url=/$urltransform=/%2F/\// /^https?:\/\/(?:[a-z0-9-]+\.)*?aff\.example\.com\/visit\?url=/$urltransform=/%3F/?/ /^https?:\/\/(?:[a-z0-9-]+\.)*?aff\.example\.com\/visit\?url=/$urltransform=/%3D/=/ /^https?:\/\/(?:[a-z0-9-]+\.)*?aff\.example\.com\/visit\?url=/$urltransform=/%26/&/

Poté musíme napsat pravidlo, které zablokuje sledovací webovou stránku a přesměruje vás přímo na cílovou adresu (somestore.com):

/^https?:\/\/(?:[a-z0-9-]+\.)*?aff\.example\.com\/visit\?url=/$urltransform=/^https?:\/\/(?:[a-z0-9-]+\.)*?aff\.example\.com.*url=([^&]*).*/\$1/

Sledovací odkazy se nyní automaticky vyčistí a umožní přímou navigaci na cílovou webovou stránku bez sledování.

Omezení

Pravidla s modifikátorem $urltransform lze použít pouze v důvěryhodných filtrech.

Pravidla $urltransform, která neobsahují žádné modifikátory typu obsahu, budou odpovídat pouze požadavkům, jejichž typem obsahu je document.

Kompatibilita

Pravidla s modifikátorem $urltransform jsou podporována AdGuardem pro Windows, Mac, Android a Linux s CoreLibs v1.15 nebo novější.

$urltransform pravidla s modifikátory typu obsahu jsou podporována od CoreLibs v1.19 nebo novější. V dřívějších verzích nebyly modifikátory typu obsahu povoleny s $urltransform.

$reason​

Modifikátor $reason umožňuje přidat vlastní vysvětlující zprávu, která se zobrazí na blokovací stránce, když je požadavek tímto pravidlem blokován. Tento modifikátor funguje pouze s modifikátorem typu obsahu $document.

Omezení počtu znaků a požadavky na únik:

  • Pro text s odůvodněním neexistuje žádné omezení maximální délky
  • V textu důvodu jsou povoleny všechny znaky
  • Zvláštní znaky (například uvozovky, čárky a zpětné lomítko) musí být správně uvozeny pomocí zpětného lomítka (\)

Předdefinované lokalizovatelné tokeny:

Místo vlastního textu můžete použít předdefinované tokeny, které budou automaticky lokalizovány:

  • malicious — pro škodlivý obsah
  • tracker — pro sledování obsahu
  • disreputable — pro nedůvěryhodný obsah

Příklady

||example.com^$document,reason="Tracker"
||example.com^$document,reason="Malicious site blocked by security filter"
||ads.example.com^$document,reason="This site contains tracking scripts"
||malware.example.com^$document,reason="Site blocked: \"Known malware distributor\""
||tracking.example.com^$document,reason=disreputable
||analytics.example.com^$document,reason=tracker
Kompatibilita

AdGuard pro Windows, AdGuard pro Mac, AdGuard pro Android a AdGuard pro Linux s CoreLibs v1.20 nebo novější podporují pravidla s modifikátorem $reason. Blokátor obsahu AdGuard tato pravidla nepodporuje.

noop​

Modifikátor noop nedělá nic a lze jej použít pouze ke zvýšení čitelnosti pravidel. Skládá se ze sekvence znaků podtržítka (_) libovolné délky a může se v pravidle objevit tolikrát, kolikrát je potřeba.

Příklady

||example.com$_,removeparam=/^ss\\$/,_,image
||example.com$replace=/bad/good/,___,~third-party
Kompatibilita

Pravidla s modifikátorem noop nejsou Blokátorem obsahu AdGuard podporována.

$empty (zastaralé)​

Upozornění na vyřazení

Tento modifikátor je zastaralý a nahrazuje jej modifikátor $redirect. Pravidla s $empty jsou stále podporována a nyní se převádějí na $redirect=nooptext, ale podpora bude v budoucnu odstraněna.

Obvykle se zablokované požadavky v prohlížeči tváří jako chyba serveru. Pokud použijete modifikátor $empty, AdGuard bude emulovat prázdnou odpověď ze serveru se stavem 200 OK.

Příklady

  • ||example.org^$empty vrátí prázdnou odpověď na všechny požadavky na example.org a všechny subdomény.
Kompatibilita

Pravidla s modifikátorem $empty nejsou podporována Blokátorem obsahu AdGuard, AdGuardem pro iOS a AdGuardem pro Safari.

$mp4 (zastaralé)​

Upozornění na vyřazení

Tento modifikátor je zastaralý a nahrazuje jej modifikátor $redirect. Pravidla s $mp4 jsou stále podporována a nyní se převádějí na $redirect=noopmp4-1s,media, ale podpora bude v budoucnu odstraněna.

Jako odpověď na zablokovaný požadavek vrátí AdGuard krátký zástupný videoklip.

Příklady

  • ||example.com/videa/$mp4 zablokuje všechna stahování videa z ||example.com/videa/* a změní odpověď na zástupný videoklip.
Kompatibilita

Pravidla s modifikátorem $mp4 nejsou podporována Blokátorem obsahu AdGuard, AdGuardem pro iOS a AdGuardem pro Safari.

Priority pravidel​

Každé pravidlo má svou vlastní prioritu, což je nutné v případě, že požadavku odpovídá několik pravidel a filtrovací nástroj musí vybrat jedno z nich. Priorita se měří kladným celým číslem.

Kolize

Pokud stejnému požadavku odpovídají dvě pravidla se stejnou prioritou, implementace filtrovacího modulu určí, které z nich bude vybráno.

informace

Koncept priorit pravidel nabývá na významu ve světle Manifest V3, protože stávající pravidla je třeba převést na pravidla declarativeNetRequest.

Výpočet priority​

Pro výpočet priority jsme modifikátory rozdělili do různých skupin. Tyto skupiny jsou seřazeny podle priority od nejnižší po nejvyšší. Modifikátor, který výrazně zužuje oblast působnosti pravidla, zvyšuje jeho celkovou prioritu. Naopak, pokud se pravidlo vztahuje na širší okruh požadavků, jeho priorita se snižuje.

Stojí za zmínku, že existují případy, kdy má jednoparametrový modifikátor vyšší prioritu než víceparametrový. Například v případě $domain=example.com|example.org má pravidlo, které zahrnuje dvě domény o něco širší oblast účinnosti než pravidlo s jednou zadanou doménou, a proto je jeho priorita nižší.

Základní priorita každého pravidla je 1. Pokud je vypočtená priorita číslo s pohyblivou řádovou čárkou, bude zaokrouhlena nahoru na nejmenší celé číslo větší nebo rovno vypočtené prioritě.

Kompatibilita
  • Koncept priority byl zaveden ve verzích TSUrlFilter v2.1.0 a 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.
poznámka

Aliasy modifikátorů (1p, 3p atd.) nejsou do těchto kategorií zahrnuty, nicméně jsou v rámci enginu využívány pro výpočet priority pravidla.

Základní modifikátory, přítomnost každého z nich přidává 1 k prioritě​

Při práci s negovanou doménou, aplikací, metodou nebo typem obsahu přidáváme 1 bod za existenci samotného modifikátoru bez ohledu na množství negovaných domén nebo typů obsahu. Je to proto, že oblast působnosti tohoto pravidla je již nyní nekonečně široká. Jednoduše řečeno, zákazem více domén, typů obsahu, metod nebo aplikací se rozsah pravidla zmenší jen minimálně.

Definované modifikátory typu obsahu, definované metody, definovaná záhlaví, $all, $popup, specifické výjimky​

Všechny platné typy obsahu:

Patří sem také pravidla, která implicitně přidávají všechny typy obsahu:

Nebo pravidla, která implicitně přidávají modifikátor $document:

Nebo některé speciální výjimky, které implicitně přidávají $document,subdocument:

Nebo povolené metody skrze $method.

Nebo pravidla s $header.

Přítomnost jakýchkoli modifikátorů typu obsahu přidává (50 + 50 / N), kde N je např. počet přítomných modifikátorů: ||example.com^$image,skript přidá 50 + 50 / 2 = 50 + 25 = 75 k celkové váze pravidla.

Do této kategorie patří také $all, protože implicitně přidává všechny modifikátory typu obsahu, např. $document,subdocument,image,script,media,<etc> + $popup.

Do této kategorie patří i $popup, protože implicitně přidává modifikátor $document. Podobně specifické výjimky přidávají $document,subdocument.

Pokud je v pravidle s povolenými metodami modifikátor $method, přidává (50 + 50 / N), kde N je počet povolených metod, např.: ||example.com^$method= GET|POST|PUT přidává 50 + 50 / 3 = 50 + 16,6 = 67 k celkové váze pravidla.

Pokud je v pravidle modifikátor $header, přidává se 50.

$domain nebo $app s povolenými doménami nebo aplikacemi​

Zadané domény prostřednictvím $domain nebo zadané aplikace prostřednictvím $app přidávají 100 + 100 / N, kde N je např. počet hodnot modifikátoru: ||example.com^$domain=example.com|example.org|example.net přidává 100 + 100 / 3 = 134,3 = 135 nebo ||example.com^$app=org.example.app1|org.example.app2 sečte 100 + 100 / 2 = 151 nebo ||example.com^$domain=example.com,app=org.example.app1|org.example.app2 sečte 100 + 100/1 ($domain část) a 100 + 100/2 ($app část), celkem 350.

Hodnoty modifikátorů, které jsou regexp nebo tld, budou interpretovány jako normální položky ve tvaru example.com a budou počítány po jedné, např.: ||example.com^$domain=example.* sečte 100 + 100 / 1 = 200 nebo ||example.com^$domain=example.*|adguard.* sečte 100 + 100 / 2 = 150.

Pravidla $redirect​

Každé z nich přidává 10^3 k prioritě pravidla.

Specifické výjimky​

Každá z nich přidává 10^4 k prioritě.

Stejně jako výjimka s modifikátorem $document: protože je to alias pro $elemhide,content,jsinject,urlblock,extension. Přidá 10^4 pro každý modifikátor z horního seznamu, celkem 10^4 * 5.

Každá z těchto výjimek navíc implicitně přidává dva povolené modifikátory typu obsahu $document,subdocument.

Pravidla seznamu povolených​

Modifikátor @@ přidává 10^5 k prioritě pravidla.

Pravidla $important​

Modifikátor $important přidává 10^6 k prioritě pravidla.

Pravidla, pro která není stanovena váha priority​

Ostatní modifikátory, které mají provádět dodatečné následné nebo předběžné zpracování požadavků, nepřidávají nic k prioritě pravidel.

poznámka

Modifikátor $replace má přednost před všemi pravidly blokování kategorií 1–3, stejně jako před pravidly výjimek z kategorií 3–5, kromě $content, protože výjimka s modifikátorem $content má přednost před všemi pravidly $replace.

Příklady​

  1. ||example.com^

    Váha pravidla bez modifikátorů: 1.

  2. ||example.com^$match-case

    Váha pravidla: základní + váha modifikátoru z kategorie 1: 1 + 1 = 2.

  3. ||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.

  4. ||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.

  5. @@||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.

  6. @@||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.

  7. @@||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.

  8. *$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.

  9. ||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​

Základní pravidla však nemusí k blokování reklam stačit. Někdy potřebujete skrýt prvek nebo změnit část kódu HTML webové stránky, aniž byste cokoli porušili. Pravidla popsaná v této části jsou vytvořena speciálně pro tento účel.

Kategorie \ ProduktyAplikace CoreLibsAdGuard pro ChromiumAdGuard pro Chrome MV3AdGuard pro FirefoxAdGuard pro iOSAdGuard pro SafariBlokátor obsahu AdGuard
Skrytí prvků✅✅✅✅✅✅✅
Pravidla CSS✅✅✅✅✅✅❌
Rozšířené CSS✅✅✅✅✅✅❌
HTML filtrování✅❌❌✅❌❌❌
JavaScript✅✅✅✅✅✅❌
Scriptlety✅✅✅✅✅✅❌
poznámka
  • ✅ — plně podporováno
  • ❌ — nepodporováno

Kosmetická pravidla​

informace

Práce s ostatními pravidly vyžaduje základní znalost HTML a CSS. Pokud se tedy chcete naučit, jak taková pravidla vytvářet, doporučujeme seznámit se s touto dokumentací.

Pravidla pro skrytí prvků​

Pravidla pro skrytí prvků slouží ke skrývání prvků webových stránek. Je to podobné jako použít styl { display: none; } na vybraný prvek.

Pravidla pro skrytí prvků mohou fungovat odlišně v závislosti na platformě.

Syntaxe​

   rule = [domains] "##" selector
domains = [domain0, domain1[, ...[, domainN]]]
  • selektor — CSS selektor definuje prvky, které mají být skryty.
  • domains — omezení domény pro dané pravidlo.

Pokud chcete omezit oblast použití pravidel na určité domény, stačí je zadat oddělené čárkami. Např.: example.org,example.com##selector.

Toto pravidlo bude také použito na všechny subdomény example.org a example.com.

Pokud chcete, aby se pravidlo nevztahovalo na určité domény, začněte název domény znakem ~. Např.: ~example.org##selector.

V jednom pravidle můžete použít oba přístupy. Např. example.org,~subdomain.example.org##domain bude fungovat pro example.org a všechny subdomény kromě subdomain.example.org.

poznámka

Pravidla pro skrývání prvků na sobě nejsou závislá. Pokud je ve filtru pravidlo example.org##selector a přidáte ~example.org##selector, budou obě pravidla použita nezávisle.

Příklady

  • example.com##div.textad — skryje div s třídou textad na doméně example.com a všech subdoménách.
  • example.com,example.org###adblock — skryje prvek s atributem id, který se rovná adblock na example.com, example.org a všech subdoménách.
  • ~example.com##.textad — skryje prvek s třídou textad na všech doménách kromě example.com a jejích subdomén.

Omezení

Safari nepodporuje povolené i zakázané domény. Takže pravidla jako example.org,~foo.example.org##.textad jsou v AdGuardu pro Safari neplatná.

Výjimky

Výjimky mohou zakázat některá pravidla pro určité domény. Jsou velmi podobné běžným pravidlům výjimek, ale namísto ## musíte použít #@#.

Ve filtru je např. pravidlo:

##.textad

Pokud to chcete zakázat pro example.com, můžete vytvořit pravidlo výjimky:

example.com#@#.textad

Někdy může být nutné zakázat všechna pravidla omezení. Např. k provádění testů. Za tímto účelem použijte pravidlo výjimky bez zadání domény. Úplně zakáže odpovídající pravidlo CSS elemhide na VŠECH doménách:

#@#.textad

Toho lze dosáhnout přidáním tohoto pravidla:

*#@#.textad

Tento druh výjimek doporučujeme používat pouze v případě, že není možné změnit samotné pravidlo skrývání. V ostatních případech je lepší změnit původní pravidlo pomocí omezení domény.

Pravidla CSS​

Někdy pouhé skrytí prvku k vyřešení reklamy nestačí. Např. zablokování prvku reklamy může jen narušit rozvržení stránky. V tomto případě může AdGuard použít pravidla, která jsou mnohem flexibilnější než pravidla pro skrývání. Pomocí těchto pravidel můžete v podstatě přidat na stránku libovolné styly CSS.

Syntaxe

   rule = [domains] "#$#" selector "{" style "}"
domains = [domain0, domain1[, ...[, domainN]]]
  • selektor — CSS selektor 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; }

Toto pravidlo použije styl background-color: #333!important; na prvek body na doménu example.com a všechny subdomény.

Výjimky

Stejně jako u skrývání prvků existuje typ pravidel, který zakáže vybrané pravidlo stylu CSS pro určité domény. Syntaxe pravidel pro výjimky je téměř stejná, stačí jen změnit #$# na #@$#.

Ve filtru je např. pravidlo:

#$#.textad { visibility: hidden; }

Pokud to chcete zakázat pro example.com, můžete vytvořit pravidlo výjimky:

example.com#@$#.textad { visibility: hidden; }

Tento druh výjimek doporučujeme používat pouze v případě, že není možné změnit samotné pravidlo CSS. V ostatních případech je lepší změnit původní pravidlo pomocí omezení domény.

Omezení

Styly, které vedou k načtení jakéhokoli zdroje, jsou zakázány. V podstatě to znamená, že ve stylu nelze použít žádný typ hodnoty <url>.

Kompatibilita

Pravidla CSS nejsou Blokátorem obsahu AdGuard podporována.

Pravidla CSS mohou fungovat odlišně v závislosti na platformě.

Kompatibilita s Adblock Plus

V produktech AdGuardu, které používají CoreLibs verze 1.18 nebo novější, můžete také použít pravidla pro skrytí prvků k vložení deklarace remove: true:

example.org##body { remove: true; }

Toto použití se nedoporučuje, protože je lepší používat pravidla CSS, a je podporováno pouze z důvodu kompatibility se seznamy filtrů napsanými pro Adblock Plus.

Výjimky skrytí prvků (#@#) jsou porovnávány pouze podle části selektoru, přičemž část bloku deklarací je ignorována. Například výše uvedené pravidlo lze deaktivovat pomocí kterékoli z následujících výjimek:

example.org#@#body
example.org#@#body { remove: true; }
example.org#@#body{remove:true;}

Rozšířené CSS selektory​

CSS 3.0 ne vždy stačí k blokování reklam. AdGuard tento problém řeší rozšířením možností CSS o podporu nových pseudo-prvků. Vyvinuli jsme samostatnou open-source knihovnu pro výběr nestandardních prvků a aplikaci CSS stylů s rozšířenými vlastnostmi.

Myšlenkou rozšířených možností je možnost přiřazovat prvky DOM pomocí selektorů na základě jejich vlastní reprezentace (styl, textový obsah atd.) nebo vztahů s jinými prvky. Existuje také možnost použít styly s nestandardními vlastnostmi CSS.

Oblast použití

Rozšířené selektory lze použít v jakémkoli kosmetickém pravidle, ať už se jedná o pravidla pro skrytí prvků nebo pravidla CSS.

Kompatibilita

Pravidla se selektory CSS nejsou Blokátorem obsahu AdGuard podporována.

Syntaxe

Bez ohledu na pseudo-třídy CSS, které v pravidle používáte, můžete pomocí speciálních znaků vynutit použití těchto pravidel pomocí ExtendedCss. Doporučujeme používat tyto znaky pro všechna rozšířená kosmetická pravidla CSS, aby bylo snazší je najít.

Syntaxe rozšířených pravidel CSS:

  • #?# — pro skrytí prvku, #@?# — pro výjimky
  • #$?# — pro pravidlo CSS, #@$?# — pro výjimky

Důrazně doporučujeme použít tyto znaky kdykoli, když používáte rozšířený selektor CSS.

Příklady

  • example.org#?#div:has(> a[target="_blank"][rel="nofollow"]) — toto pravidlo blokuje všechny prvky div obsahující podřízený uzel, který má odkaz s atributy [target="_blank"][rel="nofollow"]. Pravidlo platí pouze pro example.org a její subdomény.
  • example.com#$?#h3:contains(cookies) { display: none!important; } — toto pravidlo nastaví styl display: none!important všem prvkům h3, které obsahují slovo cookies. Pravidlo platí pouze pro example.com a všechny její subdomény.
  • example.net#?#.banner:matches-css(width: 360px) — toto pravidlo blokuje všechny prvky .banner s vlastností stylu width: 360px. Pravidlo platí pouze pro example.net a její subdomény.
  • example.net#@?#.banner:matches-css(width: 360px) — toto pravidlo zakáže předchozí pravidlo.

Standardní CSS selektory můžete použít pomocí knihovny ExtendedCss pomocí znaku pravidla #?#, např. #?#div.banner.

Přečtěte si další informace o ladění rozšířených selektorů.

poznámka

Některé pseudo-třídy před sebou selektor nevyžadují. Přesto přidání univerzálního selektoru * usnadňuje čtení rozšířeného selektoru, i když nemá žádný vliv na chování při porovnávání. Takže selektor #blok :has(> .inner) funguje přesně jako #blok *:has(> .inner), ale druhý je zřejmější.

Názvy pseudo-tříd nerozlišují malá a velká písmena, např. :HAS() funguje jako :has(). Přesto se běžně používají názvy s malými písmeny.

Limitace ExtendedCss​

  1. CSS komentáře a at-pravidla nejsou podporovány.

  2. Konkrétní pseudot-řída může mít svá vlastní omezení: :has(), :xpath(), :nth-ancestor(), :upward(), :is(), :not() a :remove().

Pseudo-třída :has()​

Návrh specifikace CSS 4.0 popisuje :has() pseudo-třídu. Bohužel to zatím není podporováno všemi oblíbenými prohlížeči.

poznámka

Pravidla s pseudo-třídou :has() musí používat nativní implementaci :has(), pokud používají znak ## a pokud je to možné, tj. bez dalších rozšířených selektorů uvnitř. Pokud to produkt (nebo v případě rozšíření prohlížeče AdGuard) nepodporuje, bude automaticky použita implementace ExtendedCss jako náhradní řešení, a to i pro pravidla se značkou ##.

AdGuard podporuje nativní implementaci :has():

  • AdGuard pro Windows, AdGuard pro Mac, AdGuard pro Android a AdGuard pro Linux to podporují s knihovnou CoreLibs v1.12 nebo novější.
  • AdGuard pro iOS a AdGuard pro Safari to podporují s knihovnou SafariConverterLib v2.0.39 a prohlížečem Safari v16.4 nebo novějším.
  • Rozšíření prohlížeče AdGuard to podporuje ve verzi 5.3 nebo novější:
    • Manifest V3 (na bázi Chromium): vždy používá nativní :has() jako výchozí.
    • Manifest V2: Pokud prohlížeč nepodporuje nativní podporu :has(), použije CSS.supports() a vrátí se k ExtendedCss.
  • Všechny ostatní produkty AdGuardu to nepodporují.

Chcete-li vynutit použití implementace ExtendedCss :has() (bez ohledu na podporu), použijte explicitně značky pravidel #?# nebo #$?#, např. example.com#?#p:has(> a) nebo example.com#$?#div:has(> span) { display: none !important; }.

A protože pseudo-třída :has() nemůže být v nativní implementaci zanořena do další :has(), například div:has(p:has(a)), vždy je v rozšíření prohlížeče AdGuard považována za rozšířenou.

Kompatibilita s jinými pseudo-třídami

Synonyma :-abp-has() podporují ExtendedCss pro lepší kompatibilitu.

Upozornění na odstranění

:if() již není podporováno jako synonymum pro :has().

Syntaxe

[target]:has(selector)
  • target — nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvku
  • selector — povinný, standardní nebo rozšířený selektor CSS

Pseudo-třída :has() vybere prvky target, které se hodí do selector. Také selector může začínat kombinátorem.

Seznam selektorů lze nastavit také v selector. V tomto případě se zatím porovnávají všechny selektory v seznamu. V budoucnu bude opraveno pro <forgiving-relative-selector-list>jako argument

:has() limitations​

Použití pseudo-třídy :has() je v některých případech omezeno (2, 3):

  • zakazuje :has() uvnitř pseudo akceptující pouze složené selektory;
  • zakazuje :has() po běžných pseudoprvcích.

Nativní pseudo-třída :has() neumožňuje použití argumentů :has(), :is(), :where() uvnitř argumentu :has(), aby se nezvyšovala složitost zneplatnění :has()(případ 1). ExtendedCss však dříve takové omezení nemělo a seznamy filtrů již taková pravidla obsahují, proto jsme toto omezení do ExtendedCss nepřidali a umožnili jsme používat :has() uvnitř :has(), jak to bylo možné dříve. Chcete-li to použít, stačí vynutit použití ExtendedCss nastavením znaku pravidla #?#/#$?#.

Nativní implementace neumožňuje žádné použití :scope uvnitř argumentu :has() ([1], [2]). Přesto v seznamech filtrů některá taková pravidla existují: div:has(:scope a), která nadále podporujeme tím, že je jednoduše převedeme na div:has(> a), jak se to dělalo dříve.

Příklady

div:has(.banner) vybere všechny prvky div, které obsahují prvek se třídou banner:

<!-- HTML code -->
<div>Not selected</div>
<div>Selected
  <span class="banner">inner element</span>
</div>

div:has(> .banner) vybere všechny prvky div, které obsahují prvek třídy banner jako přímý potomek z div:

<!-- HTML code -->
<div>Not selected</div>
<div>Selected
  <p class="banner">child element</p>
</div>

div:has(+ .banner) vybere všechny prvky div předcházející prvek třídy banner, který bezprostředně následuje po div a oba jsou potomky stejného rodu:

<!-- HTML code -->
<div>Not selected</div>
<div>Selected</div>
<p class="banner">adjacent sibling</p>
<span>Not selected</span>

div:has(~ .banner) vybere všechny prvky div předcházející prvek třídy banner, který následuje div, ale ne nutně bezprostředně a oba jsou potomky stejného rodu:

<!-- HTML code -->
<div>Not selected</div>
<div>Selected</div>
<span>Not selected</span>
<p class="banner">general sibling</p>

div:has(span, .banner) vybere všechny prvky div, které obsahují prvek se třídou span a banner:

<!-- HTML code -->
<div>Not selected</div>
<div>Selected
  <span>child span</span>
  <p class="banner">child .banner</p>
</div>
Stará syntaxe

Zpětně kompatibilní syntaxe pro :has()je podporována, ale není doporučena.

Pseudo-třída :contains()​

Princip pseudo-třídy :contains() je velmi jednoduchý: umožňuje vybrat prvky, které obsahují zadaný text nebo jejichž obsah odpovídá zadanému regulárnímu výrazu. Příznaky regexp jsou podporovány.

poznámka

Pseudo-třída :contains() používá pro porovnávání vlastnost prvku textContent, nikoliv innerHTML.

Kompatibilita s jinými pseudo-třídami

Pro lepší kompatibilitu jsou podporována synonyma :-abp-contains() a :has-text().

Syntaxe

[target]:contains(match)
  • target — nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvku
  • shoda — povinný, řetězec nebo regulární výraz pro shodu prvku textContent. Příznaky regulárních výrazů jsou podporovány.

Příklady

Pro DOM:

<!-- HTML code -->
<div>Not selected</div>
<div id="match">Selected as IT contains "banner"</div>
<div>Not selected <div class="banner"></div></div>

prvek div#match lze vybrat pomocí kteréhokoli z těchto rozšířených selektorů:

! 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)
poznámka

Vybrán je pouze div s id=match, protože další prvek neobsahuje žádný text a banner je součástí kódu, nikoli textu.

Stará syntaxe

Zpětně kompatibilní syntaxe pro :contains()je podporována, ale není doporučena.

Pseudo-třída :matches-css()​

Pseudo-třída :matches-css() umožňuje porovnat prvek podle jeho aktuálních vlastností stylu. Práce pseudo-třídy je založena na použití metody Window.getComputedStyle()..

Syntaxe

[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 prvku
  • pseudo-element — volitelný, platný standardní pseudoprvek, např. before, after, first-line atd.
  • property — povinný, název vlastnosti CSS, pro kterou se má prvek zkontrolovat
  • pattern — povinný, vzor hodnoty, který používá stejnou jednoduchou shodu se zástupnými znaky jako v základních pravidlech filtrování adres URL nebo regulární výraz. 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/.

Speciální znaky uvozené a neuvozené

Všechny vzory non-regexp (,),[,] musí být neuvozeny, např. :matches-css(background-image:url(data:*)).

Vzory regexp \ by měly být uvozeny, např. :matches-css(background-image: /^url\\("data:image\\/gif;base64.+/).

Příklady

Pro DOM:

<!-- HTML code -->
<style type="text/css">
    #matched::before {
        content: "Block me"
    }
</style>
<div id="matched"></div>
<div id="not-matched"></div>

prvky div s pseudoprvkem ::before a se zadanou vlastností content lze vybrat kterýmkoli z těchto rozšířených selektorů:

! 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/)
Omezení

Vzory regexp nepodporují příznaky.

Kompatibilita

Zastaralé pseudo-třídy :matches-css-before() a :matches-css-after() se již nedoporučují, ale stále jsou podporovány kvůli lepší kompatibilitě.

Stará syntaxe

Zpětně kompatibilní syntaxe pro :matches-css() je podporována, ale nedoporučuje se.

Pseudo-třída :matches-attr()​

Pseudo-třída :matches-attr() umožňuje vybrat prvek podle jeho atributů, zejména pokud jsou náhodné.

Syntaxe

[target]:matches-attr("name"[="value"])
  • target — nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvku
  • name — povinný, jednoduchý řetězec nebo řetězec se zástupným znakem nebo regulární výraz pro shodu názvu atributu
  • value — volitelný, jednoduchý řetězec nebo řetězec se zástupným znakem nebo regulární výraz pro shodu hodnoty atributu

Uvození speciálních znaků

Pro vzory regexp " a \ by mělo být uvozeno, např. div:matches-attr(class=/[\\w]{5}/).

Příklady

div:matches-attr("ad-link") vybere prvek div#target1:

<!-- HTML code -->
<div id="target1" ad-link="1random23-banner_240x400"></div>

div:matches-attr("data-*"="adBanner") vybere prvek div#target2:

<!-- HTML code -->
<div id="target2" data-1random23="adBanner"></div>

div:matches-attr(*unit*=/^click$/) vybere prvek div#target3:

<!-- HTML code -->
<div id="target3" random123-unit094="click"></div>

*:matches-attr("/.{5,}delay$/"="/^[0-9]*$/") vybere prvek #target4:

<!-- HTML code -->
<div>
  <inner-random23 id="target4" nt4f5be90delay="1000"></inner-random23>
</div>
Omezení

Vzory regexp nepodporují příznaky.

Pseudo-třída :matches-property()​

Pseudo-třída :matches-property() umožňuje vybrat prvek podle jeho vlastností.

Syntaxe

[target]:matches-property("name"[="value"])
  • target — nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvku
  • name — 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ů

Uvození speciálních znaků

Pro vzory regexp " a \ musí být uvozeno, např. div:matches-property(prop=/[\\w]{4}/).

poznámka

Vzory regexp jsou podporovány v name pro libovolnou vlastnost v řetězci, např. prop./^unit[\\d]{4}$/.type.

Příklady

Prvek s těmito vlastnostmi:

divProperties = {
  id: 1,
  check: {
    track: true,
    unit_2random1: true,
  },
  memoizedProps: {
    key: null,
    tag: 12,
    _owner: {
      effectTag: 1,
      src: 'ad.com',
    },
  },
};

lze vybrat pomocí některého z těchto rozšířených selektorů:

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/)
Pro správce filtrů

Chcete-li zkontrolovat vlastnosti konkrétního prvku, postupujte takto:

  1. Zkontrolujte prvek stránky nebo jej vyberte na kartě Elements v nástroji DevTools prohlížeče
  2. Spusťte console.dir($0) na kartě Console
Omezení

Vzory regexp nepodporují příznaky.

Pseudo-třída :xpath()​

Pseudo-třída :xpath() umožňuje vybrat prvek vyhodnocením výrazu XPath.

Syntaxe

[target]:xpath(expression)
  • target — volitelný, standardní nebo rozšířený selektor CSS
  • expression — povinný, platný výraz XPath
:xpath() limitations​

target lze vynechat, takže je volitelný. Pro jakoukoli jinou pseudo-třídu by to znamenalo "aplikuj na všechny uzly DOM", ale v případě :xpath() to znamená jen "aplikuj na celý dokument", a takovéto použití výrazně zpomaluje výběr prvků. Proto jsou pravidla jako #?#:xpath(expression) omezena na nahlížení do znaku body. Např. pravidlo #?#:xpath(//div[@data-st-area=\'Advert\']) je analyzováno jako #?#body:xpath(//div[@data-st- area=\'Advert\']).

Rozšířené selektory s definovaným target jako libovolný selektor — *:xpath(expression) — lze stále použít, ale nedoporučuje se to, proto by měl být místo toho uveden target.

Funguje správně pouze na konci selektoru, s výjimkou pseudo-třídy :remove().

Příklady

:xpath(//*[@class="banner"]) vybere prvek div#target1:

<!-- HTML code -->
<div id="target1" class="banner"></div>

:xpath(//*[@class="inner"]/..) vybere prvek div#target2:

<!-- HTML code -->
<div id="target2">
  <div class="inner"></div>
</div>

Pseudo-třída :nth-ancestor()​

Pseudo-třída :nth-ancestor() umožňuje vyhledat nth předka vzhledem k dříve vybranému prvku.

subject:nth-ancestor(n)
  • subjectr — povinný, standardní nebo rozšířený selektor CSS
  • n — povinné, číslo >= 1 a < 256, vzdálenost k potřebnému předkovi od prvku vybraného pomocí subject

Syntaxe

subject:nth-ancestor(n)
  • subjectr — povinný, standardní nebo rozšířený selektor CSS
  • n — povinné, číslo >= 1 a < 256, vzdálenost k potřebnému předkovi od prvku vybraného pomocí subject
:nth-ancestor() limitations​

Pseudo-třída :nth-ancestor() není podporována v argumentu pseudo-třídy :not().

Příklady

Pro 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) vybere prvek div#target1, div[class="inner"]:nth-ancestor(3) vybere prvek div#target2.

Pseudo-třída :upward()​

Pseudo-třída :upward() umožňuje vyhledat předka vzhledem k dříve vybranému prvku.

Syntaxe

subject:upward(ancestor)
  • subjectr — povinný, standardní nebo rozšířený selektor CSS
  • ancestor — 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
:upward() limitations​

Pseudo-třída :nth-upward() není podporována v argumentu pseudo-třídy :not().

Příklady

Pro 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]) vybere prvek div#target1, .inner:upward(div[id]) vybere prvek div#target2, .child:upward(1) vybere prvek div#target1, .inner:upward(3) vybere prvek div#target2.

Pseudo-třída :remove() a pseudo-vlastnost remove​

Někdy je nutné odpovídající prvek odstranit namísto jeho skrytí nebo použití vlastních stylů. Chcete-li to provést, můžete použít pseudo-třídu :remove() a také pseudo-vlastnost remove.

Pseudo-třídu :remove() lze umístit pouze na konec selektoru.

Syntaxe

! pseudo-class
selector:remove()

! pseudo-property
selector { remove: true; }
  • selector — povinný, standardní nebo rozšířený selektor CSS
:remove() a remove limitations​

Pseudo-třída :remove() je omezena tak, aby správně fungovala pouze na konci selektoru.

Pro použití pseudo-třídy :remove() na libovolný prvek je třeba použít univerzální selektor *. V opačném případě může být takový rozšířený selektor považován za neplatný, např. .banner > :remove() neplatí pro odstranění jakéhokoli podřízeného prvku třídy banner, takže by měl vypadat jako .banner > *:remove().

Pokud je použita pseudo-třída :remove() nebo pseudovlastnost remove, všechny vlastnosti stylu se ignorují kromě pseudovlastnosti debug.

Příklady

div.banner:remove()
div:has(> div[ad-attr]):remove()

div:contains(advertisement) { remove: true; }
div[class]:has(> a > img) { remove: true; }
poznámka

Pravidla s pseudovlastností remove musí používat znak #$?#: $ pro syntaxi pravidel stylu CSS, ? pro syntaxi ExtendedCss.

Pseudo-třída :is()​

Pseudo-třída :is() umožňuje porovnat jakýkoli prvek, který lze vybrat kterýmkoli ze selektorů, které jí byly předány. Neplatné selektory jsou přeskočeny a pseudo-třída se vypořádá s platnými selektory bez vyhození chyby. Naše implementace nativní pseudotřídy :is().

Syntaxe

[target]:is(selectors)
  • target — nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvku
  • selektory — šetrný seznam standardních nebo rozšířených selektorů. U rozšířených selektorů jsou podporovány pouze složené selektory, nikoli komplexní.
:is() limitations​

Pravidla s pseudo-třídou :is() musí používat nativní implementaci :has(), pokud pravidla používají znak ## a pokud je to možné, tj. bez dalších rozšířených selektorů uvnitř. Chcete-li vynutit použití pravidel ExtendedCss s :is(), použijte explicitně znak #?#/#$?#.

Pokud je argument :is() pseudo-třídy selector rozšířeným selektorem, vzhledem ke způsobu, jakým je v ExtendedCss v2.0 implementována pseudo-třída :is(), není možné ji použít na horní uzel DOM, kterým je html, tj. #?#html:is(<extended-selectors>) nefunguje. Pokud tedy target není definován nebo je definován jako univerzální selektor *, je rozšířené použití pseudo-třídy omezeno na htmlpotomky, např. pravidla #?#:is(...) a #?#*:is(...) jsou analyzována jako #?#html *:is(...). Upozorňujeme, že pro standardní argument selektoru takové omezení neexistuje, tj. #?#html:is(.locked) funguje bez problémů.

Komplexní selektory s rozšířenými pseudo-třídami nejsou podporovány jako argument selector pro pseudo-třídu :is(), povoleny jsou pouze složené. Další podrobnosti naleznete v příkladech níže.

Příklady

#container *:is(.inner, .footer) vybere pouze prvek div#target1:

<!-- HTML code -->
<div id="container">
  <div data="true">
    <div>
      <div id="target1" class="inner"></div>
    </div>
  </div>
</div>

Kvůli omezením :is(*:not([class]) > .banner)' nefunguje, ale lze místo něj použít :is(*:not([class]):has(> .banner)) k výběru prvku div#target2:

<!-- HTML code -->
<span class="span">text</span>
<div id="target2">
  <p class="banner">inner paragraph</p>
</div>

Pseudo-třída :not()​

Pseudo-třída :not() umožňuje vybrat prvky, které se neshodují se selektory předávanými jako argument. Neplatné selektory argumentů nejsou povoleny a je třeba vyhodit chybu. Naše implementace pseudo-třídy :not().

Syntaxe

[target]:not(selectors)
  • target — nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvku
  • selectors — seznam standardních nebo rozšířených selektorů
:not() limitations​

Pravidla s pseudo-třídou :not() musí používat nativní implementaci :not(), pokud pravidla používají znak ## a pokud je to možné, tj. bez dalších rozšířených selektorů uvnitř. Chcete-li vynutit použití pravidel ExtendedCss s :not(), použijte explicitně znak #?#/#$?#.

Pokud je argument :not() pseudo-třídy selector rozšířeným selektorem, vzhledem ke způsobu, jakým je v ExtendedCss v2.0 implementována pseudo-třída :not(), není možné ji použít na horní uzel DOM, kterým je html, tj. #?#html:not(<extended-selectors>) nefunguje. Pokud tedy target není definován nebo je definován jako univerzální selektor *, je rozšířené použití pseudo-třídy omezeno na htmlpotomky, např. pravidla #?#:not(...) a #?#*:not(...) jsou analyzována jako #?#html *:not(...). Upozorňujeme, že pro standardní argument selektoru takové omezení neexistuje, tj. #?#html:not(.locked) funguje bez problémů.

:not() je považována za standardní pseudo-třídu CSS uvnitř argumentu pseudo-třídy :upward(), protože :upward() podporuje pouze standardní selektory.

"Up-looking" pseudotřídy, které jsou :nth-ancestor() a :upward() nejsou podporovány uvnitř argumentu selector pro pseudo-třídu :not().

Příklady

#container > *:not(h2, .text) vybere pouze prvek div#target1:

<!-- HTML code -->
<div id="container">
  <h2>Header</h2>
  <div id="target1"></div>
  <span class="text">text</span>
</div>

Pseudo-class :empty-trimmed​

The :empty-trimmed pseudo-class allows selecting elements without text content. Unlike the native CSS :empty pseudo-class, which matches elements that have no child nodes at all (no elements, no text nodes), :empty-trimmed checks textContent of the element and its descendants. It also matches elements whose text content consists only of whitespace, including non-breaking spaces such as &nbsp;.

Syntaxe

[target]:empty-trimmed
  • target — nepovinný, standardní nebo rozšířený selektor CSS může být přeskočen pro kontrolu libovolného prvku

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

This pseudo-class has no arguments.

:::

Kompatibilita

Added in ExtendedCSS v2.0.0.

Rules with the :empty-trimmed pseudo-class are supported by AdGuard Browser Extension v5.5 or later. Such rules do not work in AdGuard Content Blocker.

Příklady

div > p:empty-trimmed selects p#empty, p#spaces, p#nbsp, p#child-empty, and p#comment:

<!-- HTML code -->
<div>
  <p id="empty"></p>
  <p id="spaces">   </p>
  <p id="nbsp">&nbsp;</p>
  <p id="text">hello</p>
  <p id="child-empty"><span></span></p>
  <p id="child-text"><span>world</span></p>
  <p id="comment"><!-- hidden --></p>
  <p id="zwsp">&#x200B;</p>
</div>

div > p:not(:empty-trimmed) selects p#text, p#child-text, and p#zwsp.

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

An element like <p><span></span></p> matches :empty-trimmed (its text content is empty) but does not match native :empty (it has a child <span> node).

Elements containing only HTML comments (e.g. <!-- hidden -->) also match :empty-trimmed, because comment nodes are not reflected in textContent.

Zero-width characters such as zero-width space (\u200B) are not treated as whitespace. An element containing only zero-width characters does not match :empty-trimmed.

:::

Pseudo-class :if-not() (removed)​

Upozornění na odstranění

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, AdGuard for Mac, AdGuard for Android, and AdGuard for Linux, 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.

Kompatibilita

HTML filtering rules are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, AdGuard for Linux, 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.

The syntax with an optional value in the attributes is supported by AdGuard for Windows, AdGuard for Mac, and AdGuard for Android with CoreLibs v1.18 or later. It is also supported by AdGuard Browser Extension v5.2 or later. For the other products and previous versions value must always be specified. Otherwise, the rule will be treated as incorrect and ignored.

Syntaxe​

Syntax supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, AdGuard for Linux with CoreLibs, and AdGuard Browser Extension prior to v5.2:

     selector = [tagName] [attributes] [pseudoClasses]
   combinator = ">"
         rule = [domains] "$$" selector *(combinator selector)
      domains = [domain0, domain1[, ...[, domainN]]]
   attributes = "[" name0[ = value0] "]" "[" name1[ = value2] "]" ... "[" nameN[ = valueN] "]"
pseudoClasses = pseudoClass *pseudoClass
  pseudoClass = ":" pseudoName [ "(" pseudoArgs ")" ]
  • tagName — name of the element in lower case, for example, div or script.
  • domains — omezení domény pro dané pravidlo. Same principles as in element hiding rule syntax.
  • attributes — a list of attributes that limit the selection of elements. name — required, attribute name; value — optional (may not be specified), substring that is contained in attribute value.
  • pseudoName — the name of a pseudo-class.
  • pseudoArgs — the arguments of a function-style pseudo-class.
  • combinator — an operator that works similarly to the CSS child combinator: that is, the selector on the right of the combinator will only match an element whose direct parent matches the selector on the left of the combinator.

Syntax supported by AdGuard Browser Extension v5.3 or later:

         rule = [domains] "$$" selector
      domains = [domain0, domain1[, ...[, domainN]]]
  • selector — CSS selector, defines the element(s) to be removed from the HTML code before the page is loaded.
  • domains — omezení domény pro dané pravidlo. Same principles as in element hiding rule syntax.
Omezení

The following limitations apply to AdGuard Browser Extension v5.3 and later:

  • Pseudo-elements (e.g., ::before, ::after) are not supported, as they are not applicable in the context of HTML filtering.

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.

If the value of the attribute is omitted in the rule, then the element will be removed if it contains the specified attribute, regardless of its value. This is also the way to remove the elements whose attributes don't have any value at all.

<div some_attribute="some_value"></div>
<div some_attribute></div>
example.org$$div[some_attribute]

This rule removes all div elements with the attribute some_attribute on example.org and all its subdomains. So, the both div elements from the example above will be removed.

Speciální atributy​

In addition to checking standard HTML attributes, you can filter elements based on their inner text or script content.

:contains()​

The recommended way to filter elements by their content is using the :contains() pseudo-class. It allows you to target elements based on the actual text or script variables they contain, supporting both plain text strings and regular expressions.

Příklady:

example.com$$div:contains("Sponsored by")
example.com$$script:contains(/ad_system_\d+/)

The first rule removes any <script> tag containing the word Adverts. The second targets any <div> containing the phrase Sponsored by. The third rule utilizes a regular expression to match dynamic script patterns.

Upozornění na vyřazení

The attributes listed below are legacy features kept only for backward compatibility. They may become unsupported in future updates. Prefer using the :contains() pseudo-class where it is available.

tag-content​

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"]
Omezení

The tag-content special attribute must not appear in a selector to the left of a > combinator.

This limitation does not apply to AdGuard Browser Extension v5.3 or later.

wildcard​

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 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.

Omezení

The wildcard special attribute must not appear in a selector to the left of a > combinator.

This limitation does not apply to AdGuard Browser Extension v5.3 or later.

max-length​

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.

Omezení

The max-length special attribute must not appear in a selector to the left of a > combinator.

This limitation does not apply to AdGuard Browser Extension v5.3 or later.

min-length​

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.

Omezení

The min-length special attribute must not appear in a selector to the left of a > combinator.

This limitation does not apply to AdGuard Browser Extension v5.3 or later.

Pseudotřídy​

:contains()​

Syntaxe​
:contains(unquoted text)

nebo

:contains(/reg(ular )?ex(pression)?/)
Compatibility

:-abp-contains() and :has-text() are synonyms for :contains().

Kompatibilita

The :contains() pseudo-class is supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, AdGuard for Linux with CoreLibs v1.13 or later, and AdGuard Browser Extension v5.3 or later.

Requires that the inner HTML of the element contains the specified text or matches the specified regular expression.

Omezení

A :contains() pseudo-class must not appear in a selector to the left of a > combinator.

This limitation does not apply to AdGuard Browser Extension v5.3 or later.

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 $@$.

Ve filtru je např. pravidlo:

$$script[tag-content="banner"]

Pokud to chcete zakázat pro example.com, můžete vytvořit pravidlo výjimky:

example.com$@$script[tag-content="banner"]

Někdy může být nutné zakázat všechna pravidla omezení. Např. k provádění testů. Za tímto účelem použijte pravidlo výjimky bez zadání domény.

$@$script[tag-content="banner"]

Tento druh výjimek doporučujeme používat pouze v případě, že není možné změnit samotné pravidlo skrývání. V ostatních případech je lepší změnit původní pravidlo pomocí omezení domény.

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.

Syntaxe

rule = [domains] "#%#" script

Příklady

  • example.org#%#window.__gaq = undefined; executes the code window.__gaq = undefined; on all pages at example.org and all subdomains.

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 #@%#.

Ve filtru je např. pravidlo:

#%#window.__gaq = undefined;

Pokud to chcete zakázat pro example.com, můžete vytvořit pravidlo výjimky:

example.com#@%#window.__gaq = undefined;

Někdy může být nutné zakázat všechna pravidla omezení. Např. k provádění testů. Za tímto účelem použijte pravidlo výjimky bez zadání domény.

#@%#window.__gaq = undefined;

Tento druh výjimek doporučujeme používat pouze v případě, že není možné změnit samotné pravidlo skrývání. V ostatních případech je lepší změnit původní pravidlo pomocí omezení domény.

Omezení

JavaScript rules can only be used in trusted filters.

Kompatibilita

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.

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

AdGuard supports a lot of different scriptlets. In order to achieve cross-blocker compatibility, we also support syntax of uBO and ABP.

:::

Blocking rules syntax

[domains]#%#//scriptlet(name[, arguments])
  • domains — optional, a list of domains where the rule should be applied;
  • name — required, a name of the scriptlet from the AdGuard Scriptlets library;
  • arguments — optional, a list of string arguments (no other types of arguments are supported).

Příklady

  1. Použijte skriptlet abort-on-property-read na všech stránkách example.org a jejích subdoménách a předejte mu argument alert:

    example.org#%#//scriptlet('abort-on-property-read', 'alert')

  2. Odstraňte třídu branding ze všech prvků div[class^="inner"] na všech stránkách example.org a jejích subdoménách:

    example.org#%#//scriptlet('remove-class', 'branding', 'div[class^="inner"]')

Exception rules syntax

Exception rules can disable some scriptlets on particular domains. The syntax for exception scriptlet rules is similar to normal scriptlet rules but uses #@%# instead of #%#:

[domains]#@%#//scriptlet([name[, arguments]])
  • domains — optional, a list of domains where the rule should be applied;
  • name — optional, a name of the scriptlet to except from the applying; if not set, all scriptlets will not be applied;
  • arguments — optional, a list of string arguments to match the same blocking rule and disable it.

Příklady

  1. Zakázat specifické pravidlo skriptletu tak, aby se pouze abort-on-property-read použilo pouze na example.org a její subdomény:

    example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
    example.com#@%#//scriptlet("abort-on-property-read", "alert")

  2. Zakázat všechny skriptlety abort-on-property-read pro example.com a její subdomény:

    example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
    example.com#@%#//scriptlet("abort-on-property-read")

  3. Zakázat všechny skriptlety pro example.com a její subdomény:

    example.org,example.com#%#//scriptlet("abort-on-property-read", "alert")
    example.com#@%#//scriptlet()

  4. Použijte set-constant a set-cookie na libovolnou webovou stránku, ale vzhledem ke speciálnímu pravidlu výjimky pro skriplety bude na stránce example.org a jejích subdoménách použito pouze set-constant:

    #%#//scriptlet('set-constant', 'adList', 'emptyArr')
    #%#//scriptlet('set-cookie', 'accepted', 'true')
    example.org#@%#//scriptlet('set-cookie')

  5. Použijte adjust-setInterval na libovolnou webovou stránku a set-local-storage-item na example.com a jejích subdoménách, ale existuje také několik pravidel pro výjimky skriptletů, takže na example.com a jejích subdoménách nebudou použita žádná pravidla pro skriptlety:

    #%#//scriptlet('adjust-setInterval', 'count', '*', '0.001')
    example.com#%#//scriptlet('set-local-storage-item', 'ALLOW_COOKIES', 'false')
    example.com#@%#//scriptlet()

Learn more about how to debug scriptlets.

More information about scriptlets can be found on GitHub.

Omezení

Scriptlets rules can only be used in trusted filters.

Kompatibilita

Scriptlet rules are not supported by AdGuard Content Blocker.

The full syntax of scriptlet exception rules is supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard for Linux with CoreLibs v1.16 or later, and AdGuard Browser Extension for Chrome, Firefox, and Edge with TSUrlFilter v3.0 or later. Previous versions only support exception rules that disable specific scriptlets.

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.

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

Trusted scriptlets are not compatible with other ad blockers except AdGuard.

:::

Omezení

Trusted scriptlets rules can only be used in trusted filters.

Kompatibilita

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.

Syntaxe

rule = "[$" modifiers "]" [rule text]
modifiers = modifier0[, modifier1[, ...[, modifierN]]]
  • modifier — set of the modifiers described below.
  • rule text — a rule to be modified.

For example, [$domain=example.com,app=test_app]##selector.

In the modifiers values, the following characters must be escaped: [, ], ,, and \ (unless it is used for the escaping). Use \ to escape them. For example, an escaped bracket looks like this: \].

Modifikátor \ ProduktyAplikace CoreLibsAdGuard pro ChromiumAdGuard pro Chrome MV3AdGuard pro FirefoxAdGuard pro iOSAdGuard pro SafariBlokátor obsahu AdGuard
$app✅❌❌❌❌❌❌
$domain✅✅✅ *[1]✅✅✅❌
$path✅✅ *[2]❌✅ *[2]✅✅❌
$url✅✅ *[3]✅ *[3]✅ *[3]❌❌❌

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

  • ✅ — 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

:::

$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 hides a div with the class textad at example.com and all subdomains in requests sent from the org.example.app Android app.
  • [$app=~org.example.app1|~org.example.app2]example.com##.textad hides a div with the class textad at example.com and all subdomains in requests sent from any app except org.example.app1 and org.example.app2.
  • [$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300') applies scriptlet prevent-setInterval only in Safari browser on Mac.
  • [$app=org.example.app]#@#.textad disables all ##.textad rules for all domains while using org.example.app.
Kompatibilita

Such rules with $app modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard for Linux.

$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 — hides a div with the class textad at example.com and all subdomains.
  • [$domain=example.com|example.org]###adblock — hides an element with attribute id equals adblock at example.com, example.org and all subdomains.
  • [$domain=~example.com]##.textad — this rule hides div elements of the class textad for all domains, except example.com and its subdomains.

There are 2 ways to specify domain restrictions for non-basic rules:

  1. "klasický" způsob je zadat domény před masku pravidla a atributy: example.com##.textad;
  2. 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.

Nezákladní omezení modifikátoru $domain​

Omezení

Since the non-basic $domain works the same as the basic one, it has the same limitations.

Kompatibilita

Such rules with $domain modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, AdGuard Browser Extension for Chrome, Chrome MV3, Firefox, and Edge.

$path​

$path modifier limits the rule application area to specific locations or pages on websites.

Syntaxe

$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 hides a div with the class textad at /page.html or /page.html?<query> or /sub/page.html or /another_page.html
  • [$path=/page.html]##.textad hides a div with the class textad at /page.html or /page.html?<query> or /sub/page.html of any domain but not at /another_page.html
  • [$path=|/page.html]##.textad hides a div with the class textad at /page.html or /page.html?<query> of any domain but not at /sub/page.html
  • [$path=/page.html|]##.textad hides a div with the class textad at /page.html or /sub/page.html of any domain but not at /page.html?<query>
  • [$path=/page*.html]example.com##.textad hides a div with the class textad at /page1.html or /page2.html or any other path matching /page<...>.html of example.com
  • [$path]example.com##.textad hides a div with the class textad at the main page of example.com
  • [$domain=example.com,path=/page.html]##.textad hides a div with the class textad at page.html of example.com and all subdomains but not at another_page.html
  • [$path=/\\/(sub1|sub2)\\/page\\.html/]##.textad hides a div with the class textad at both /sub1/page.html and /sub2/page.html of any domain (please note the escaped special characters)

Path-in-domain syntax​

For cosmetic rules, you can use a simplified path-in-domain syntax by specifying the path directly in the domain part of the rule instead of using the $path modifier.

Syntaxe

   rule = [targets] "##" selector
targets = [target0, target1[, ...[, targetN]]]
 target = domain [path]

Příklady:

  • example.org/checkout##.promo-banner — hides .promo-banner elements only on checkout pages
  • news.site.com/article##.sidebar-ad — hides sidebar ads only on article pages
  • domain1.com,example.org/path##.banner — applies to all pages on domain1.com and only /path pages on example.org
  • /example\.org\/article\d+/##.ad — hides ads on article pages with numeric IDs

Path-in-domain syntax works with all types of cosmetic rules (##, #@#, #$#, $$, $@$, #%#, #@%#)

Kompatibilita

Path-in-domain syntax has been introduced in CoreLibs v1.20, Browser extension v5.4.

$path modifier limitations​

Omezení

In AdGuard Browser Extension, the non-basic $path modifier is compatible with other non-basic modifiers only when it is placed last, e.g., [$domain=/example.(com|org)/,path=/foo]##.ad. Otherwise, it may not work as expected.

Kompatibilita

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.

Syntaxe

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 hides a div with the class textad at addresses like https://example.com/content/article.html and even https://subdomain.example.com/content/article.html.
  • [$url=||example.org^]###adblock hides an element with attribute id equal to adblock at example.org and its subdomains.
  • [$url=/\[a-z\]+\\.example\\.com^/]##.textad hides div elements of the class textad for all domains matching the regular expression [a-z]+\.example\.com^.

$url modifier limitations​

Omezení

In AdGuard Browser Extension, non-basic $url modifier is not compatible with domain-specific rules and other non-basic modifiers — $domain and $path. For example, the rule [$url=/category/*]example.com###textad will not be applied.

Kompatibilita

Rules with the $url modifier are supported by AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard for Linux 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 filter maintainers to improve compatibility with different ad blockers and provide:

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

Any mistake in a preprocessor directive will lead to AdGuard failing the filter update in the same way as if the filter URL was unavailable.

Preprocessor directives can be used in the user rules or in the custom filters.

:::

Including a file​

The !#include directive allows to include contents of a specified file into the filter. It supports only files from the same origin to make sure that the filter maintainer is in control of the specified file. The included file can also contain pre-directives (even other !#include directives). Ad blockers should consider the case of recursive !#include and implement a protection mechanism.

Syntaxe

!#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

Conditions​

Filter maintainers can use conditions to supply different rules depending on the ad blocker type. A conditional directive beginning with an !#if directive must explicitly be terminated with an !#endif directive. Conditions support all basic logical operators.

There are two possible scenarios:

  1. 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á.

  2. 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.

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

Whitespaces matter. !#if is a valid directive, while !# if is not.

:::

Syntaxe

!#if (conditions)
rules_list
!#endif

nebo

!#if (conditions)
true_conditions_rules_list
!#else
false_conditions_rules_list
!#endif

kde:

  • !#if (conditions) — start of the block when conditions are true
  • conditions — just like in some popular programming languages, preprocessor conditions are based on constants declared by ad blockers. Authors of ad blockers define on their own what exact constants they declare. Possible values:
    • adguard always declared; shows maintainers that this is one of AdGuard products; should be enough in 95% of cases
    • product-specific constants for cases when you need a rule to work (or not work — then ! should be used before constant) in a specific product only:
      • adguard_app_windows — AdGuard for Windows
      • adguard_app_mac — AdGuard for Mac
      • adguard_app_cli — AdGuard for Linux
      • adguard_app_android — AdGuard for Android
      • adguard_app_ios — AdGuard for iOS
      • adguard_ext_safari — AdGuard for Safari
      • adguard_ext_chromium — AdGuard Browser Extension for Chrome (and chromium-based browsers, e.g. new Microsoft Edge)
      • adguard_ext_chromium_mv3 — AdGuard for Chrome MV3
      • adguard_ext_firefox — AdGuard Browser Extension for Firefox
      • adguard_ext_edge — AdGuard Browser Extension for Edge Legacy
      • adguard_ext_opera — AdGuard Browser Extension for Opera
      • adguard_ext_android_cb — AdGuard Content Blocker for mobile Samsung and Yandex browsers
      • ext_ublock — special case; this one is declared when a uBlock version of a filter is compiled by the FiltersRegistry
      • cap_html_filtering — products that support HTML filtering rules: AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard for Linux
  • !#else — start of the block when conditions are false
  • rules_list, true_conditions_rules_list, false_conditions_rules_list — lists of rules
  • !#endif — end of the block

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)
! for all AdGuard products except AdGuard for Safari
||example.org^$third-party
domain.com##div.ad
!#else
! for AdGuard for Safari only
||subdomain.example.org^$third-party
!#endif
Kompatibilita

The !#else directive is supported by the FiltersDownloader v1.1.20 or later.

It is already supported for filter lists compiled by the FiltersRegistry, but it still may not be supported by AdGuard products when adding a filter list with !#else as a custom one. The following products will support it in the mentioned versions or later:

  • AdGuard for Windows, Mac, and Android with CoreLibs v1.13;
  • AdGuard Browser Extension v4.2.208;
  • AdGuard for Safari v1.11.16.

Safari affinity​

Safari's limit for each content blocker is 150,000 active rules. But in AdGuard for Safari and AdGuard for iOS, we've split the rules into 6 content blockers, thus increasing the rule limit to 900,000.

Here is the composition of each content blocker:

  • AdGuard General — Ad Blocking, Language-specific
  • AdGuard Privacy — Privacy
  • AdGuard Social — Social Widgets, Annoyances
  • AdGuard Security — Security
  • AdGuard Other — Other
  • AdGuard Custom — Custom

User rules and allowlist are added to every content blocker.

pozor

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.

Syntaxe

!#safari_cb_affinity(content_blockers)
rules_list
!#safari_cb_affinity

kde:

  • !#safari_cb_affinity(content_blockers) — start of the block
  • content_blockers — comma-separated list of content blockers. Possible values:
    • general — AdGuard General content blocker
    • privacy — AdGuard Privacy content blocker
    • social — AdGuard Social content blocker
    • security — AdGuard Security content blocker
    • other — AdGuard Other content blocker
    • custom — AdGuard Custom content blocker
    • all — special keyword that means that the rules must be included into all content blockers
  • rules_list — list of rules
  • !#safari_cb_affinity — end of the block

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).

Syntaxe

!+ HINT_NAME1(PARAMS) HINT_NAME2(PARAMS)

Multiple hints can be applied.

NOT_OPTIMIZED hint​

For each filter, AdGuard compiles two versions: full and optimized. Optimized version is much more lightweight and does not contain rules which are not used at all or used rarely.

Rules usage frequency comes from the collected filter rules statistics. But filters optimization is based on more than that — some filters have specific configuration. This is how it looks like for Base filter:

"filter": AdGuard Base filter,
"percent": 30,
"minPercent": 20,
"maxPercent": 40,
"strict": true

kde:

  • filter — filter identifier
  • percent — expected optimization percent ~= (rules count in optimized filter) / (rules count in original filter) * 100
  • minPercent — lower bound of percent value
  • maxPercent — upper bound of percent value
  • strict — if percent < minPercent OR percent > maxPercent and strict mode is on then filter compilation should fail, otherwise original rules must be used

In other words, percent is the "compression level". For instance, for the Base filter it is configured to 40%. It means that optimization algorithm should strip 60% of rules.

Eventually, here are the two versions of the Base filter for AdGuard Browser Extension:

If you want to add a rule which should not be removed at optimization use the NOT_OPTIMIZED hint:

!+ NOT_OPTIMIZED
||example.org^

And this rule will not be optimized only for AdGuard for Android:

!+ NOT_OPTIMIZED PLATFORM(android)
||example.org^

PLATFORM and NOT_PLATFORM hints​

Used to specify the platforms to apply the rules. List of existing platforms and links to Base filter, for example, for each of them:

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^

NOT_VALIDATE​

This hint is used to skip validation of the rule. It is useful for rules for which support has not yet been added to the filters compiler, or for rules that are incorrectly discarded.

If you want to add a rule that should not be validated, use the NOT_VALIDATE hint:

!+ NOT_VALIDATE
||example.org^$newmodifier

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.

  • In AdGuard for Windows, you can find it in the Ad Blocker tab or via the tray menu
  • In AdGuard for Mac, it is located in Settings → Advanced → Filtering log
  • In AdGuard for Android, you can find it under Statistics → Recent activity. Recent activity can also be accessed from the Assistant
  • In AdGuard Browser Extension, it is accessible from the Miscellaneous settings tab or by right-clicking the extension icon. Only Chromium- and Firefox-based web browsers show applied element hiding rules (including CSS, ExtCSS) and JS rules and scriptlets in their Filtering logs

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

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 of the parsed selector, may differ from the input one
  • timings — list of DOM nodes matched by the selector
    • appliesCount — total number of times that the selector has been applied on the page
    • appliesTimings — time that it took to apply the selector on the page, for each of the instances that it has been applied (in milliseconds)
    • meanTiming — mean time that it took to apply the selector on the page
    • standardDeviation — standard deviation
    • timingsSum — total time it took to apply the selector on the page across all instances

Printed only for remove pseudos:

  • removed — flag to signal if elements were removed

Printed if elements are not removed:

  • matchedElements — list of DOM nodes matched by the selector
  • styleApplied — parsed rule style declaration related to the selector

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:

The following scriptlets also may be used for debug purposes:

Legenda tabulek kompatibility​

Zkratky produktů​

  1. Aplikace CoreLibs — AdGuard pro Windows, AdGuard pro Mac, AdGuard pro Android a AdGuard pro Linux
  2. AdGuard pro Chromium — Rozšíření prohlížeče AdGuard pro Chrome a další prohlížeče založené na Chromium, např. nový Microsoft Edge a Opera
  3. Adguard pro Chrome MV3 — Rozšíření prohlížeče AdGuard pro Chrome MV3
  4. Adguard pro Firefox — Rozšíření prohlížeče AdGuard pro Firefox
  5. AdGuard pro iOS — AdGuard pro iOS a AdGuard pro iOS Pro (pro mobilní prohlížeč Safari)
  6. AdGuard pro Safari — AdGuard pro desktopový prohlížeč Safari
  7. Blokátor obsahu AdGuard — blokátor obsahu pro mobilní prohlížeče Android: Samsung Internet a Yandex Browser

Zkratky kompatibility​

Zakazuje prohlížeči Google Chrome odesílat informace o verzi a modifikaci s požadavky na domény Google (včetně DoubleClick a Google Analytics).

  • ✅ — 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
  • 🧩 — may already be implemented in nightly or beta versions but is not yet supported in release versions
  • ⏳ — feature that is planned to be implemented but is not yet available in any product
  • ❌ — nepodporováno
  • 👎 — zastaralé; stále podporovano, ale v budoucnu bude odstraněno
  • 🚫 — odstraněno a již nepodporováno

:::