Как составлять свои фильтры
В этой статье мы рассказываем, как писать пользовательские правила фильтрации для использования в продуктах AdGuard. Чтобы проверить правила, скачайте приложение AdGuard
Фильтр — это набор правил фильтрации рекламного контента (баннеров, всплывающих окон и тому подобного). В AdGuard есть список базовых фильтров, созданных нашей командой. Они постоянно дорабатываются и дополняются, и, как мы надеемся, удовлетворяют требованиям большинства пользователей.
В то же время AdGuard позволяет создавать пользовательские фильтры, используя те же типы правил, что и в наших фильтрах.
Для описания синтаксиса правил мы используем Augmented BNF for Syntax Specifications, но не всегда строго следуем этой спецификации.
Синтаксис правил AdGuard изначально основан на синтаксисе правил Adblock Plus. Позже мы расширили его новыми типами правил для лучшей фильтрации рекламы. Часть информации в этой статье об общих для ABP и AdGuard типах правил взята из руководства Adblock Plus по написанию фильтров.
Комментарии
Любая строка, начинающаяся с восклицательного знака, является комментарием. В списке правил она подсвечивается серым цветом. AdGuard будет игнорировать эту строку, так что можете спокойно писать там всё, что хотите. Комментарии обычно размещаются над правилами и описывают то, что они делают.
Например:
! Это комментарий. Под этой строкой находится правило фильтрации.
||example.org^
Примеры
Блокировка по имени домена
Это правило блокирует:
http://example.org/ad1.gif
http://subdomain.example.org/ad1.gif
https://ads.example.org:8000/
Это правило не блокирует:
http://ads.example.org.us/ad1.gif
http://example.com/redirect/http://ads.example.org/
By default, such rules do not work for document requests. This means that the ||example.org^
rule will block a request made to example.org
when you try to navigate to this domain from another website, but if you type example.org
into the address bar and try to navigate to it, the website will open. To block the document request, you will need to use a rule with the $document
modifier: ||example.org^$document
.
Блокировка конкретного адреса
Это правило блокирует:
http://example.org/
Это правило не блокирует:
https://example.org/banner/img
Модификаторы базовых правил
Правила фильтрации поддерживают множество модификаторов, которые позволяют вам точно настраивать поведение правила. Вот пример правила с некоторыми простыми модификаторами.
Это правило блокирует:
http://example.com/script.js
, если этот скрипт загружен сexample.com
.
Это правило не блокирует:
https://example.org/script.js
если этот скрипт загружен сexample.org
.https://example.org/banner.png
потому что это не скрипт.
Разблокировка адреса
Это правило разблокирует:
http://example.org/banner.png
, даже если для этого адреса есть правило блокировки.
Правила блокировки с модификатором $important
приоритетнее, чем обычные правила разблокировки.
Разблокировка всего сайта
Это правило разблокирует
- Оно отключает все косметические правила на
example.com
. - Оно блокирует все запросы, отправленные с этого сайта, даже если есть правила блокировки, соответствующие этим запросам.
Косметические правила
Косметические правила применяются с использованием CSS — специального языка программирования, который понимает каждый браузер. В основном, он добавляет новый стиль CSS на сайт, цель которого — скрыть определённые элементы. Вы можете узнать больше о CSS в целом здесь.
AdGuard расширяет возможности CSS и позволяет разработчикам фильтров решать гораздо более сложные задачи. Но чтобы использовать эти расширенные правила, вы должны хорошо понимать, что такое CSS.
Популярные CSS-селекторы
Имя | CSS-селектор | Описание |
---|---|---|
Селектор ID | #banners | Выбирает все элементы, id которых равен banners . |
Селектор класса | .banners | Выбирает все элементы с атрибутом class , содержащие banners . |
Селектор атрибута | div[class="banners"] | Соответствует всем div элементам с атрибутом class , равным banners . |
Селектор вхождения подстроки | div[class^="advert1"] | Выбирает все div -элементы, атрибут class которых начинается с advert1 . |
Селектор вхождения подстроки | div[class$="banners_ads"] | Выбирает все div -элементы, атрибут class которых заканчивается на banners_ads . |
Селектор вхождения подстроки | a[href^="http://example.com/"] | Выбирает все ссылки, загруженные с домена http://example.com/ . |
Селектор атрибута | a[href="http://example.com/"] | Выбирает все ссылки, которые точное соответствуют http://example.com/ . |
Ограничения и запреты
Доверенные фильтры
Некоторые правила можно использовать только в доверенных фильтрах. В эту категорию входят:
- Списки фильтров, созданные командой AdGuard
- Пользовательские списки фильтров, помеченные как
trusted
(доверенные) - Пользовательские правила
AdGuard Content Blocker
AdGuard Content Blocker — это расширение для браузеров Samsung и Яндекс, которое можно установить из Google Play. Его не следует путать с полнофункциональным AdGuard для Android, который можно загрузить только с нашего сайта. К сожалению, возможности AdGuard Content Blocker ограничены тем, что позволяют браузеры, а они поддерживают только старый синтаксис фильтров Adblock Plus:
- Базовые правила блокировки со следующими модификаторами:
$domain
,$third-party
и модификаторы типа контента. - Базовые правила исключения со следующими модификаторами:
$document
,$elemhide
. - Базовые правила скрытия элементов без расширенной поддержки CSS.
Из-за указанных выше ограничений AdGuard Content Blocker не будет упоминаться в примечаниях по совместимости.
Базовые правила
Самые простые правила — это так называемые Базовые правила. Они используются для блокировки запросов к определённым URL-адресам. Либо, при наличии специального маркера @@ в начале правила, для разблокировки запроса. Основной принцип для этого типа правил достаточно прост: необходимо указать адрес и дополнительные параметры, которые ограничивают или расширяют область действия правила.
Базовые правила, блокирующие запросы, применяются только к подзапросам. Это означает, что они не будут блокировать загрузку страницы, если это не будет явно указано с помощью модификатора $document
.
Браузер определяет заблокированный подзапрос как выполненный с ошибкой.
Правила короче 4 символов считаются некорректными и игнорируются.
Синтаксис базовых правил
rule = ["@@"] pattern [ "$" modifiers ]
modifiers = [modifier0, modifier1[, ...[, modifierN]]]
pattern
— маска адреса. URL каждого запроса сопоставляется с этой маской. In the template, you can also use the special characters described below. Note that AdGuard truncates URLs to a length of 4096 characters in order to speed up matching and avoid issues with ridiculously long URLs.@@
— маркер, который используется для обозначения правил-исключений. С такого маркера должны начинаться правила, отключающие фильтрацию для запроса.modifiers
— параметры, используемые для «уточнения» базового правила. Некоторые параметры ограничивают область действия правила, а некоторые могут полностью изменить принцип его работы.
Специальные символы
*
— wildcard-символ. Используется, чтобы обозначить любой набор символов. Это может быть как пустая строка, так и строка любой длины.||
— указание на применение правила к указанному домену и его поддоменам. Этот специальный символ позволяет не указывать конкретный протокол и поддомен в маске адреса. То есть||
соответствует сразуhttp://*.
,https://*.
,ws://*.
иwss://*.
.^
— указатель для разделительного символа. Разделителем может быть любой символ кроме буквы, цифры и следующих символов:_
-
.
%
. Например, в адресеhttp:
//
example.com
/?
t=1
&
t2=t3
жирным выделены разделительные символы. Конец адреса также принимается в качестве разделителя.|
— указатель на начало или конец адреса. Значение зависит от расположения символов в маске. Например, правилоswf|
соответствуетhttp://example.com/annoyingflash.swf
, но неhttp://example.com/swf/index.html
.|http://example.org
соответствуетhttp://example.org
, но неhttp://domain.com?url=http://example.org
.
|
, ||
, ^
can only be used with rules that have a URL pattern. For example, ||example.com##.advert
is incorrect and will be ignored by the blocker.
Рекомендуем также прочитать шпаргалку по фильтрам от Adblock Plus, чтобы лучше понять, как строятся такие правила.
Поддержка регулярных выражений
Если вы хотите добиться ещё большей гибкости при составлении правил, вы можете использовать регулярные выражения вместо упрощённой маски со специальными символами, которая используется по умолчанию.
Такие правила работают медленнее обычных, поэтому рекомендуется избегать их или хотя бы ограничивать их область действия конкретными доменами.
Чтобы блокировщик определил, что вы хотите использовать регулярное выражение, необходимо, чтобы pattern
имел особый вид:
pattern = "/" regexp "/"
Например, правило /banner\d+/$third-party
применит регулярное выражение banner\d+
ко всем сторонним запросам. Правила-исключения с использованием регулярных выражений выглядят вот так: @@/banner\d+/
.
AdGuard для Safari и AdGuard для iOS не полностью поддерживают регулярные выражения в силу ограничений Content Blocking API (см. раздел The Regular expression format).
Поддержка wildcard для доменов верхнего уровня (TLD)
Wildcard-символы поддерживаются для TLD-доменов в шаблонах косметических правил, правил HTML-фильтрации и JavaScript.
Для косметических правил, например, example.*##.banner
, несколько доменов будут сопоставлены благодаря части .*
, т.е. example.com
, sub.example.net
, example.co.uk
и т. д.
При составлении базовых правил вы можете использовать wildcard-символ для TLD только вместе с модификатором $domain
. Например, ||*/banners/*$image,domain=example.*
.
В AdGuard для Windows, Mac и Android и в браузерном расширении AdGuard правила с подстановочным знаком .*
соответствуют любому публичному суффиксу (или eTLD). Но для AdGuard для Safari и iOS поддерживаемый список доменов верхнего уровня ограничен из-за ограничений Safari.
Правила с wildcard для доменов верхнего уровня не поддерживаются в AdGuard Content Blocker.
Примеры базовых правил
||example.com/ads/*
— простое правило, которое соответствует адресам типаhttp://example.com/ads/banner.jpg
и дажеhttp://subdomain.example.com/ads/otherbanner.jpg
.||example.org^$third-party
— правило, которое блокирует сторонние запросы к доменуexample.org
и его поддоменам.@@||example.com$document
— наиболее общее правило-исключение. Такое правило полностью отключает фильтрацию на доменеexample.com
и всех его поддоменах. Существует ряд параметров, которые также можно использовать в правилах-исключениях. Более подробно о правилах-исключениях и параметрах, которые могут в таких правилах использоваться, написано ниже.
Модификаторы базовых правил
Возможности, описанные в этом разделе, предназначены для опытных пользователей. Они расширяют возможности «Общих правил», но для их применения необходимо представлять, как работает браузер.
Вы можете изменить поведение «общего правила», используя дополнительные модификаторы. Список этих параметров располагается в конце правила за знаком доллара $
и разделяется запятыми.
Пример:
||domain.com^$popup,third-party
Базовые модификаторы
Приведённые ниже модификаторы самые простые и часто применяемые. В основном, они просто ограничивают сферу применения правила.
Модификатор \ Продукты | Приложения CoreLibs | AdGuard для Chromium | AdGuard для Firefox | AdGuard для iOS | AdGuard для Safari | AdGuard Content Blocker |
---|---|---|---|---|---|---|
$app | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$denyallow | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$domain | ✅ | ✅ | ✅ | ✅ * | ✅ * | ✅ |
$header | ✅ | ⏳ | ⏳ | ❌ | ❌ | ❌ |
$important | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$match-case | ✅ | ✅ | ✅ | ⏳ | ⏳ | ✅ |
$method | ⏳ | ✅ | ✅ | ❌ | ❌ | ❌ |
$popup | ✅ * | ✅ | ✅ | ✅ * | ✅ * | ❌ |
$third-party | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$to | ⏳ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — полностью поддерживается
- ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
- ⏳ — функция, которая реализована или планируется к реализации, но пока недоступна ни в одном продукте
- ❌ — не поддерживается
$app
Этот модификатор ограничивает действие правила до конкретного приложения (или списка приложений). Это может быть не слишком важно для Windows и Mac, но это очень важно для мобильных устройств, где некоторые правила фильтрации должны быть связаны с конкретным приложением.
- Android — используйте имя пакета приложения, например,
org.example.app
. - Windows — используйте имя процесса, например,
chrome.exe
. - Mac — используйте bundle ID или имя процесса, например,
com.google.Chrome
.
На Mac вы можете найти bundle ID или имя процесса интересующего вас приложения в деталях соответствующих запросов в Журнале фильтрации.
Примеры
||baddomain.com^$app=org.example.app
— правило для блокировки запросов, которые соответствуют указанной маске и отправлены Android-приложениемorg.example.app
.||baddomain.com^$app=org.example.app1|org.example.app2
— аналогичное правило, но оно работает как для приложенияorg.example.app1
, так и дляorg.example.app2
.
Если вы хотите, чтобы правило не применялось к определённым приложениям, начните название приложения с символа ~
.
||baddomain.com^$app=~org.example.app
— правило для блокировки запросов, соответствующих указанной маске и отправленных из любого приложения, кромеorg.example.app
.||baddomain.com^$app=~org.example.app1|~org.example.app2
— аналогично, но в исключениях два приложения:org.example.app1
иorg.example.app2
.
В модификаторе правила к приложениям нельзя добавлять подстановочный знак (), например `$app=com..music`. Правила с таким модификатором считаются недействительными.
- Только AdGuard для Windows, Mac и Android имеют технические возможности для поддержки правил с модификатором
$app
. - На Windows имя процесса нечувствительно к регистру, начиная с версий AdGuard для Windows c CoreLibs 1.12.
$denyallow
Модификатор $denyallow
позволяет избежать создания дополнительных правил, когда требуется отключить то или иное правило для определённых доменов. Модификатор $denyallow
соответствует только целевым доменам, но не доменам реферера.
Добавление этого модификатора в правило равносильно исключению доменов при помощи паттерна правила либо при помощи добавления дополнительных правил-исключений. Чтобы добавить несколько доменов в одно правило, используйте символ |
в качестве разделителя.
Примеры
Это правило:
*$script,domain=a.com|b.com,denyallow=x.com|y.com
эквивалентно этому правилу:
/^(?!.*(x.com|y.com)).*$/$script,domain=a.com|b.com
или комбинации этих трёх:
*$script,domain=a.com|b.com
@@||x.com$script,domain=a.com|b.com
@@||y.com$script,domain=a.com|b.com
- Паттерн правила не может указывать на конкретные домены, например, не может начинаться с
||
. - Домены в значении модификатора не могут иметь отрицание (например,
$denyallow=~x.com
) или wildcard домена верхнего уровня$denyallow=x.*
.
Правила, нарушающие эти ограничения, считаются недействительными.
Правила с модификатором $denyallow
не поддерживаются в AdGuard для iOS, Safari и AdGuard Content Blocker.
$domain
$domain
ограничивает область действия правила запросами, сделанными с указанных доменов и их поддоменов (как указано в HTTP-заголовке Referer).
Синтаксис
Модификатор представляет собой список из одного или нескольких выражений, разделённых символом |
, каждое из которых сопоставляется с доменом определённым образом в зависимости от его типа (см. ниже).
domains = ["~"] entry_0 ["|" ["~"] entry_1 ["|" ["~"]entry_2 ["|" ... ["|" ["~"]entry_N]]]]
entry_i = ( regular_domain / any_tld_domain / regexp )
Regular_domain
— обычное доменное имя (domain.com
). Соответствует указанному домену и его поддоменам. Сопоставляется лексикографически.any_tld_domain
— доменное имя, оканчивающееся подстановочным знаком в качестве публичного суффикса, например, дляexample.*
этоco.uk
вexample.co.uk
. Соответствует указанному домену и его поддоменам с любым публичным суффиксом. Сопоставляется лексикографически.regexp
— регулярное выражение, начинается и заканчивается символом/
. Паттерн работает так же, как и в основных URL-правилах, но символы/
,$
и,
должны быть экранированы с помощью\
.
Правила с модификатором $domain
в виде regular_domain
или any_tld_domain
поддерживаются всеми продуктами AdGuard.
Примеры
Просто $domain
:
||baddomain.com^$domain=example.org
блокирует запросы, которые соответствуют указанной маске и отправлены с доменаexample.org
или его поддоменов.||baddomain.com^$domain=example.org|example.com
— такое же правило, но срабатывать оно будет как для доменаexample.org
, так и дляexample.com
.
Если вы хотите, чтобы правило не применялось к определённым доменам, начните доменное имя со знака ~
.
$domain
и инверсия ~
:
||baddomain.com^$domain=example.org
блокирует запросы, которые соответствуют указанной маске и отправлены с доменаexample.org
или его поддоменов.||baddomain.com^$domain=example.org|example.com
— такое же правило, но срабатывать оно будет как для доменаexample.org
, так и дляexample.com
.||baddomain.com^$domain=~example.org
блокирует запросы, которые соответствуют указанной маске и отправлены с любого домена, кромеexample.org
и его поддоменов.||baddomain.com^$domain=example.org|~foo.example.org
блокирует запросы, отправленные с доменаexample.org
и всех его поддоменов, кромеfoo.example.org
.||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/
блокирует запросы, отправляемые с доменовexample.org
иexample.com
и всех их поддоменов.||baddomain.com^$domain=~a.com|~b.*|~/(^\|.+\.)c\.(com\|org)\$/
блокирует запросы, отправленные с любых доменов, кромеa.com
,b
с любым публичным суффиксом (b.com
,b.co.uk
, и т.д.),c.com
,c.org
и их поддоменов.
Модификатор $domain
, соответствующий целевому домену:
В некоторых случаях модификатор $domain
может соответствовать не только домену-рефереру, но и целевому домену. This happens when all the following conditions are met:
- The request has the
document
content type - Шаблон правила не соответствует ни одному конкретному домену
- Шаблон правила не содержит регулярных выражений
- Модификатор
$domain
содержит только исключённые домены, например,$domain=~example.org|~example.com
Для сопоставления целевого домена должен выполняться следующий предикат:
1 И ((2 И 3) ИЛИ 4)
То есть, если модификатор $domain
содержит только исключённые домены, то правилу не нужно выполнять второе и третье условия, чтобы соответствовать целевому домену $domain
.
Если какие-либо из условий выше не выполнены, но правило содержит модификатор $cookie
или $csp
, модификатор всё равно будет соответствовать целевому домену.
Если реферер соответствует правилу с $domain
, которое явно исключает домен реферера, то правило не сработает, даже если целевой домен тоже ему соответствует. Это также касается правил с модификаторами $cookie
и $csp
.
Примеры
*$cookie,domain=example.org|example.com
заблокирует cookies для всех запросов от и кexample.org
иexample.com
.*$document,domain=example.org|example.com
заблокирует все запросы от и кexample.org
иexample.com
.
В следующих примерах предполагается, что запросы отправляются от http://example.org/page
(реферер), а целевой URL — http://targetdomain.com/page
.
page$domain=example.org
сработает, так как соответствует рефереру.page$domain=targetdomain.com
сработает, так как соответствует целевому домену и удовлетворяет всем требованиям, перечисленным выше.||*page$domain=targetdomain.com
не сработает, так как шаблон||*page
может указывать на конкретные домены, например,example.page
.||*page$domain=targetdomain.com,cookie
сработает, потому что правило содержит модификатор$cookie
, несмотря на то, что шаблон||*page
может соответствовать конкретным доменам./banner\d+/$domain=targetdomain.com
не сработает, поскольку правило содержит регулярное выражение.page$domain=targetdomain.com|~example.org
не сработает, так как домен реферера явно исключён.
Ограничения модификатора $domain
Safari не поддерживает одновременно разрешённые и запрещённые домены, поэтому правила вида ||baddomain.com^$domain=example.org|~foo.example.org
не работают в AdGuard для iOS и AdGuard для Safari.
Правила с регулярными выражениями в модификаторе $domain
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 11 или выше.
В AdGuard для Windows, Mac и Android с CoreLibs 1.12 или более поздней версии вместо модификатора $domain
можно также использовать $from
.
$header
Модификатор $header
позволяет сопоставлять HTTP-ответ, имеющий определённый заголовок, с определённым значением (опционально).
Синтаксис
$header "=" h_name [":" h_value]
h_value = string / regexp
где:
h_name
(обязательно) — имя HTTP-заголовка. Сопоставляется без учёта регистра символов.h_value
(опционально) — выражение для сопоставления значения HTTP-заголовка, может быть одним из:string
— последовательность символов. Лексикографически сопоставляется со значением заголовка;regexp
— регулярное выражение, начинается и заканчивается символом/
. Паттерн работает так же, как и в основных URL-правилах, но символы/
,$
и,
должны быть экранированы с помощью\
.
The modifier part, ":" h_value
, may be omitted. В этом случае модификатор сопоставляет только имя заголовка.
Примеры
||example.com^$header=set-cookie:foo
— блокирует запрос, ответ которого содержит заголовокSet-Cookie
со значениемfoo
.||example.com^$header=set-cookie
блокирует запрос, ответ которого содержит заголовокSet-Cookie
с любым значением.@@||example.com^$header=set-cookie:/foo\, bar\$/
разблокирует запросы, ответы которых содержат заголовокSet-Cookie
со значениемfoo, bar$
.@@||example.com^$header=set-cookie
разблокирует запрос, ответ которого содержит заголовокSet-Cookie
с любым значением.
Правила с модификатором $header
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 11 или выше.
$important
The $important
modifier applied to a rule increases its priority over rules without the identical modifier. Даже относительно базовых правил-исключений.
Перейдите к приоритетам правил для более подробной информации.
Примеры
! блокирующее правило заблокирует все запросы, несмотря на правило-исключение
||example.org^$important
@@||example.org^
! если правило-исключение тоже содержит модификатор `$important`, его приоритет будет выше, и запросы не будут заблокированы
||example.org^$important
@@||example.org^$important
$match-case
Этот модификатор определяет правило, которое применяется только к адресам с совпадением регистра символов. По умолчанию регистр символов не учитывается.
Примеры
*/BannerAd.gif$match-case
— такое правило будет блокироватьhttp://example.com/BannerAd.gif
, но неhttp://example.com/bannerad.gif
.
Правила с $match-case
поддерживаются в AdGuard для iOS и AdGuard для Safari с SafariConverterLib версии 2.0.43 или выше.
Все остальные продукты уже поддерживают этот модификатор.
$method
Этот модификатор ограничивает область действия правила запросами, использующими указанный набор методов HTTP. Допускается инверсия (~). Методы должны быть указаны строчными буквами, но сопоставляются они без учёта регистра. Чтобы добавить несколько методов в одно правило, используйте в качестве разделителя вертикальную черту |
.
Примеры
||evil.com^$method=get|head
блокирует только запросы GET и HEAD кevil.com
.||evil.com^$method=~post|~put
блокирует любые запросы кevil.com
, кроме POST или PUT.@@||evil.com$method=get
разблокирует только GET-запросы кevil.com
.@@||evil.com$method=~post
разблокирует любые запросы кevil.com
, кроме POST.
Правила, где к одному методу применяется инверсия (~), а к другому нет, считаются недействительными. Так, например, правило ||evil.com^$method=get|~head
будет отклонено.
Правила с модификатором $method
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 12 или выше.
$popup
AdGuard будет пытаться закрыть браузерную вкладку с любым адресом, подходящим под правило с этим модификатором. Обратите внимание, что закрыть можно не любую вкладку.
Примеры
||domain.com^$popup
— при попытке перехода на сайтhttp://domain.com
с любой страницы в браузере, новая вкладка, в которой должен открыться указанный сайт, будет закрыта.
- Модификатор
$popup
лучше всего работает в браузерном расширении AdGuard. - В AdGuard для Safari и iOS
$popup
-правила просто заблокируют страницу. - В AdGuard для Windows, Mac и Android модификатор
$popup
в некоторых случаях может не обнаружить всплывающее окно, и оно не будет заблокировано. Модификатор$popup
применяет тип контентаdocument
со специальным флагом, который передаётся блокирующей странице. Блокирующая страница сама может провести некоторые проверки и закрыть окно, если это действительно всплывающее окно. В противном случае страница должна быть загружена. Его можно комбинировать с другими модификаторами типа request, такими как$third-party
и$important
. - Правила с модификатором
$popup
не поддерживаются в AdGuard Content Blocker.
$third-party
Ограничение на сторонние или собственные запросы. Сторонним является запрос, отправленный с другого домена. Например, запрос к домену example.org
, отправленный с домена domain.com
, является сторонним.
Чтобы считаться таковым, сторонний запрос должен соответствовать одному из следующих условий:
- Его реферер — это не поддомен целевого домена, или наоборот. Например, запрос к
subdomain.example.org
, отправленный с доменаexample.org
, не является сторонним - Значение его заголовка
Sec-Fetch-Site
—cross-site
Примеры
$third-party
:
||domain.com^$third-party
— правило применяется на всех сайтах, кромеdomain.com
и его поддоменов. Пример стороннего запроса:http://example.org/banner.jpg
.
Если указан модификатор $~third-party
, то правило применяется только к запросам, которые не являются сторонними. То есть эти запросы отправлены с того же домена.
$~third-party
:
||domain.com$~third-party
— this rule is applied exclusively todomain.com
. Example of a non third-party request:http://domain.com/icon.ico
.
Вы можете использовать более короткое название (псевдоним) вместо полного названия модификатора: $3p
.
$to
$to
ограничивает область действия правила запросами, сделанными на указанные домены и их поддомены. Чтобы добавить несколько доменов в одно правило, используйте символ |
в качестве разделителя.
Примеры
/ads$to=evil.com|evil.org
блокирует любые запросы кevil.com
илиevil.org
и их поддоменам с путём, соответствующим/ads
./ads$to=~not.evil.com|evil.com
блокирует любые запросы кevil.com
и его поддоменам с путём, совпадающим с/ads
, за исключением запросов кnot.evil.com
и его поддоменам./ads$to=~good.com|~good.org
блокирует любые запросы с путём, соответствующим/ads
, за исключением запросов кgood.com
илиgood.org
и их поддоменам.
$denyallow
нельзя использовать вместе с $to
. Его можно выразить инвертированным $to
: $denyallow=a.com|b.com
эквивалентно $to=~a.com|~b.com
.
Правила с модификатором $to
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.12 или выше и в Браузерном расширении AdGuard с TSUrlFilter версии 2.1.3 или выше.
Модификаторы типа контента
Существует целый набор модификаторов, которые ограничивают область применения правила только определённым типом контента. Эти модификаторы можно комбинировать, чтобы, например, распространить правило одновременно и на картинки, и на скрипты.
Существует большая разница в том, как AdGuard определяет тип контента на разных платформах. В случае Браузерного расширения AdGuard, тип контента для каждого запроса предоставляется самим браузером. В случае AdGuard для Windows, Mac и Android для определения используется следующая методика: сначала мы пытаемся определить тип запроса по заголовку запроса Sec-Fetch-Dest
или по расширению имени файла. Если запрос не заблокирован на этом этапе, то тип запроса уточняется с использованием заголовка Content-Type
в начале ответа, полученного от сервера.
Примеры модификаторов типа контента
||example.org^$image
— соответствует всем картинкам с доменаexample.org
.||example.org^$script,stylesheet
— соответствует всем скриптам и стилям с доменаexample.org
.||example.org^$~image,~script,~stylesheet
— соответствует всем запросам к доменуexample.org
, кроме картинок, скриптов и стилей.
Модификатор \ Продукты | Приложения CoreLibs | AdGuard для Chromium | AdGuard для Firefox | AdGuard для iOS | AdGuard для Safari | AdGuard Content Blocker |
---|---|---|---|---|---|---|
$document | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$font | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$image | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$media | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$object | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$other | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$ping | ✅ * | ✅ | ✅ | ❌ | ❌ | ✅ |
$script | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$stylesheet | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$subdocument | ✅ * | ✅ | ✅ | ✅ | ✅ | ❌ |
$websocket | ✅ | ✅ | ✅ | ✅ * | ✅ * | ✅ |
$xmlhttprequest | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$webrtc 🚫 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
$object-subrequest 🚫 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
- ✅ — полностью поддерживается
- ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
- ❌ — не поддерживается
- 🚫 — удалён и больше не поддерживается
$document
Правило соответствует запросам основного документа страницы, т.е. HTML-документа, который загружается во вкладке браузера. Оно не подходит для iframe, для них существует модификатор $subdocument
.
По умолчанию AdGuard не блокирует запросы, которые загружаются во вкладке браузера (например, «обход основного фрейма»). Идея заключается в том, чтобы не препятствовать загрузке страниц, поскольку пользователь явно указал, что он хочет, чтобы эта страница была загружена. Однако, если использовать модификатор $document
, то AdGuard не будет использовать эту логику и предотвратит загрузку страницы. Другими словами, заблокирует её.
Если этот модификатор используется в правиле-исключении (@@
), то оно полностью отключает блокировку на соответствующих страницах. Это равносильно одновременному использованию модификаторов $elemhide
, $content
, $urlblock
, $jsinject
и $extension
.
Примеры
@@||example.com^$document
полностью отключает фильтрацию на всех страницах сайтаexample.com
и всех его поддоменах.||example.com^$document
блокирует запрос HTML-документа наexample.com
с помощью блокирующей страницы.||example.com^$document,redirect=noopframe
перенаправляет запрос HTML-документа сайтаexample.com
на пустой HTML-документ.||example.com^$document,removeparam=test
удаляет параметрtest
из запроса HTML-документа кexample.com
.||example.com^$document,replace=/test1/test2/
заменяетtest1
наtest2
в запросе HTML-документа кexample.com
.
Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $doc
.
$font
Правило соответствует запросам к файлам шрифтов (например, файлам с расширением .woff
).
$image
Правило соответствует запросам к изображениям.
$media
Правило соответствует запросам к медиафайлам — музыке и видео, например файлам .mp4
.
$object
Правило соответствует ресурсам плагинов браузера, например, Java или Flash.
$other
Правило применяется к запросам, тип которых не был определён или не соответствует перечисленным выше типам.
$ping
Правило соответствует запросам, вызванным атрибутом navigator.sendBeacon()
или ping
в ссылках.
AdGuard для Windows, Mac и Android часто не может точно определить navigator.sendBeacon()
. Не рекомендуется использовать $ping
в фильтрах, которые должны использоваться продуктами AdGuard на базе CoreLibs.
Правила с модификатором $ping
не поддерживаются в AdGuard для Safari и iOS.
$script
Правило соответствет запросам к файлам скриптов, например, javascript или vbscript.
$stylesheet
Правило соответствует запросам к файлам CSS-стилей.
Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $css
.
$subdocument
Правило соответствует запросам к встроенным страницам — HTML-теги frame
и iframe
.
Примеры
||example.com^$subdocument
блокирует запросы встроенных страниц (frame
иiframe
) кexample.com
и всем его поддоменам.||example.com^$subdocument,domain=domain.com
блокирует запросы встроенных страниц (frame
иiframe
) кexample.com
и его поддоменам сdomain.com
и всех его поддоменов.
Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $frame
.
В AdGuard для Windows, Mac и Android вложенные документы обнаруживаются по заголовку Sec-Fetch-Dest, если он есть. В противном случае некоторые основные страницы могут рассматриваться как поддокументы.
Правила с модификатором $subdocument
не поддерживаются в AdGuard Content Blocker.
$websocket
Правило применяется только к соединениям WebSocket.
Модификатор $websocket
поддерживается во всех продуктах AdGuard, кроме AdGuard Content Blocker. Что касается AdGuard для Safari и AdGuard для iOS, то они поддерживаются на устройствах с macOS Monterey (версия 12) и iOS 16 и выше.
$xmlhttprequest
Правило применяется только к ajax-запросам (запросам, отправленным через объект JavaScript XMLHttpRequest
).
Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $xhr
.
AdGuard для Windows, Mac и Android часто не может точно определить этот тип модификатора и иногда определяет его как $other
или $script
. Они могут надёжно обнаружить этот тип контента только при фильтрации современных браузеров, поддерживающих Fetch metadata request headers.
$object-subrequest
(удалён)
Модификатор $object-subrequest
удалён и больше не поддерживается. Правила с ним не работают. Правило соответствует запросам плагинов браузера (обычно это Flash).
$webrtc
(удалён)
Этот модификатор удалён и больше не поддерживается. Правила с ним не работают. Если вы хотите блокировать WebRTC, рассмотрите возможность использования скриптлета nowebrtc
.
Правило применяется только к WebRTC-соединениям.
Примеры
||example.com^$webrtc,domain=example.org
blocks webRTC connections toexample.com
fromexample.org
.@@*$webrtc,domain=example.org
— это правило отключает оболочку RTC дляexample.org
.
Модификаторы правил исключений
Правила исключений отключают действие других базовых правил для адресов, которым они соответствуют. Они начинаются с маркера @@
. Для таких правил работают все базовые модификаторы, перечисленные выше. Также добавляется несколько специальных модификаторов, которые будут описаны ниже.
Рекомендуем также прочитать шпаргалку по фильтрам от Adblock Plus, чтобы лучше понять, как строятся правила исключений.
Модификатор \ Продукты | Приложения CoreLibs | AdGuard для Chromium | AdGuard для Firefox | AdGuard для iOS | AdGuard для Safari | AdGuard Content Blocker |
---|---|---|---|---|---|---|
$content | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
$elemhide | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$extension | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$jsinject | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$stealth | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$urlblock | ✅ | ✅ | ✅ | ✅ * | ✅ * | ❌ |
$genericblock | ✅ | ✅ | ✅ | ✅ * | ✅ * | ❌ |
$generichide | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$specifichide | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — полностью поддерживается
- ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
- ❌ — не поддерживается
$content
Отключает HTML-фильтрацию, правила $hls
, $replace
и $jsonprune
на страницах, соответствующих правилу.
Примеры
@@||example.com^$content
отключает все правила модификации контента на страницахexample.com
и всех его поддоменах.
$elemhide
Отключает любые косметические правила на страницах, подходящих под правило.
Примеры
@@||example.com^$elemhide
отменяет все косметические правила для страниц на сайтеexample.com
и на всех его поддоменах.
Вы можете использовать более короткое название (псевдоним) вместо полного названия модификатора: $ehide
.
$extension
Отключает пользовательские скрипты — определённые или все для данного домена.
Синтаксис
$extension[="userscript_name1"[|"userscript_name2"[|"userscript_name3"[...]]]]
userscript_name(i)
обозначает конкретное имя пользовательского скрипта, которое должно быть отключено модификатором. The modifier can contain any number of userscript names or none. В последнем случае модификатор отключает все пользовательские скрипты.
Имена пользовательских скриптов обычно содержат пробелы или другие специальные символы, поэтому необходимо заключать их в кавычки. Поддерживаются как одинарные ('
), так и двойные ("
) ASCII-кавычки. Несколько имён пользовательских скриптов должны быть разделены вертикальной чертой (|
). Однако если имя пользовательского скрипта представляет собой одно слово без специальных символов, то его можно использовать без кавычек.
Вы также можете исключить пользовательский скрипт из фильтрации, добавив перед ним символ ~
. В этом случае пользовательский скрипт не будет отключён модификатором.
$extension=~"userscript name"
Исключая пользовательский скрипт из фильтрации, обязательно выносите символ ~
за кавычки.
Если имя пользовательского скрипта содержит кавычки ("
), запятые (,
) или вертикальную черту (|
), они должны быть экранированы обратной косой чертой (\
).
$extension="userscript name\, with \"quote\""
Примеры
@@||example.com^$extension="AdGuard Assistant"
отключает пользовательский скриптAdGuard Assistant
на сайтеexample.com
.@@||example.com^$extension=MyUserscript
отключает пользовательский скриптMyUserscript
на сайтеexample.com
.@@||example.com^$extension='AdGuard Assistant'|'Popup Blocker'
отключает оба пользовательских скриптаAdGuard Assistant
иPopup Blocker
на сайтеexample.com
.@@||example.com^$extension=~"AdGuard Assistant"
отключает все пользовательские скрипты на сайтеexample.com
, кромеAdGuard Assistant
.@@||example.com^$extension=~"AdGuard Assistant"|~"Popup Blocker"
отключает все пользовательские скрипты на сайтеexample.com
, кромеAdGuard Assistant
иPopup Blocker
.@@||example.com^$extension
— пользовательские скрипты не будут работать на страницах сайтаexample.com
.@@||example.com^$extension="AdGuard \"Assistant\""
отключает пользовательский скриптAdGuard "Assistant"
на сайтеexample.com
.
- Только AdGuard для Windows, Mac и Android имеют технические возможности для поддержки правил с модификатором
$extension
. - Модификатор
$extension
с названием пользовательского скрипта поддерживается в AdGuard для Windows, Mac и Android c CoreLibs версии 1.13 или выше.
Правила с модификатором $extension
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.13 или выше.
$jsinject
Запрещает добавление javascript-кода на страницу. О скриптлетах и javascript-правилах речь пойдёт ниже.
Примеры
@@||example.com^$jsinject
отменяет все javascript-правила для страниц на сайтеexample.com
и на всех его поддоменах.
$stealth
Отключает модуль «Антитрекинг» для всех страниц и запросов, подходящих под это правило.
Синтаксис
$stealth [= opt1 [| opt2 [| opt3 [...]]]]
Здесь opt(i)
обозначают опции «Антитрекинг», отключаемые правилами. The modifier can contain any number of options (see below) or none. В последнем случае модификатор отключает модуль «Антитрекинг» полностью.
Список доступных опций модификатора:
searchqueries
отключает опцию Скрывать поисковые запросыdonottrack
отключает опцию Просить сайты не отслеживать вас3p-cookie
отключает Самоуничтожение сторонних куки1p-cookie
отключает Самоуничтожение куки сайта3p-cache
отключает опцию Блокировать заголовки ETag и If-None-Match3p-auth
отключает опцию Блокировать сторонний заголовок авторизацииwebrtc
отключает опцию Блокировать WebRTCpush
отключает опцию Блокировать Push APIlocation
отключает опцию Блокировать Location APIflash
отключает опцию Блокировать Flashjava
отключает опцию Блокировать Javareferrer
отключает опцию Скрывать Referer от третьих лицuseragent
отключает опцию Скрывать User-Agentip
отключает опцию Скрывать IP-адресxclientdata
отключает опцию Удалять заголовок X-Client-Datadpi
отключает опцию Защищать от DPI
Примеры
@@||example.com^$stealth
полностью отключает модуль «Антитрекинг» для запросов кexample.com
и поддоменам, кроме блокировки куки и скрытия параметров отслеживания (см.ниже).@@||domain.com^$script,stealth,domain=example.com
отключает модуль «Антитрекинг» только для script-запросов кdomain.com
(и поддоменам) наexample.com
и всех его поддоменах.@@||example.com^$stealth=3p-cookie|dpi
отключает блокировку сторонних куки-файлов и меры защиты от DPI для запросов кexample.com
.
Блокировка куки и скрытие параметров отслеживания достигается использованием правил с модификаторами $cookie
и $removeparam
. Правила-исключения только с модификатором $stealth
не дадут желаемого результата. Если вы хотите полностью отключить все функции Антитрекинга для определённого домена, нужно включить в правило все три модификатора: @@||example.org^$stealth,removeparam,cookie
- Modifier options must be lowercase, i.e.
$stealth=DPI
will be rejected. - Параметры модификатора не могут отрицаться, т.е.
$stealth=~3p-cookie
будет отклонён.
- Антитрекинг доступен в AdGuard для Windows, Mac и Android и в Браузерном расширении AdGuard. Все остальные продукты будут игнорировать правила с модификатором
$stealth
. - Правила с модификатором
$stealth
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.10 или выше.
$urlblock
Отключает все правила $cookie
и блокировку всех запросов со страниц, соответствующих правилу.
Примеры
@@||example.com^$urlblock
— любые запросы, отправленные со страниц сайтаexample.com
и всех его поддоменов, не будут блокироваться.
В AdGuard для iOS и AdGuard для Safari правила $urlblock
работают как исключение $document — они разблокируют всё.
Правила с модификатором $urlblock
не поддерживаются в AdGuard Content Blocker.
Generic-правила
Перед тем, как перейти к описанию следующих модификаторов, необходимо ввести определение generic-правил. Правило относится к generic-правилам, если его действие не ограничено конкретными доменами. Также поддерживается wildcard-символ *
.
Например, это generic-правила:
###banner
*###banner
#@#.adsblock
*#@#.adsblock
~domain.com###banner
||domain.com^
||domain.com^$domain=~example.com
А это уже не generic-правила:
domain.com###banner
||domain.com^$domain=example.com
$genericblock
Отключает все базовые правила generic на страницах, подходящих под правило-исключение.
Примеры
@@||example.com^$genericblock
отключает базовые правила generic на любых страницахexample.com
и всех поддоменах.
В AdGuard для iOS и AdGuard для Safari правила $genericblock
работают как исключение $document — они разблокируют всё.
Правила с модификатором $genericblock
не поддерживаются в AdGuard Content Blocker.
$generichide
Отключает все косметические правила generic на страницах, соответствующих правилу-исключению.
Примеры
@@||example.com^$generichide
отключает косметические правила generic на страницах сайтаexample.com
и всех его поддоменах.
Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $ghide
.
specifichide
Отключает все specific-правила скрытия элементов и CSS-правила, но не отключает general-правила. Имеет эффект, противоположный $generichide
.
Примеры
@@||example.org^$specifichide
отключаетexample.org##.banner
, но не##.banner
.
Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $shide
.
Все косметические правила, а не только specific, можно отключить модификатором $elemhide
.
Правила с модификатором $specifichide
не поддерживаются в AdGuard для iOS, AdGuard для Safari и AdGuard Content Blocker.
Расширенные возможности
Модификаторы, описанные в этом разделе, полностью меняют поведение базовых правил.
Модификатор \ Продукты | Приложения CoreLibs | AdGuard для Chromium | AdGuard для Firefox | AdGuard для iOS | AdGuard для Safari | AdGuard Content Blocker |
---|---|---|---|---|---|---|
$all | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$badfilter | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$cookie | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$csp | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$hls | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$inline-font | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$inline-script | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$jsonprune | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$network | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$permissions | ✅ | ⏳ | ⏳ | ❌ | ❌ | ❌ |
$redirect | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$redirect-rule | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$referrerpolicy | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$removeheader | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$removeparam | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$replace | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
noop | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$empty 👎 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
$mp4 👎 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
- ✅ — полностью поддерживается
- ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
- ❌ — не поддерживается
- 👎 — устарел; всё ещё поддерживается, но в будущем будет удалён
$all
Модификатор $all
состоит из всех модификаторов content-type и $popup
. Например, правило ||example.org^$all
конвертируется в правило:
||example.org^$document,subdocument,font,image,media,object,other,ping,script,stylesheet,websocket,xmlhttprequest,popup
Этот модификатор нельзя использовать как исключение с маркером @@
.
Правила с модификатором $all
не поддерживаются в AdGuard Content Blocker.
$badfilter
Правила, содержащие модификатор $badfilter
, отключают другие базовые правила, на которые они ссылаются. Это означает, что текст отключённого правила должен соответствовать тексту $badfilter
-правила (за исключением самого модификатора $badfilter
).
Примеры
||example.com$badfilter
отключает||example.com
||example.com$image,badfilter
отключает||example.com$image
@@||example.com$badfilter
отключает@@||example.com
||example.com$domain=domain.com,badfilter
отключает||example.com$domain=domain.com
Правила с модификатором $badfilter
могут отключать другие базовые правила для определённых доменов, если они соответствуют следующим условиям:
- В правиле есть модификатор
$domain
- В модификаторе
$domain
нет отрицания домена~
В этом случае, правило с $badfilter
отключит соответствующее базовое правило для доменов, указанных как в правиле с $badfilter
, так и в базовом правиле. Обратите внимание, что логика wildcard для доменов верхнего уровня (TLD) здесь также применима.
Примеры
/some$domain=example.com|example.org|example.io
отключено дляexample.com
правилом/some$domain=example.com,badfilter
/some$domain=example.com|example.org|example.io
отключено дляexample.com
иexample.org
правилом/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org
и/some$domain=example.io
полностью отключены правилом/some$domain=example.com|example.org|example.io,badfilter
/some$domain=example.com|example.org|example.io
полностью отключено правилом/some$domain=example.*,badfilter
/some$domain=example.*
отключено дляexample.com
иexample.org
правилом/some$domain=example.com|example.org,badfilter
/some$domain=example.com|example.org|example.io
НЕ отключено дляexample.com
правилом/some$domain=example.com|~example.org,badfilter
, поскольку значение модификатора$domain
содержит отрицание домена
Правила с модификатором $badfilter
не поддерживаются в AdGuard Content Blocker.
$cookie
Модификатор $cookie
полностью меняет поведение правила. Вместо того, чтобы блокировать запрос, этот модификатор позволяет AdGuard блокировать или изменять заголовки Cookie
или Set-Cookie
.
Несколько правил, соответствующих одному запросу
В случае, когда несколько правил $cookie
соответствуют одному запросу, мы применим каждое из них по очереди.
Синтаксис
$cookie [= name[; maxAge = seconds [; sameSite = strategy ]]]
где:
name
— опционально, строка или регулярное выражение для сопоставления с именем куки.seconds
— количество секунд, на которое сместится истечение срока действия куки.strategy
— строка для стратегии Same-Site для использования куки.
Например,
||example.org^$cookie=NAME;maxAge=3600;sameSite=lax
каждый раз, когда AdGuard встречает куки с именем NAME
в запросе к example.org
, он будет делать следующее:
- Установит дату истечения срока хранения на текущее время плюс
3600
секунд - Позволяет куки использовать стратегию Same-Site.
Экранирование специальных символов
Если для сопоставления используется регулярное выражение name
, необходимо экранировать два символа: запятую ,
и знак доллара $
. Используйте для этого обратный слеш \
. Например, экранированная запятая будет выглядеть так: \,
.
Примеры
||example.org^$cookie
блокирует все куки, установленныеexample.org
; это эквивалентно установкеmaxAge=0
$cookie=__cfduid
блокирует куки CloudFlare везде$cookie=/__utm[a-z]/
блокирует куки Google Analytics везде||facebook.com^$third-party,cookie=c_user
не позволяет Facebook отслеживать вас, даже если вы вошли в систему
Существует два способа деактивации правил $cookie
: основной предполагает использование исключения с @@
— @@||example.org^$cookie
. Альтернативный метод использует исключение $urlblock
(также входящее в псевдоним исключения $document
— $elemhide,jsinject,content,urlblock,extension
). Вот как это работает:
@@||example.org^$cookie
разблокирует все куки-файлы, установленныеexample.org
@@||example.org^$urlblock
разблокирует все файлы куки, установленныеexample.org
, и отключает блокировку всех запросов, отправленных сexample.org
@@||example.org^$cookie=concept
разблокирует один куки-файл с именемconcept
@@||example.org^$cookie=/^_ga_/
разблокирует все куки, соответствующие регулярному выражению
$cookie
rules support three types of modifiers: $domain
, $~domain
, $important
, $third-party
, and $~third-party
.
Правила с модификатором $cookie
не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.
$csp
Этот модификатор полностью меняет поведение страницы. Когда он применяется, правило не блокирует запрос. Вместо этого будут изменены заголовки ответа.
Чтобы использовать правила этого типа, необходимо базовое понимание слоя безопасности Content Security Policy.
Для запросов, подходящих под $csp
-правило, мы усилим политику безопасности ответа, добавив дополнительную политику, равнозначную содержимому модификатора $csp
. Правила $csp
применяются независимо от правил любого другого типа. Only document-level exceptions can influence it (see the examples section), but no other basic rules.
Несколько правил, соответствующих одному запросу
В случае, когда несколько правил $csp
соответствуют одному запросу, мы применим каждое из них.
Синтаксис
Синтаксис значений $csp
похож на синтаксис заголовков Политики Безопасности Контента.
Значение $csp
может быть пустым в случае правил-исключений. См. примеры ниже.
Примеры
||example.org^$csp=frame-src 'none'
запрещает все фреймы на example.org и его поддоменах.@@||example.org/page/*$csp=frame-src 'none'
отключает все правила с модификатором$csp
, в точности соответствующимframe-src 'none'
на всех страницах, подходящих под паттерн правила. Например, правило выше.@@||example.org/page/*$csp
отключает все$csp
-правила на всех страницах, подходящих под паттерн правила.||example.org^$csp=script-src 'self' 'unsafe-eval' http: https:
отключает инлайн-скрипты на всех страницах, подходящих под паттерн правила.@@||example.org^$document
или@@||example.org^$urlblock
отключает все$csp
-правила на всех страницах, подходящих под паттерн правила.
- Некоторые символы запрещены в значении
$csp
:,
,$
. $csp
-правила поддерживают ограниченный список модификаторов:$domain
,$important
,$subdocument
.- Правила с директивами
report-*
считаются некорректными.
Правила с модификатором $csp
не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.
$hls
Правила $hls
модифицируют ответ на соответствующий правилу запрос. Они предназначены для удаления сегментов из HLS-плейлистов (RFC 8216).
Слово segment в документации означает Media Segment или playlist (как часть Master Playlist): с точки зрения правил $hls
, Master Playlist и Media Playlist неразличимы.
Синтаксис
||example.org^$hls=urlpattern
удаляет сегменты, URL которых соответствует паттернуurlpattern
. Паттерн работает так же, как в базовых URL-правилах, однако символы/
,$
и,
в составеurlpattern
необходимо экранировать с помощью\
.||example.org^$hls=/regexp/options
удаляет сегменты, в которых URL-адрес или один из тегов (для определённых параметров, если они есть) соответствуют регулярному выражениюregexp
. Доступные значенияoptions
:t
— вместо URL-адреса сегмента проверять каждый тег сегмента на соответствие регулярному выражению. Сегмент с соответствующим тегом будет удалён;i
— сделать регулярное выражение нечувствительным к регистру символов.
Символы /
, $
и ,
должны быть экранированы с помощью \
внутри regexp
.
Исключения
Базовые URL правила-исключения не отключают правила с модификатором $hls
. Отключить их можно следующим образом:
@@||example.org^$hls
отключает все правила$hls
для ответов от URL-адресов, соответствующих||example.org^ URL
.@@||example.org^$hls=text
отключает все правила$hls
, у которых значение модификатора$hls
равноtext
, для ответов с URL-адресов, соответствующих||example.org^ URL
.
$hls
также можно отключить с помощью правил-исключений с модификаторами $document
, $content
и $urlblock
.
Если несколько правил $hls
соответствуют одному и тому же запросу, их эффект суммируется.
Примеры
||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads
удаляет все сегменты с соответствующим URL.||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i
делает почти то же самое, но с помощью регулярного выражения вместо URL-паттерна.||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
удаляет все сегменты с соответствующим тегом.
О формате HLS-плейлистов
Из спецификации следует:
- HLS-плейлист — это набор текстовых строк
- Можно использовать пустую строку, комментарий (начинается с
#
), тег (тоже начинается с#
, распознаётся по содержанию) или URL - Строка с URL называется сегментом
- Тег может относиться к одному сегменту, т.е. к первой строке с URL, следующей после данного тега, ко всем последующим сегментам (пока не встретится тег с тем же названием) или ко всему плейлисту
Замечания, касающиеся правил $hls
:
- Когда сегмент удаляется, все теги, относящиеся только к нему, тоже удаляются
- Теги, относящиеся к нескольким сегментам, удаляются, если все эти сегменты были удалены
- Поскольку различные типы тегов невозможно распознать по синтаксису, мы распознаем все теги, указанные в RFC, плюс некоторые нестандартные теги, которые встречались нам в полевых условиях. Любые строки, начинающиеся с
#
и не распознанные как тег, пропускаются без модификации и не сопоставляются с правилами - Tags will not be matched if they apply to the entire playlist, and
$hls
rrules cannot be used to remove them, as these rule types are intended for segment removals. Если вы знаете, что делаете, вы можете использовать правила$replace
для удаления или перезаписи только одного тега из плейлиста
Пример работы правил:
Исходный ответ
#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
Применённые правила
||example.org^$hls=preroll
||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
Модифицированный ответ
#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
- Правила
$hls
разрешены только в доверенных фильтрах. - Правила
$hls
совместимы с модификаторами$domain
,$third-party
,$app
,$important
,$match-case
и$xmlhttprequest
. - Правила
$hls
применимы только к HLS-плейлистам, т. е. к тексту в кодировке UTF-8, начинающемуся со строки#EXTM3U
. Никакие другие ответы не будут модифицированы этими правилами. $hls
rules do not apply if the size of the original response is more than 10 MB.
Правила с модификатором $hls
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.10 или выше.
$inline-script
Модификатор $inline-script
предназначен для блокировки встроенного в страницу кода JavaScript с использованием политики безопасности контента (CSP). Он повышает безопасность, не позволяя загружать встроенную рекламу или потенциально вредоносные скрипты. Правило ||example.org^$inline-script
конвертируется в правило синтаксиса CSP:
||example.org^$csp=script-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
$inline-font
Модификатор $inline-font
предназначен для блокировки встроенных в страницу шрифтов с использованием политики безопасности контента (CSP). Он повышает безопасность, не позволяя загружать встроенные шрифты, которые могут использоваться для сбора данных и фингерпринтинга. Правило ||example.org^$inline-font
конвертируется в правило синтаксиса CSP:
||example.org^$csp=font-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
$jsonprune
Правила $jsonprune
модифицируют ответ на соответствующий запрос, удаляя JSON-элементы, которые соответствуют модифицированному выражению JSONPath. Эти правила не изменяют ответы, которые не являются действительными JSON-документами.
В AdGuard для Windows, Mac и Android с CoreLibs версии 1.11 или выше $jsonprune
также поддерживается модификация JSONP-документов (padded JSON).
Синтаксис
||example.org^$jsonprune=expression
удаляет из ответа элементы, соответствующие изменённому JSONPath-выражениюexpression
.
Из-за особенностей работы парсинга правил символы $
и ,
внутри expression
должны экранироваться символом \
.
Модифицированный синтаксис JSONPath имеет следующие отличия от оригинального:
- Выражения на сценарном языке (script expressions) не поддерживаются
- Поддерживаемые предикаты (filter expressions):
?(has <key>)
— верно, если текущий объект содержит указанный ключ?(key-eq <key> <value>)
— верно, если текущий объект содержит указанный ключ и его значение равно указанному?(key-substr <key> <value>)
— верно, если указанное значение является подстрокой значения ключа текущего объекта
- Пробелы вне двойных или одинарных кавычек игнорируются
- Можно использовать строки как с двойными, так и с одинарными кавычками
- Выражения, оканчивающиеся на
..
, не поддерживаются - Разрешено указывать несколько срезов массива (array slices) в квадратных скобках
Существуют различные онлайн-инструменты, которые делают работу с выражениями JSONPath удобнее:
https://www.site24x7.com/tools/jsonpath-finder-validator.html https://jsonpathfinder.com/ https://jsonpath.com/
Обратите внимание, что различные имплементации JSONPath обладают уникальными особенностями и могут быть несовместимы друг с другом.
Исключения
Базовые URL правила-исключения не отключают правила с модификатором $jsonprune
. Отключить их можно следующим образом:
@@||example.org^$jsonprune
отключает все правила$jsonprune
для ответов от URL-адресов, соответствующих||example.org^
.@@||example.org^$jsonprune=text
отключает все правила$jsonprune
, у которых значение модификатораjsonprune
равноtext
, для ответов с URL-адресов, соответствующих||example.org^
.
$jsonprune
также можно отключить с помощью правил-исключений с модификаторами $document
, $content
и $urlblock
.
Когда одному и тому же запросу соответствует несколько правил с модификатором $jsonprune
, они сортируются в лексикографическом порядке: первое правило применяется к исходному ответу, а каждое из оставшихся правил применяется к результату применения предыдущего.
Примеры
||example.org^$jsonprune=\$..[one\, "two three"]
удаляет все вхождения ключей one и two three в любом месте JSON-документа.
До
{
"one": 1,
"two": {
"two three": 23,
"four five": 45
}
}
После
{
"two": {
"four five": 45
}
}
||example.org^$jsonprune=\$.a[?(has ad_origin)]
удаляет всех прямых потомковa
, которые обладают свойствомad_origin
.
До
{
"a": [
{
"ad_origin": "https://example.org",
"b": 42
},
{
"b": 1234
}
]
}
После
{
"a": [
{
"b": 1234
}
]
}
||example.org^$jsonprune=\$.*.*[?(key-eq 'Some key' 'Some value')]
удаляет все элементы на уровне вложенности 3, обладающие свойством Some key, равным Some value.
До
{
"a": {"b": {"c": {"Some key": "Some value"}, "d": {"Some key": "Other value"}}},
"e": {"f": [{"Some key": "Some value"}, {"Some key": "Other value"}]}
}
После
{
"a": {"b": {"d": {"Some key": "Other value"}}},
"e": {"f": [{"Some key": "Other value"}]}
}
Вложенные выражения JSONPath
В AdGuard для Windows, Mac и Android с CoreLibs версии 1.11 или выше выражения JSONPath могут быть использованы как ключи в выражениях фильтра.
||example.org^$jsonprune=\$.elems[?(has "\$.a.b.c")]
удаляет всех прямых потомковelems
, которые обладают свойством, выбираемым JSONPath-выражением$.a.b.c
.
До
{
"elems": [
{
"a": {"b": {"c": 123}},
"k": "v"
},
{
"d": {"e": {"f": 123}},
"k1": "v1"
}
]
}
После
{
"elems": [
{
"d": {"e": {"f": 123}},
"k1": "v1"
}
]
}
||example.org^$jsonprune=\$.elems[?(key-eq "\$.a.b.c" "abc")]
удаляет всех прямых потомковelems
, которые обладают свойством, выбираемым выражением JSONPath$.a.b.c
со значением, равным"abc"
.
До
{
"elems": [
{
"a": {"b": {"c": 123}},
},
{
"a": {"b": {"c": "abc"}}
}
]
}
После
{
"elems": [
{
"a": {"b": {"c": 123}}
}
]
}
- Правила с
$jsonprune
совместимы с модификаторами$domain
,$third-party
,$app
,$important
,$match-case
и$xmlhttprequest
. $jsonprune
rules do not apply if the size of the original response is more than 10 MB.
Правила с модификатором $jsonprune
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.10 или выше.
$network
По сути, это правила типа Firewall, позволяющие полностью блокировать или разблокировать доступ к указанному удалённому адресу.
- Правила
$network
соответствуют только IP-адресам! Вы не можете использовать их, чтобы блокировать или разблокировать доступ к домену. - Чтобы сопоставить адрес IPv6, вы должны использовать сжатый синтаксис, например, использовать
[2001:4860:4860::8888]$network
вместо[2001:4860:4860:0:0:0:0:8888]$network
. - An allowlist
$network
rule makes AdGuard bypass data to the matching endpoint, hence there will be no further filtering at all. - Если часть IP начинается и заканчивается символом
/
, она рассматривается как регулярное выражение.
Рекомендуем ознакомиться с этой статьёй для лучшего понимания регулярных выражений.
Модификатор $network
можно использовать в правилах только вместе с модификаторами $app
и $important
, но не с какими-либо другими модификаторами.
Примеры
174.129.166.49:3478^$network
блокирует доступ к174.129.166.49:3478
(но не к174.129.166.49:34788
).[2001:4860:4860::8888]:443^$network
блокирует доступ к[2001:4860:4860::8888]:443
.174.129.166.49$network
блокирует доступ к174.129.166.49:*
.@@174.129.166.49$network
заставляет AdGuard направлять трафик в конечную точку. Никакие другие правила применяться не будут./.+:3[0-9]{4}/$network
блокирует доступ к диапазанону портов 30000–39999./8.8.8.(:?8|4)/$network
блокирует доступ к8.8.8.8
и к8.8.8.4
.
Только AdGuard для Windows, Mac и Android имеют технические возможности для поддержки правил с модификатором $network
.
$permissions
Этот модификатор полностью меняет поведение правила. Когда он применяется, правило не блокирует запрос. Вместо этого будут изменены заголовки ответа.
Чтобы использовать правила этого типа, необходимо базовое понимание слоя безопасности Feature Policy.
Для запросов, соответствующих правилу $permissions
, AdGuard усиливает «политику функций» ответа, добавляя дополнительную политику, равную содержимому модификатора $permissions
. Правила $permissions
применяются независимо от правил любого другого типа. Only document-level exceptions can influence it (see the examples section), but no other basic rules.
Несколько правил, соответствующих одному запросу.
В случае, когда несколько правил с $permissions
соответствуют одному запросу, AdGuard применит каждое из них.
Синтаксис
Синтаксис значения $permissions
подобен заголовку Permissions-Policy
синтаксису с одним исключением: запятая, разделяющая несколько функций , ДОЛЖНА экранироваться — см. примеры ниже. Список доступных директив доступен здесь.
Значение $permissions
может быть пустым в случае правил-исключений — смотрите примеры ниже.
Примеры
||example.org^$permissions=autoplay=()
запрещает автовоспроизведение медиафайлов, запрашиваемых через интерфейсHTMLMediaElement
на сайтеexample.org
.@@||example.org/page/*$permissions=autoplay=()
отключает все правила с модификатором$permissions
, в точности соответствующимautoplay=()
на всех страницах, подходящих под паттерн правила. Например, правило выше.@@||example.org/page/*$permissions
отключает все$permissions
-правила на всех страницах, подходящих под паттерн правила.$domain=example.org|example.com,permissions=storage-access=()\, camera=()
запрещает использование Storage Access API для запроса доступа к неразмеченным куки, а также использование устройств видеоввода на сайтахexample.org
иexample.com
.@@||example.org^$document
или@@||example.org^$urlblock
отключает все$permission
-правила на всех страницах, подходящих под паттерн правила.
- В модификаторе
$permissions
запрещён символ$
$permissions
is compatible with three types of modifiers:$domain
,$important
, and$subdocument
Правила с модификатором $permissions
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.11 или выше.
$redirect
AdGuard способен перенаправлять веб-запросы на локальный «ресурс».
Синтаксис
AdGuard использует тот же синтаксис правил фильтрации, что и uBlock Origin. Также он совместим с модификатором ABP $rewrite=abp-resource
.
$redirect
— это модификатор для базовых правил фильтрации, поэтому правила с этим модификатором поддерживают остальные базовые модификаторы, такие как $domain
, $third-party
, $script
и т. д.
Значение модификатора $redirect
должно быть именем ресурса, который будет использован для переадресации.
Отключение правил $redirect
||example.org/script.js$script,redirect=noopjs
— это правило перенаправляет все запросы кexample.org/script.js
на ресурс с именемnoopjs
.||example.org/test.mp4$media,redirect=noopmp4-1s
— это правило перенаправляет все запросы кexample.org/script.js
на ресурс с именемnoopmp4-1s
.@@||example.org^$redirect
отключит все правила$redirect
для URL-адресов, соответствующих||example.org^
.@@||example.org^$redirect=nooptext
отключит все правила с$redirect=nooptext
для любого запроса, который соответствует||example.org^
.
Больше информации о редиректах и их использовании доступно на GitHub.
Приоритеты правил $redirect
У правил с $redirect
более высокий приоритет, чем у обычных базовых правил блокировки. Это означает, что если существует базовое правило блокировки, то правило $redirect
будет его отменять. У правил белого списка с пометкой @@
более высокий приоритет, чем у правил $redirect
. Если базовое правило с модификатором $important
и правило $redirect
соответствуют одному и тому же URL-адресу, последнее переопределяется, если оно также не помечено как $important
.
$important
> @@
> $redirect
> базовые правила
.
Перейдите к приоритетам правил для более подробной информации.
- Правила с модификатором
$redirect
не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari. $redirect
в uBlock Origin поддерживает указание приоритета, например,$redirect=noopjs:42
. AdGuard не поддерживает его и вместо этого просто отбрасывает приоритетный постфикс.
$redirect-rule
По сути это другое имя $redirect
, поскольку он имеет те же значения «перенаправления» и почти аналогичную логику. Разница в том, что $redirect-rule
применяется только в том случае, если целевой запрос заблокирован другим базовым правилом.
Перейдите к приоритетам правил для более подробной информации.
Отключение $redirect-rule
работает точно так же, как для обычных правил $redirect
. Даже более того, @@||example.org^$redirect
будет отключать как правило $redirect
, так и $redirect-rule
.
Примеры
||example.org/script.js
||example.org^$redirect-rule=noopjs
В этом случае только запросы к example.org/script.js
будут перенаправлены на noopjs
. Все остальные запросы к example.org
останутся без изменений.
Правила с модификатором $redirect
не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.
$referrerpolicy
Эти правила позволяют переопределить политику реферера страницы . В ответах на соответствующие запросы все заголовки Referrer-Policy
заменит один заголовок со значением, равным значению модификатора правила сопоставления. Если ответ содержит HTML-документ с тегом <meta name="referrer"...
, то атрибут content
этого тега также будет заменён на значение модификатора.
Правило исключения со значением модификатора отключает правило блокировки с тем же значением. Правило исключения без значения модификатора отключает все совпадающие правила referrer-policy.
Если запрос соответствует нескольким правилам $referrerpolicy
, не отключённым исключениями, то применяется только одно из них (какое именно — не уточняется). Правила $referrerpolicy
без указанных модификаторов типа контента применяются к типам контента $document
и $subdocument
.
Примеры
||example.com^$referrerpolicy=unsafe-url
переопределяет политику referrer дляexample.com
сunsafe-url
.@@||example.com^$referrerpolicy=unsafe-url
отключает предыдущее правило.@@||example.com/abcd.html^$referrerpolicy
отключает все правила$referrerpolicy
наexample.com/abcd.html
.
Правила с модификатором $referrerpolicy
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.12 или выше.
$removeheader
Правила с модификатором $removeheader
предназначены для того, чтобы убирать заголовки HTTP-запросов и ответов. Изначальная мотивация для создания этого типа правил заключалась в том, чтобы иметь возможность избавиться от заголовка Refresh
, который часто используется для перенаправления пользователей на нежелательную страницу. Однако применение данного модификатора не ограничивается этим случаем.
Как и в случае с $csp
, $redirect
, $removeparam
и $cookie
, этот модификатор существует независимо, правила с ним не зависят от обычных базовых правил, то есть регулярные выражения или блокирующие правила никак на них не повлияют. По умолчанию они работают только применительно к заголовкам ответов. Но вы также можете изменить его, чтобы удалить заголовки из HTTP-запросов.
Синтаксис
Базовый синтаксис
||example.org^$removeheader=header-name
убирает заголовок ответа с названиемheader-name
||example.org^$removeheader=request:header-name
убирает заголовок запроса с названиемheader-name
$removeheader
нечувствителен к регистру, но мы настоятельно рекомендуем всегда использовать нижний регистр.
Отрицание $removeheader
Этот тип правил работает почти так же, как и с модификаторами $csp
и $redirect
.
Используйте @@
, чтобы отменить $removeheader
:
@@||example.org^$removeheader
отменяет все правила$removeheader
для URL-адресов, соответствующих||example.org^
.@@||example.org^$removeheader=header
отменяет все правила с$removeheader=header
для любого запроса, соответствующего||example.org^
.
Правила с $removeheader
также можно отключить, используя правила-исключения $document
и $urlblock
. Но базовые правила-исключения без модификаторов не смогут этого сделать. Например, @@||example.com^
не отключит $removeheader=p
для запросов к example.com
, а @@||example.com^$urlblock
отключит.
В случае, когда несколько правил с $removeheader
соответствуют одному запросу, мы будем применять их все по очереди.
Примеры
|
|example.org^$removeheader=refresh
убирает заголовокRefresh
из всех HTTP-ответов, возвращённыхexample.org
и его поддоменами.||example.org^$removeheader=request:x-client-data
убирает заголовокX-Client-Data
из всех HTTP-запросов.Данный блок правил убирает заголовки
Refresh
иLocation
из всех HTTP-ответов, возвращённыхexample.org
, кроме запросов кexample.org/path/*
, для которого заголовки не будут убраны:||example.org^$removeheader=refresh
||example.org^$removeheader=location
@@||example.org/path/$removeheader
Этот тип правил может быть использован только в доверенных фильтрах.
Чтобы избежать потенциальных проблем с безопасностью,
$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
Правила с
$removeheader
совместимы с модификаторами$domain
,$third-party
,$app
,$important
,$match-case
, а также модификаторами типа контента, такими как$script
и$stylesheet
. Правила с другими модификаторами считаются некорректными и не будут применены.
Правила с модификатором $removeheader
поддерживаются в AdGuard для Windows, Mac и Android, а также в Браузерном расширении AdGuard для Chrome, Firefox и Edge.
$removeparam
Модификатор $removeparam
— это полный аналог модификатора $queryprune
. Поскольку модификатор $queryprune
считается устаревшим, рекомендуем везде использовать только модификатор $removeparam
.
Правила с модификатором $removeparam
предназначены для того, чтобы убирать параметры запроса из URL-адресов. Такие правила применяются только к запросам типов GET
, HEAD
, OPTIONS
и иногда к POST
.
Правила с модификатором $removeparam
, не содержащие модификаторов типа контента, будут соответствовать только тем запросам, которые имеют тип контента document
.
Синтаксис
Базовый синтаксис
$removeparam=param
убирает параметр запроса с именемparam
из URL любого запроса. Например, запрос кhttp://example.com/page?param=1&&another=2
будет преобразован вhttp://example.com/page?another=2
.
Правила с модификатором $removeparam
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.7 или выше и в Браузерном расширении AdGuard версии 3.6 или выше.
Регулярные выражения
Вы также можете использовать регулярные выражения, чтобы выбрать нужные параметры запроса или их значения:
$removeparam=/regexp/[options]
убирает из URL-адреса любого запроса все параметры, соответствующие заданному регулярному выражениюregexp
. В отличие от базового синтаксиса, это означает «убрать параметры запроса, нормализованные к строкеname=value
, которая соответствуетрегулярному выражению
».[options]
— это список опций регулярного выражения. На данный момент единственная поддерживаемая опция — этоi
, делающая соответствие нечувствительным к регистру.
Экранирование специальных символов
Не забывайте экранировать специальные символы, такие как ,
, /
и $
в регулярных выражениях. Используйте для этого символ \
. Например, экранированная запятая должна выглядеть так: \,
.
Правила с регулярными выражениями смотрят как на название, так и на значение параметра. Чтобы свести к минимуму ошибки, рекомендуем начинать регулярное выражение с /^
, если только вы не хотите специально работать со значениями параметров.
Мы стараемся обнаруживать и игнорировать неэкранированные символы $
автоматически. По умолчанию не считаем символ разделителем, если верны три условия:
- Есть сочетание
$/
- Слева от символа есть ещё один слеш
/
- Слева от этого слеша есть ещё один неэкранированный символ
$
Удалить параметры запроса
Укажите «голый» $removeparam
, чтобы удалить все параметры запроса:
||example.org^$removeparam
удаляет все параметры запроса из URL-адресов, соответствующих правилу||example.org^
.
Инверсия
Используйте ~
, чтобы применить инверсию:
$removeparam=~param
удаляет все параметры запроса, кромеparam
.$removeparam=~/regexp/
удаляет все параметры запроса, которые не совпадают с заданным регулярным выражениемregexp
.
Исключение правил с $removeparam
Этот тип правил работает практически так же, как и в случае с модификаторами $csp
и $redirect
.
Используйте @@
, чтобы исключить правило с $removeparam
:
@@||example.org^$removeparam
не даёт применять правила с$removeparam
для URL, соответствующихexample.org
.@@||example.org^$removeparam=param
не даёт применять правила с$removeparam=param
для запросов кexample.org
.@@||example.org^$removeparam=/regexp/
не даёт применять правила с$removeparam=/regexp/
для запросов кexample.org
.
Несколько правил, соответствующих одному запросу
В случае, когда несколько правил с $removeparam
соответствуют одному запросу, они все будут применены по очереди.
Примеры
$removeparam=/^(utm_source|utm_medium|utm_term)=/
$removeparam=/^(utm_content|utm_campaign|utm_referrer)=/
@@||example.com^$removeparam
С помощью этих правил некоторые параметры UTM будут удалены из любого запроса, за исключением запросов к example.com
, которые не будут удалены вообще. Например, http://google.com/page?utm_source=s&utm_referrer= fb.com&utm_content=img
будет преобразован в http://google.com/page
, но на http://example.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img
правило блокировки не повлияет.
$removeparam=utm_source
удаляет параметрutm_source
из всех запросов.$removeparam=/utm_.*/
удаляет все параметрыutm_*
из URL любого запроса. Например, запросhttp://example.com/page?utm_source=test
будет трансформирован вhttp://example.com/page
.$removeparam=/^utm_source=campaign$/
удаляет параметрutm_source
со значениемcampaign
. Не затрагивает другие параметрыutm_source
.
Исключение правила с $removeparam
и замена его другим
$removeparam=/^(gclid|yclid|fbclid)=/
@@||example.com^$removeparam=/^(gclid|yclid|fbclid)=/
||example.com^$removeparam=/^(yclid|fbclid)=/
Эти правила удаляют Click ID Google, Яндекса и Facebook. Есть одно исключение: Google Click ID (gclid) не будет удалён из запросов к example.com.
Исключение правила с $removeparam
для всех параметров
$removeparam=/^(utm_source|utm_medium|utm_term)=/
$removeparam=/^(utm_content|utm_campaign|utm_referrer)=/
@@||example.com^$removeparam
Эти правила удаляют указанные UTM-параметры из всех запросов, кроме запросов к example.org
.
Правила с $removeparam
также можно отключить с помощью правил исключений с $document
и $urlblock
. Но базовые правила исключений без модификаторов не могут этого сделать. Например, @@||example.com^
не отключит $removeparam=p
для запросов к example.com, а вот @@||example.com^$urlblock
— отключит.
- Правила с модификатором
$removeparam
могут быть использованы только в доверенных фильтрах. - Правила с
$removeparam
совместимы с базовыми модификаторами, модификаторами типа контента, а также с модификаторами$important
и$app
. Правила с любыми другими модификаторами считаются некорректными и не будут применены.
- Правила с модификатором
$removeparam
поддерживаются в AdGuard для Windows, Mac и Android и Браузерном расширении AdGuard для Chrome, Firefox и Edge. - Синтаксис регулярных выражений
$removeparam
поддерживается в Браузерном расширении AdGuard 4.0 и в AdGuard для Windows, Mac и Android, с CoreLibs версии 1.8 или выше. - Типы запросов
POST
поддерживаются только в AdGuard для Windows, Mac и Android с CoreLibs версии 1.10 или выше.
$replace
Этот модификатор полностью меняет поведение страницы. Когда он применяется, правило не блокирует запрос. Вместо этого ответ модифицируется.
Вам потребуется знание регулярных выражений, чтобы использовать модификатор $replace
.
Функции
- Правила с
$replace
применяются к любому текстовому ответу, но не применяются к binary (media
,image
,object
и т. д.). $replace
rules do not apply if the size of the original response is more than 10 MB.- Правила с
$replace
обладают более высоким приоритетом, чем другие базовые правила (включая правила исключений). Если запрос соответствует двум различным правилам, одно из которых имеет модификатор$replace
, применится именно это правило. - Правила исключений уровня document с модификаторами
$content
или$document
отменяют срабатывание правил$replace
, даже если запрос им соответствует. - Прочие правила исключений уровня document (с модификаторами
$generichide
,$elemhide
или$jsinject
) применяются вместе с правилами$replace
. Это означает, что вы можете изменять содержимое страницы при помощи правила$replace
и одновременно отменять косметические правила.
Значение $replace
может быть пустым в случае правил исключений. Более подробную информацию вы найдёте в разделе с примерами.
Несколько правил, соответствующих одному запросу
В случае, когда несколько правил $replace
соответствуют одному запросу, мы применим каждое из них. Правила будут применяться в алфавитном порядке.
Синтаксис
В целом синтаксис $replace
аналогичен замене регулярными выражениями в Perl.
replace = "/" regexp "/" replacement "/" modifiers
regexp
— регулярное выражение.replacement
— строка, которая будет использована для замены строки в соответствии сregexp
.modifiers
— флаги регулярных выражений. Например,i
— поиск без учёта регистра, илиs
— режим одной строки.
В значении $replace
необходимо экранировать два символа: запятую ,
и знак доллара $
. Используйте для этого обратный слеш \
. Например, экранированная запятая будет выглядеть так: \,
.
Примеры
||example.org^$replace=/(<VAST[\s\S]*?>)[\s\S]*<\/VAST>/\$1<\/VAST>/i
У этого правила три части:
regexp
(регулярное выражение) —(<VAST(.|\s)*?>)(.|\s)*<\/VAST>
replacement
(замена) —\$1<\/VAST>
где$
экранируетсяmodifiers
(флаги регулярных выражений) —i
для поиска без учёта регистра
Здесь вы можете увидеть, как работает это правило: http://regexr.com/3cesk
Несколько правил с $replace
||example.org^$replace=/X/Y/
||example.org^$replace=/Z/Y/
@@||example.org/page/*$replace=/Z/Y/
- Правила 1 и 2 будут применены ко всем запросам, отправленным к
example.org
. - Правило 2 отключено для запросов, соответствующих
||example.org/page/
, но правило 1 при этом всё равно работает!
Отключение правил с $replace
@@||example.org^$replace
отключит все правила с$replace
, где есть||example.org^
.@@||example.org^$document
или@@||example.org^$content
отключит все правила с$replace
, исходящие со страниц доменаexample.org
, включая саму эту страницу.
Правила с модификатором $replace
могут быть использованы только в доверенных фильтрах.
Правила с модификатором $replace
поддерживаются в AdGuard для Windows, Mac и Android и Браузерном расширении AdGuard для Firefox. Другие расширения не могут модифицировать содержимое страниц на сетевом уровне, поэтому там эти правила не работают.
noop
Модификатор noop
не делает ничего и используется только для того, чтобы улучшить читаемость правил. Он состоит из последовательности символов нижнего подчёркивания (_
) любой длины и может фигурировать в правиле столько раз, сколько требуется.
Примеры
||example.com$_,removeparam=/^ss\\$/,_,image
||example.com$replace=/bad/good/,___,~third-party
Правила с модификатором noop
не поддерживаются в AdGuard Content Blocker.
$empty
(устаревший)
Этот модификатор считается устаревшим. Вместо него теперь используется модификатор $redirect
. Правила с $empty
всё ещё поддерживаются и преобразуются в $redirect=nooptext
, но в будущем перестанут поддерживаться.
Обычно заблокированный запрос выглядит для браузера как ошибка сервера. В случае применения модификатора $empty
AdGuard эмулирует пустой ответ сервера со статусом 200 OK
.
Примеры
||example.org^$empty
возвращает пустой ответ для всех запросов к доменуexample.org
и всех его поддоменов.
Правила с модификатором $empty
не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.
$mp4
(устаревший)
Этот модификатор считается устаревшим. Вместо него теперь используется модификатор $redirect
. Правила с $mp4
всё ещё поддерживаются и преобразуются в $redirect=noopmp4-1s,media
, но в будущем перестанут поддерживаться.
В качестве ответа на заблокированный запрос AdGuard возвращает короткую видео-заглушку.
Примеры
||example.com/videos/$mp4
блокирует загрузку видео с адресов||example.com/videos/*
и заменяет ответ на видео-заглушку.
Правила с модификатором $mp4
не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.
Приоритеты правил
Каждое правило имеет свой приоритет, что необходимо, когда запросу соответствует несколько правил и фильтрующий механизм должен выбрать одно из них. Приоритет измеряется целым положительным числом.
Если два правила с одинаковым приоритетом соответствуют одному и тому же запросу, то от реализации механизма фильтрации зависит, какое из них будет выбрано.
Концепция приоритетов правил становится всё более важной в свете Manifest V3, поскольку существующие правила должны быть преобразованы в правила declarativeNetRequest.
Priority calculation
Для расчёта приоритета мы разделили модификаторы на разные группы. Эти группы ранжируются по степени приоритетности, от низшей к высшей. Модификатор, существенно сужающий область действия правила, увеличивает вес его общего приоритета. И наоборот, если правило применяется к более широкому кругу запросов, то его приоритет снижается.
Следует отметить, что существуют случаи, когда модификатор с одним параметром имеет более высокий приоритет, чем тот, у которого много параметров. Например, в случае $domain=example.com|example.org
правило, включающее два домена, имеет несколько более широкую область действия, чем правило с одним указанным доменом, поэтому его приоритет ниже.
Базовый приоритет любого правила равен 1. Если вычисленный приоритет — число с плавающей точкой, то оно будет округлено в большую сторону до наименьшего целого числа, большего или равного вычисленному приоритету.
- Понятие приоритета было введено в tsurlfilter 2.1.0 и CoreLibs 1.13. До этого в AdGuard не было специального алгоритма вычисления приоритетов, и обработка конфликтов могла отличаться в зависимости от продукта и версии AdGuard.
- AdGuard для iOS, Safari и AdGuard Content Blocker зависят от реализации браузера и не могут следовать указанным здесь правилам.
Псевдонимы-модификаторы (1p
, 3p
и т. д.) не входят в эти категории, однако, они используются в движке для вычисления приоритета правила.
Базовые модификаторы, наличие каждого добавляет 1 к приоритету
$app
с приложениями, исключаемыми с помощью~
$denyallow
$domain
с доменами, исключаемыми с помощью~
$match-case
$method
с методами, исключаемыми с помощью~
$third-party
$to
- ограниченные модификаторы сontent-type с
~
При работе с исключаемым доменом, приложением, методом или типом содержимого мы добавляем 1 балл за существование самого модификатора, независимо от количества исключаемых доменов или типов содержимого. Это связано с тем, что область действия правила и так бесконечно широка. Проще говоря, запрещая несколько доменов, модификаторов content-type, методов или приложений, мы лишь немного сужаем область действия правила.
Определённые модификаторы content-type, методы, заголовки, $popup, специальные исключения
Все разрешённые типы контента:
Это также включает правила, которые неявно добавляют модификатор $document
:
Или специальные исключения, которые неявно добавляют $document,subdocument
:
Или методы, разрешённые модификатором $method
.
Или правила с $header
.
Наличие любых модификаторов content-type добавляет (50 + 50 / N)
, где N
— количество модификаторов, например: ||example.com^$image,script
добавит 50 + 50 / 2 = 50 + 25 = 75
к общему весу правила. К этой категории относится и $popup
, так как в нём неявно добавляется модификатор $document
. Аналогично, конкретные исключения добавляют $document,subdocument
.
Если в правиле есть модификатор $method
с разрешёнными методами, то он добавляет (50 + 50 / N)
, где N
— количество разрешённых методов, например: ||example.com^$method=GET|POST|PUT
добавит 50 + 50 / 3 = 50 + 16,6 = 67
к общему весу правила.
Если в правиле есть модификатор $header
, то он добавляет 50
.
$domain
или $app
с разрешёнными доменами или приложениями
Домены или приложения, указанные с помощью $domain
и $app
соответственно, добавят 100 + 100 / N
, где N
— количество значений модификатора, например: ||example.com^$domain=example.com|example.org|example.net
добавит 100 + 100 / 3 = 135
или ||example.com^$app=org.example.app1|org.example.app2
добавит 100 + 100 / 2 = 100 + 51 = 151
или ||example.com^$domain=example.com,app=org.example.app1|org.example.app2
добавит 100 + 100/1
(часть $domain) и 100 + 100/2
(часть $app) — в сумме 350
.
Значения модификаторов regexps или tld будут интерпретироваться как обычные записи вида example.com
и считаться по одному, например: ||example.com^$domain=example.*
будет добавлено 100 + 100 / 1 = 200
или ||example.com^$domain=example.*|adguard.*
будет добавлено 100 + 100 / 2 = 150
.
Правила $redirect
Каждое из них добавляет 10^3
к приоритету правила.
Особые исключения
Каждое из них добавляет 10^4
к приоритету.
Исключение с модификатором $document
в том числе: это псевдоним для $elemhide, content,jsinject,urlblock,extension
. Оно добавит 10^4
для каждого модификатора из верхнего списка, 10^4 * 5
в сумме.
Кроме того, каждое из этих исключений неявно добавляет два разрешённых модификатора типа контента: $document,subdocument
.
Правила белого списка
Модификатор @@
добавляет 10^5
к приоритету правила.
Правила $important
Модификатор $important
добавляет 10^6
к приоритету правила.
Правила, для которых нет веса приоритета
Прочие модификаторы, которые должны выполнять дополнительную пост- или предобработку запросов, ничего не добавляют к приоритету правил.
Примеры
Пример 1
||example.com^
Вес правила без модификаторов: 1
.
Пример 2
||example.com^$match-case
Вес правила: базовый вес + вес модификатора из категории 1: 1 + 1 = 2
.
Пример 3
||example.org^$removeparam=p
Вес правила: базовый вес + 0, так как $removeparam не участвует в расчёте приоритета: 1 + 0 = 1
.
Пример 4
||example.org^$document,redirect=nooptext
Вес правила: базовый вес + допустимый тип содержимого, категория 3 + $redirect из категория 6: 1 + (100 + 100 / 1) + 1000 = 1201
.
Пример 5
@@||example.org^$removeparam=p,document
Вес правила: базовый вес + правило белого списка, категория 5 + 0, потому что $removeparam не участвует в расчёте приоритета + разрешённый тип контента, категория 2: 1 + 10000 + 0 + (50 + 50 / 1) = 10101
.
Пример 6
@@||example.com/ad/*$domain=example.org|example.net,important
Вес правила: базовый вес + правило белого списка, категория 5 + важное правило, категория 7 + разрешённые домены, категория 3: 1 + 10000 + 1000000 + (100 + 100 / 2) = 1010152
.
Пример 7
@@||example.org^$document
без дополнительных модификаторов — это псевдоним для @@|||example.com^$elemhide,content,jsinject,urlblock,extension
Вес правила: базовый вес + специфические исключения, категория 4 + два разрешённых типа контента (document и subdocument), категория 2: 1 + 10000 * 4 + (50 + 50 / 2) = 40076
.
Пример 8
*$script,domain=a.com,denyallow=x.com|y.com
Вес правила: базовый вес + разрешённый тип контента, категория 2 + разрешённый домен, категория 3 + отказ, категория 1: 1 + (50 + 50/1) + (100 + 100 / 1) + 1 = 303
.
Пример 9
||example.com^$all
(псевдоним для ||example.com^$document,subdocument,image,script,media и т.д. + $popup
)
Вес правила: базовый вес + разрешённые типы контента, категория 2: 1 + (50 + 50 / 12) = 55
.
Другие правила
Базовых правил может быть недостаточно для блокировки рекламы. Иногда для этого требуется скрыть какой-нибудь элемент или изменить часть HTML-кода страницы, при этом ничего не сломав. Для этого предназначены правила, описанные в данном разделе.
Категории \ Продукты | Приложения CoreLibs | AdGuard для Chromium | AdGuard для Firefox | AdGuard для iOS | AdGuard для Safari | AdGuard Content Blocker |
---|---|---|---|---|---|---|
Скрытие элементов | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
CSS-правила | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
Расширенный CSS | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
Фильтрация HTML | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
JavaScript | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
Скриптлеты | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
- ✅ — полностью поддерживается
- ❌ — не поддерживается
Косметические правила
Для работы с косметическими правилами необходимы знания HTML и CSS. Если вы хотите научиться самостоятельно составлять такие правила, ознакомьтесь с документацией.
Правила скрытия элементов
Правила скрытия элементов предназначены, как это следует из их названия, для скрытия элементов веб-страниц. По сути это аналогично применению стиля { display: none; }
к выбранному элементу.
Правила скрытия элементов работают по-разному, и их приоритет меняется в зависимости от платформы.
Синтаксис
rule = [domains] "##" selector
domains = [domain0, domain1[, ...[, domainN]]]
selector
— CSS-селектор, задающий элементы, которые должны быть скрыты.domains
— ограничение на домены, на страницах которых будет применено правило.
Если вы хотите ограничить область действия одним или более доменами, просто перечислите их через запятую. Например: example.org,example.com##selector
.
Это правило будет работать также на всех поддоменах example.org
и example.com
.
Если вы хотите, чтобы правило не применялось к определённым доменам, начните доменное имя со знака ~
. Например: ~example.org##selector
.
Вы можете использовать оба подхода в одном правиле. Например, правило example.org,~subdomain.example.org##domain
будет работать для домена example.org
и всех его поддоменов, кроме subdomain.example.org
.
Правила скрытия не зависят друг от друга. Если в фильтре есть правило example.org##selector
и вы добавляете правило ~example.org##selector
, то оба этих правила будут применены независимо друг от друга.
Примеры
example.com##div.textad
— hides adiv
with the classtextad
atexample.com
and all subdomains.example.com,example.org###adblock
скроет элемент с атрибутомid
равнымadblock
на доменахexample.com
,example.org
и всех их поддоменах.~example.com##.textad
— hides an element with the classtextad
at all domains, exceptexample.com
and its subdomains.
Ограничения
Safari не поддерживает одновременно разрешённые и запрещённые домены, поэтому правила вида example.org,~foo.example.org##.textad
не работают в AdGuard для Safari.
Исключения
Исключения могут отключать некоторые правила на определённых доменах. Они очень похожи на обычные правила-исключения, только вместо ##
нужно использовать #@#
.
Например, в фильтре есть правило:
##.textad
Если вы хотите отключить его для домена example.com
, вы можете создать правило исключения:
example.com#@#.textad
В некоторых случаях может потребоваться отключение всех запрещающих правил. Например, на время тестирования. Для этого воспользуйтесь правилом исключения без указания домена. Это полностью отключит соответствующее правило CSS elemhide для ВСЕХ доменов:
#@#.textad
Правило такого вида даст аналогичный результат:
*#@#.textad
Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия невозможно. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.
CSS-правила
Иногда недостаточно просто скрыть какой-либо элемент, чтобы заблокировать рекламу. Например, блокировка рекламного элемента может просто сломать вёрстку сайта. Для таких случаев AdGuard позволяет использовать гораздо более гибкие правила, чем обычные правила скрытия. With these rules you can basically add any CSS styles to the page.
Синтаксис
rule = [domains] "#$#" selector "{" style "}"
domains = [domain0, domain1[, ...[, domainN]]]
selector
— CSS-селектор, определяющий элементы, к которым мы хотим применить стиль.domains
— ограничение на домены, на страницах которых будет применено правило. Строится по тем же правилам, что и в случае правил скрытия элементов.style
— CSS-стиль, который мы хотим применить к выбранным элементам.
Примеры
example.com#$#body { background-color: #333!important; }
Это правило применит стиль background-color: #333!important;
к элементу body
для домена example.com
и всех его поддоменов.
Исключения
По аналогии с правилами скрытия существует специальный тип правил, отключающий действие выбранного правила CSS-стилей для определённых доменов. Синтаксис правил-исключений практически такой же, только маркер #$#
заменяется на #@$#
.
Например, в фильтре есть правило:
#$#.textad { visibility: hidden; }
Если вы хотите отключить его для домена example.com
, вы можете создать правило исключения:
example.com#@$#.textad { visibility: hidden; }
Применять такие исключения рекомендуется только в случае, когда невозможно изменить само CSS-правило. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.
Запрещено использование стилей, которые могут приводить к загрузке каких-либо ресурсов. Это означает, что нельзя использовать атрибуты типа <url>
.
CSS-правила не поддерживаются в AdGuard Content Blocker.
CSS-правила работают по-разному, и их приоритет меняется в зависимости от платформы.
Расширенные CSS-селекторы
- Ограничения
- Псевдокласс
:has()
- Псевдокласс
:contains()
- Псевдокласс
:matches-css()
- Псевдокласс
:matches-attr()
- Псевдокласс
:matches-property()
- Псевдокласс
:xpath()
- Псевдокласс
:nth-ancestor()
- Псевдокласс
:upward()
- Псевдокласс
:remove()
и псевдосвойствоremove
- Псевдокласс
:is()
- Псевдокласс
:not()
- Псевдокласс
:if-not()
(удалён)
Возможностей CSS 3.0 не всегда хватает для блокировки рекламы. Чтобы решить эту проблему, AdGuard расширяет возможности CSS, добавляя поддержку новых псевдоэлементов. Мы разработали отдельную библиотеку с открытым исходным кодом для выбора нестандартных элементов и применения CSS-стилей с расширенными свойствами.
Идея расширенных возможностей заключается в возможности сопоставлять элементы DOM с селекторами на основе их собственного представления (стиль, текстовое содержимое и т. д.) или отношений с другими элементами. Также есть возможность применять стили с нестандартными свойствами CSS.
Область применения
Расширенные селекторы можно применять в любом косметическом правиле, будь то правила скрытия или CSS-правила.
Правила с расширенными CSS-селекторами не поддерживаются в AdGuard Content Blocker.
Синтаксис
Независимо от того, какие CSS-псевдоклассы вы используете в правилах, вы можете использовать специальные маркеры для принудительного применения этих правил с помощью ExtendedCss. Рекомендуется использовать эти маркеры для всех косметических расширенных CSS-правил, чтобы их было легче отличить.
Синтаксис расширенных CSS-правил:
#?#
— для скрытия элементов,#@?#
— для исключений#$?#
— для CSS-стилей,#@$?#
— для исключений
Настоятельно рекомендуем использовать этим маркеры каждый раз, когда вы используете расширенный CSS-селектор.
Примеры
example.org#?#div:has(> a[target="_blank"][rel="nofollow"])
— это правило блокирует все элементыdiv
, которые содержат дочерний элемент со ссылкой с атрибутами[target="_blank"][rel="nofollow"]
. При этом правило будет работать только для доменаexample.org
и всех его поддоменов.example.com#$?#h3:contains(cookies) { display: none!important; }
— это правило устанавливает стильdisplay: none!important
для всех элементовh3
, которые содержат словоcookies
. При этом правило будет работать только для доменаexample.com
и всех его поддоменов.example.net#?#.banner:matches-css(width: 360px)
— это правило блокирует все элементы.banner
, которые содержат стильwidth: 360px
. При этом правило будет работать только для доменаexample.net
и всех его поддоменов.example.net#@?#.banner:matches-css(width: 360px)
— это правило отменяет действие предыдущего правила.
You can apply standard CSS selectors using the ExtendedCss library by using the rule marker #?#
, e.g. #?#div.banner
.
Больше об отладке расширенных селекторов
Некоторые псевдоклассы не требуют селектора перед ними. Still adding the universal selector *
makes an extended selector easier to read, even though it has no effect on the matching behavior. Поэтому селектор #block :has(> .inner)
работает точно так же, как #block *:has(> .inner)
, но второй более очевиден.
Названия псевдоклассов не чувствительны к регистру, например, :HAS()
работает как :has()
. До сих пор часто используются названия в нижнем регистре.
Ограничения ExtendedCss
CSS-комментарии и at-rules не поддерживаются.
У конкретного псевдокласса могут быть свои ограничения:
:has()
,:xpath()
,:nth-ancestor()
,:upward()
,:is()
,:not()
, and:remove()
.
Псевдокласс :has()
Проект спецификации CSS 4.0 описывает псевдокласс :has()
. К сожалению, популярные браузеры пока не поддерживают этот псевдокласс.
Rules with the :has()
pseudo-class must use the native implementation of :has()
if they use ##
marker and if it is possible, i.e. with no other extended selectors inside. Чтобы принудительно применить правила ExtendedCss с :has()
, используйте маркер #?#
/#$?#
явно.
Совместимость с другими псевдоклассами
Синонимы :-abp-has()
поддерживаются ExtendedCss для лучшей совместимости.
:if()
больше не поддерживается как синоним для :has()
.
Синтаксис
[target]:has(selector)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementselector
— необходимый, стандартный или расширенный CSS-селектор
Псевдокласс :has()
выбирает target
-элементы, которые подходят под selector
. Также селектор
может начинаться с комбинатора.
Список селекторов можно задать и в selector
. В этом случае все селекторы в списке будут сопоставляться. В будущем это будет исправлено для <forgiving-relative-selector-list>
как аргумента.
Ограничения :has()
Использование псевдокласса :has()
ограничено для некоторых случаев (2, 3):
- запретить
:has()
внутри псевдоселекторов, принимающих только составные селекторы; - запретить
:has()
после обычных псевдоэлементов.
Нативный псевдокласс :has()
не допускает аргумент :has()
, :is()
, :where()
внутри :has()
, чтобы избежать увеличения сложности аннулирования :has()
(случай 1). Но ранее ExtendedCss не имел такого ограничения, а списки фильтров уже содержат такие правила, поэтому мы не стали добавлять это ограничение в ExtendedCss и разрешили использовать :has()
внутри :has()
, как это было возможно ранее. Чтобы использовать его, просто принудительно используйте ExtendedCss, установив маркер #?#
/#$?#
.
Native implementation does not allow any usage of :scope
inside the :has()
argument ([1], [2]). Тем не менее в списках фильтров есть правила div:has(:scope a)
, которые мы продолжаем поддерживать, просто преобразуя их в div:has(> a)
, как это делалось ранее.
Примеры
div:has(.banner)
выбирает все div
-элементы, которые включают элемент с классом banner
:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<span class="banner">inner element</span>
</div>
div:has(> .banner)
выбирает все div
-элементы, которые включают элемент класса banner
в качестве прямого дочернего элемента div
:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<p class="banner">child element</p>
</div>
div:has(+ .banner)
выбирает все div
-элементы, предшествующие элементу класса banner
, который непосредственно следует за div
и оба являются детьми одного родителя:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected</div>
<p class="banner">adjacent sibling</p>
<span>Not selected</span>
div:has(~ .banner)
выбирает все div
-элементы, предшествующие элементу класса banner
, который следует за div
, но не обязательно сразу, и оба являются детьми одного родителя:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected</div>
<span>Not selected</span>
<p class="banner">general sibling</p>
div:has(span, .banner)
выбирает все элементы div
, которые включают в себя как элемент span
, так и элемент класса banner
:
<!-- HTML code -->
<div>Not selected</div>
<div>Selected
<span>child span</span>
<p class="banner">child .banner</p>
</div>
Синтаксис обратной совместимости для :has()
поддерживается, но не рекомендуется.
Псевдокласс :contains()
Принцип действия псевдокласса :contains()
очень прост: он позволяет выбрать элементы, которые содержат заданный текст или содержимое которых соответствует указанному регулярному выражению. Поддерживаются флаги регулярных выражений.
Псевдокласс :contains()
использует для сопоставления свойство элемента textContent
, а не innerHTML
.
Совместимость с другими псевдоклассами
Синонимы :-abp-contains()
и :has-text()
поддерживаются для лучшей совместимости.
Синтаксис
[target]:contains(match)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementmatch
— требуется, строка или регулярное выражение для соответствия элементуtextContent
. Также поддерживаются флаги регулярных выражений.
Примеры
Для таких DOM:
<!-- HTML code -->
<div>Not selected</div>
<div id="match">Selected as IT contains "banner"</div>
<div>Not selected <div class="banner"></div></div>
the element div#match
can be selected by any of these extended selectors:
! plain text
div:contains(banner)
! регулярное выражение
div:contains(/as .* banner/)
! регулярное выражение с флагами
div:contains(/it .* banner/gi)
Выбран только div
с id=match
, так как следующий элемент не содержит текст, а banner
— это часть кода, а не текст.
Синтаксис обратной совместимости для :contains()
поддерживается, но не рекомендуется.
Псевдокласс :matches-css()
Псевдокласс :matches-css()
позволяет сопоставить элемент по свойствам его текущего стиля. Работа псевдокласса основана на использовании метода Window.getComputedStyle()
.
Синтаксис
[target]:matches-css([pseudo-element, ] property: pattern)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementpseudo-element
— необязательный, допустимый стандартный псевдоэлемент, например,before
,after
,first-line
и т. д.property
— требуется, название CSS-свойства, которое будет проверено у элементаpattern
— требуется, шаблон значений, который использует то же простое сопоставление с подстановочными знаками, что и в основных правилах фильтрации URL-адресов, ИЛИ регулярное выражение. Для этого типа соответствия AdGuard не обращает внимание на регистр. В случае с регулярными выражениями шаблон будет выглядеть так:/regexp/
.
Экранирование и снятие специальных символов
Для нерегулярных выражений паттерны (
,)
,[
,]
должны быть без экранирования, например, :matches-css(background-image:url(data:*))
.
Для регулярных выражений паттерны \
должны быть экранированы, например, :matches-css(background-image: /^url\\("data:image\\/gif;base64.+/)
.
Примеры
Для таких DOM:
<!-- HTML code -->
<style type="text/css">
#matched::before {
content: "Block me"
}
</style>
<div id="matched"></div>
<div id="not-matched"></div>
div
-элементы с псевдоэлементом ::before
и с указанным свойством content
могут быть выбраны любым из этих расширенных селекторов:
! паттерн строки
div:matches-css(before, content: block me)
! паттерн строки с подстановочным знаком
div:matches-css(before, content: block*)
! паттерн регулярного выражения
div:matches-css(before, content: /block me/)
Паттерны регулярных выражений не поддерживают флаги.
Устаревшие псевдоклассы :matches-css-before()
и :matches-css-after()
больше не рекомендуются, но по-прежнему поддерживаются для лучшей совместимости.
Синтаксис обратной совместимости для :matches-css()
поддерживается, но не рекомендуется.
Псевдокласс :matches-attr()
The :matches-attr()
pseudo-class allows selecting an element by its attributes, especially if they are randomized.
Синтаксис
[target]:matches-attr("name"[="value"])
target
— optional, standard or extended CSS selector, can be skipped for checking any elementname
— требуется, простая строка, или строка с подстановочным знаком, или регулярное выражение для сопоставления имени атрибутаvalue
— необязательный, простая строка, или строка с подстановочным знаком, или регулярное выражение для сопоставления значения атрибута
Экранирование специальных символов
For regexp patterns "
and \
should be escaped, e.g. div:matches-attr(class=/[\\w]{5}/)
.
Примеры
div:matches-attr("ad-link")
выбирает элемент div#target1
:
<!-- HTML code -->
<div id="target1" ad-link="1random23-banner_240x400"></div>
div:matches-attr("data-*"="adBanner")
выбирает элемент div#target2
:
<!-- HTML code -->
<div id="target2" data-1random23="adBanner"></div>
div:matches-attr(*unit*=/^click$/)
выбирает элемент div#target3
:
<!-- HTML code -->
<div id="target3" random123-unit094="click"></div>
*:matches-attr("/.{5,}delay$/"="/^[0-9]*$/")
выбирает элемент #target4
:
<!-- HTML code -->
<div>
<inner-random23 id="target4" nt4f5be90delay="1000"></inner-random23>
</div>
Паттерны регулярных выражений не поддерживают флаги.
Псевдокласс :matches-property()
The :matches-property()
pseudo-class allows selecting an element by matching its properties.
Синтаксис
[target]:matches-property("name"[="value"])
target
— optional, standard or extended CSS selector, can be skipped for checking any elementname
— требуется, простая строка, или строка с подстановочным знаком, или регулярное выражение для сопоставления имени свойства элементаvalue
— необязательный, простая строка, или строка с подстановочным знаком, или регулярное выражение для сопоставления значения свойства элемента
Экранирование специальных символов
For regexp patterns "
and \
must be escaped, e.g. div:matches-property(prop=/[\\w]{4}/)
.
Паттерны регулярных выражений поддерживаются в name
для любого свойства в цепочке, например, prop./^unit[\\d]{4}$/.type
.
Примеры
Элемент с такими свойствами:
divProperties = {
id: 1,
check: {
track: true,
unit_2random1: true,
},
memoizedProps: {
key: null,
tag: 12,
_owner: {
effectTag: 1,
src: 'ad.com',
},
},
};
может быть выбран любым из этих расширенных селекторов:
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/)
Чтобы проверить свойства конкретного элемента, сделайте следующее:
- Проверьте элемент страницы или выберите его в Инструментах разработчика браузера во вкладке
Элементы
- Запустите
console.dir($0)
во вкладкеКонсоль
Паттерны регулярных выражений не поддерживают флаги.
Псевдокласс :xpath()
The :xpath()
pseudo-class allows selecting an element by evaluating an XPath expression.
Синтаксис
[target]:xpath(expression)
target
— необязательный, стандартный или расширенный CSS-селекторexpression
— требуется, допустимое XPath выражение
Ограничения :xpath()
target
можно опустить, поэтому использовать его необязательно. Для любого другого псевдокласса это будет означать «применить ко всем узлам DOM», но в случае :xpath()
это просто означает «применить к целым документам», и такое применение значительно замедляет выбор элементов. Вот почему такие правила, как #?#:xpath(expression)
, ограничены поиском внутри тега body
. Например, правило #?#:xpath(//div[@data-st-area=\'Advert\'])
парсится как #?#body:xpath(//div[@data-st- area=\'Advert\'])
.
Расширенные селекторы с target
, определённым как любой селектор, — *:xpath(expression)
— всё ещё можно использовать, но не рекомендуется. Поэтому следует уточнить target
.
Корректно работает только в конце селектора, за исключением псевдокласса :remove().
Примеры
:xpath(//*[@class="banner"])
выбирает элемент div#target1
:
<!-- HTML code -->
<div id="target1" class="banner"></div>
:xpath(//*[@class="inner"]/..)
выбирает элемент div#target2
:
<!-- HTML code -->
<div id="target2">
<div class="inner"></div>
</div>
Псевдокласс :nth-ancestor()
Псевдокласс :nth-ancestor()
позволяет искать n-ного предка по отношению к ранее выбранному элементу.
subject:nth-ancestor(n)
subject
— обязателен. Стандартный или расширенный CSS-селекторn
— обязателен. Число >= 1 и < 256, расстояние до нужного родителя от элемента, выбранногоsubject
Синтаксис
subject:nth-ancestor(n)
subject
— required, standard or extended CSS selectorn
— обязателен. Число >= 1 и < 256, расстояние до нужного родителя от элемента, выбранногоsubject
Ограничения :nth-ancestor()
Псевдокласс :nth-ancestor()
не поддерживается внутри аргумента псевдокласса :not()
.
Примеры
Для таких 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)
выбирает элемент div#target1
, div[class="inner"]:nth-ancestor(3)
выбирает элемент div#target2
.
Псевдокласс :upward()
Псевдокласс :upward()
позволяет искать предка по отношению к ранее выбранному элементу.
Синтаксис
subject:upward(ancestor)
subject
— стандартный или расширенный CSS-селектор, необходимancestor
— требуется, спецификация для предка элемента, выбранногоsubject
, может быть задана как:- число >= 1 и < 256 для указания расстояния до нужного предка, то же, что и
:nth-ancestor()
- стандартный CSS-селектор для поиска ближайшего предка
- число >= 1 и < 256 для указания расстояния до нужного предка, то же, что и
Ограничения :upward()
Псевдокласс :upward()
не поддерживается внутри аргумента псевдокласса :not()
.
Примеры
Для таких 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])
выбирает элемент div#target1
, .inner:upward(div[id])
выбирает элемент div#target2
, .child:upward(1)
выбирает элемент div#target1
, .inner:upward(3)
выбирает элемент div#target2
.
Псевдокласс :remove()
и псевдосвойство remove
Иногда необходимо удалить определённый элемент, а не просто скрыть его или применить какие-либо правила стиля. Для этого можно использовать псевдокласс :remove()
, а также псевдосвойство remove
.
Псевдокласс :remove()
может быть только в конце селектора.
Синтаксис
! pseudo-class
selector:remove()
! псевдосвойство
selector { remove: true; }
subject
— обязателен. Стандартный или расширенный CSS-селектор
Ограничения :remove()
и remove
Псевдокласс :remove()
может корректно работать только в конце селектора.
For applying the :remove()
pseudo-class to any element, the universal selector *
should be used. В противном случае такой расширенный селектор может считаться некорректным, например, .banner > :remove()
недействителен для удаления любого дочернего элемента элемента класса banner
, поэтому он должен выглядеть как .banner > *:remove()
.
Если используется псевдокласс :remove()
или псевдосвойство remove
, все свойства стиля игнорируются, кроме псевдосвойства debug
.
Примеры
div.banner:remove()
div:has(> div[ad-attr]):remove()
div:contains(advertisement) { remove: true; }
div[class]:has(> a > img) { remove: true; }
Rules with the remove
pseudo-property must use #$?#
marker: $
for CSS-style rule syntax, ?
for ExtendedCss syntax.
Псевдокласс :is()
Псевдокласс :is()
позволяет сопоставить любой элемент, который может быть выбран любым из переданных ему селекторов. Некорректные селекторы пропускаются, и псевдокласс работает с допустимыми селекторами без каких-либо ошибок. Наша реализация нативного :is()
псевдокласса.
Синтаксис
[target]:is(selectors)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementselectors
— щадящий список стандартных и расширенных селекторов. For extended selectors, only compound selectors are supported, not complex.
Ограничения :is()
Rules with the :is()
pseudo-class must use the native implementation of :is()
if rules use ##
marker and it is possible, i.e. with no other extended selectors inside. Чтобы принудительно применить правила ExtendedCss с :is()
, используйте маркер #?#
/#$?#
явно.
Если selectors
аргумент псевдокласса :is()
— расширенный селектор, то из-за того, как псевдокласс :is()
реализован в ExtendedCss 2.0, его невозможно применить к верхнему узлу DOM, который является html
, т.е. #?#html:is(<extended-selectors>)
не работает. So if target
is not defined or defined as the universal selector *
, the extended pseudo-class applying is limited to html
's children, e.g. rules #?#:is(...)
and #?#*:is(...)
are parsed as #?#html *:is(...)
. Обратите внимание, что для стандартного аргумента селектора такого ограничения нет, т.е. #?#html:is(.locked)
работает нормально.
Сложные селекторы с расширенными псевдоклассами не поддерживаются в качестве аргумента selectors
для псевдокласса :is()
— разрешены только составные. Ознакомьтесь с примерами, чтобы разобраться в деталях.
Примеры
#container *:is(.inner, .footer)
выбирает только элемент div#target1
:
<!-- HTML code -->
<div id="container">
<div data="true">
<div>
<div id="target1" class="inner"></div>
</div>
</div>
</div>
Из-за ограничений :is(*:not([class]) > .banner)'
не работает, но :is(*:not([class]):has(> .banner))
можно использовать вместо него для выбора элемента div#target2
:
<!-- HTML code -->
<span class="span">text</span>
<div id="target2">
<p class="banner">inner paragraph</p>
</div>
Псевдокласс :not()
Псевдокласс :not()
позволяет выбрать элементы, которые не соответствуют селекторам, переданным в качестве аргумента. Неправильные селекторы аргументов не допускаются, и будет выдана ошибка. Наша реализация псевдокласса :not()
.
Синтаксис
[target]:not(selectors)
target
— optional, standard or extended CSS selector, can be skipped for checking any elementselectors
— список стандартных или расширенных селекторов
Ограничения :not()
Rules with the :not()
pseudo-class must use the native implementation of :not()
if rules use ##
marker and it is possible, i.e. with no other extended selectors inside. Чтобы принудительно применить правила ExtendedCss с :not()
, используйте маркер #?#
/#$?#
явно.
Если selectors
аргумент псевдокласса :not()
— расширенный селектор, то из-за того, как псевдокласс :not()
реализован в ExtendedCss 2.0, его невозможно применить к верхнему узлу DOM, который является html
, т.е. #?#html:not(<extended-selectors>)
не работает. So if target
is not defined or defined as the universal selector *
, the extended pseudo-class applying is limited to html
's children, e.g. rules #?#:not(...)
and #?#*:not(...)
are parsed as #?#html *:not(...)
. Обратите внимание, что для стандартного аргумента селектора такого ограничения нет, т.е. #?#html:not(.locked)
работает нормально.
Псевдокласс :not()
рассматривается как стандартный псевдокласс CSS внутри аргумента псевдокласса :upward()
, поскольку :upward()
поддерживает только стандартные селекторы.
«Восходящие» псевдоклассы :nth-ancestor()
и :upward()
не поддерживаются внутри аргумента selectors
для псевдокласса :not()
.
Примеры
#container > *:not(h2, .text)
выбирает только элемент div#target1
:
<!-- HTML code -->
<div id="container">
<h2>Header</h2>
<div id="target1"></div>
<span class="text">text</span>
</div>
Псевдокласс :if-not()
(удалён)
Псевдокласс :if-not()
удалён и больше не поддерживается. Правила с ним не работают.
Этот псевдокласс изначально был сокращением для :not(:has())
. Он поддерживался ExtendedCss для лучшей совместимости с подписками на некоторые фильтры.
Приоритет косметических правил
То, как применяются правила скрытия элементов и CSS-правила, зависит от платформы.
В AdGuard для Windows, Mac и Android мы используем таблицу стилей, встроенную в страницу. Приоритет у косметических правил такой же, как и у любых других таблиц стилей CSS на сайтах. Но есть ограничение: правила скрытия элементов и CSS-правила не могут обходить встроенные стили. В таких случаях рекомендуется использовать расширенные селекторы или HTML-фильтрацию.
В Браузерном расширении AdGuard используются так называемые «пользовательские таблицы стилей». Их приоритет выше, даже чем у встроенных стилей.
Расширенные CSS-селекторы используют для работы JavaScript и добавляют встроенные стили сами, поэтому могут игнорировать любой стиль.
Правила фильтрации HTML
В большинстве случаев для фильтрации рекламы достаточно базовых и косметических правил. Но иногда необходимо изменить HTML-код самой страницы перед её загрузкой. Для этого применяются правила фильтрации HTML-контента. Они позволяют указать, какие HTML-элементы необходимо вырезать из страницы перед тем, как страница попадёт в браузер.
Правила HTML-фильтрации поддерживаются в AdGuard для Windows, Mac, Android и Браузерном расширении AdGuard для Firefox. Такие правила не работают в расширениях для других браузеров, потому что они не могут модифицировать содержимое страниц на сетевом уровне.
Синтаксис
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
— имя элемента в нижнем регистре, например,div
илиscript
.domains
— ограничение на домены, на страницах которых будет применено правило. Те же принципы, что и в синтаксисе правил скрытия элементов.attributes
— список атрибутов, ограничивающих выбор элементов.name
— имя атрибута,value
— подстрока, которая содержится в значении атрибута.pseudoName
— имя псевдокласса.pseudoArgs
— аргументы псевдокласса, записанного в виде функции.combinator
— оператор, который работает аналогично CSS-комбинатору дочерних элементов: селектор справа от комбинатора будет относиться только к элементу, прямой родительский элемент которого соответствует селектору слева от комбинатора.
Примеры
HTML-код:
<script data-src="/banner.js"></script>
Правило:
example.org$$script[data-src="banner"]
Это правило удалит из кода страниц все элементы script
со значением data-src
, содержащим подстроку banner
. При этом правило будет работать только для домена example.org
и всех его поддоменов.
Специальные атрибуты
Помимо обычных атрибутов, значение которых проверяется у каждого элемента, существует набор специальных атрибутов правила, которые изменяют способ работы правила. Ниже мы перечислим все эти атрибуты:
tag-content
В будущем этот специальный атрибут может перестать поддерживаться. Предпочтительнее использовать псевдокласс :contains()
там, где это возможно.
Пожалуй, наиболее часто используемый специальный атрибут. Он ограничивает выбор теми элементами, внутренний HTML-код которых (innerHTML) содержит указанную подстроку.
You must use ""
to escape "
, for instance: $$script[tag-content="alert(""this is ad"")"]
Например, рассмотрим такой HTML-код:
<script type="text/javascript">
document.write('<div>banner text</div>" />');
</script>
Следующее правило удалит все script
элементы с подстрокой banner
в их коде:
$$script[tag-content="banner"]
Специальный атрибут tag-content
не должен появляться в селекторе слева от комбинатора >
.
wildcard
В будущем этот специальный атрибут может перестать поддерживаться. Предпочтительнее использовать псевдокласс :contains()
там, где это возможно.
Этот специальный атрибут работает почти как tag-content
и позволяет проверить внутренний HTML-код элемента. Правило проверит, удовлетворяет ли HTML-код элемента заданному шаблону поиска.
You must use ""
to escape "
, for instance: $$script[wildcard=""banner""]
Например: $$script[wildcard="*banner*text*"]
It checks if the element code contains the two consecutive substrings banner
and text
.
Специальный атрибут wildcard
не должен появляться в селекторе слева от комбинатора >
.
max-length
В будущем этот специальный атрибут может перестать поддерживаться. Предпочтительнее использовать псевдокласс :contains()
там, где это возможно.
Задает максимальную длину содержимого HTML-элемента. Если этот параметр задан и длина содержимого превышает заданное значение, правило не применяется к элементу.
Значение по умолчанию
Если этот параметр не задан, то max-length
считается равным 8192.
Например:
$$div[tag-content="banner"][max-length="400"]
Это правило удалит все элементы div
, код которых содержит подстроку banner
и длина которых не превышает 400
символов.
Специальный атрибут max-length
не должен появляться в селекторе слева от комбинатора >
.
min-length
В будущем этот специальный атрибут может перестать поддерживаться. Предпочтительнее использовать псевдокласс :contains()
там, где это возможно.
Задаёт минимальную длину содержимого HTML-элемента. Если этот параметр задан, и длина содержимого меньше заданного значения — правило не применяется к элементу.
Например:
$$div[tag-content="banner"][min-length="400"]
Это правило удалит все элементы div
, код которых содержит подстроку banner
и длина которых превышает 400
символов.
Специальный атрибут min-length
не должен появляться в селекторе слева от комбинатора >
.
Псевдоклассы
:contains()
Синтаксис
:contains(текст без кавычек)
или
:contains(/reg(ular)?ex(pression)?/)
:-abp-contains()
и :has-text()
являются синонимами :contains()
.
Псевдокласс :contains()
поддерживается в AdGuard для Windows, Mac и Android с CoreLibs версии 1.13 или выше.
Требует, чтобы внутренний HTML-код элемента содержал указанный текст или соответствовал указанному регулярному выражению.
Псевдокласс :contains()
не должен появляться в селекторе слева от комбинатора >
.
Исключения
По аналогии с правилами скрытия, существует специальный тип правил, отключающий действие выбранного правила HTML-фильтрации для определённых доменов. Синтаксис правил-исключений такой же, только маркер $$
заменяется на $@$
.
Например, в фильтре есть правило:
$$script[tag-content="banner"]
Если вы хотите отключить его для домена example.com
, вы можете создать правило исключения:
example.com$@$script[tag-content="banner"]
В некоторых случаях может потребоваться отключение всех запрещающих правил. Например, на время тестирования. Для этого воспользуйтесь правилом исключения без указания домена.
$@$script[tag-content="banner"]
Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия невозможно. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.
Правила JavaScript
AdGuard поддерживает специальный тип правил, позволяющий вставить любой javascript-код на страницы сайтов.
Мы настоятельно рекомендуем использовать скриптлеты вместо JavaScript-правил везде, где это возможно. JS-правила должны помочь в процессе отладки, но в качестве долгосрочного решения следует использовать скриптлеты.
Синтаксис
rule = [domains] "#%#" script
domains
— ограничение на домены, на страницах которых будет применено правило. Строится по тем же правилам, что и в случае правил скрытия элементов.script
— произвольный javascript-код в одну строку.
Примеры
example.org#%#window.__gaq = undefined;
выполняет кодwindow.__gaq = undefined;
на всех страницах сайтаexample.org
и всех его поддоменах.
Исключения
По аналогии с правилами скрытия, существует специальный тип правил, отключающий действие выбранного javascript-правила фильтрации для определённых доменов. Синтаксис правил-исключений такой же, только маркер #%#
заменяется на #@%#
.
Например, в фильтре есть правило:
#%#window.__gaq = undefined;
Если вы хотите отключить его для домена example.com
, вы можете создать правило исключения:
example.com#@%#window.__gaq = undefined;
В некоторых случаях может потребоваться отключение всех запрещающих правил. Например, на время тестирования. Для этого воспользуйтесь правилом исключения без указания домена.
#@%#window.__gaq = undefined;
Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия невозможно. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.
Правила JavaScript можно использовать только в доверенных фильтрах.
JavaScript-правила не поддерживаются в AdGuard Content Blocker.
Правила скриптлета
Скриптлет — это функция JavaScript с расширенными возможностями для блокировки контента. Такие функции могут использоваться в декларативной манере в правилах фильтрации AdGuard.
AdGuard поддерживает множество различных скриптлетов. Чтобы добиться совместимости между различными блокировщиками, мы также поддерживаем синтаксис uBO и ABP.
Синтаксис
rule = [domains] "#%#//scriptlet(" scriptletName arguments ")"
scriptletName
(обязательно) — это имя скриптлета из библиотеки скриптлетов AdGuardarguments
(опционально) — это список аргументов в форматеstring
(другие типы аргументов не поддерживаются)
Примеры
example.org#%#//scriptlet("abort-on-property-read", "alert")
Это правило применится на страницах домена example.org
и его поддоменов и выполнит скриптлет abort-on-property-read
с параметром alert
.
Подробнее об отладке скриптлетов.
Больше информации о скриптлетах можно найти на GitHub.
Скриптлеты не поддерживаются в AdGuard Content Blocker.
Доверенные скриптлеты
Доверенные скриптлеты — это скриптлеты с расширенной функциональностью. У них тот же синтаксис и ограничения. У имён доверенных скриптлетов есть префикс trust-
, например, trust-set-cookie
, чтобы их было легко отличить от обычных скриптлетов.
Доверенные скриптлеты несовместимы с другими блокировщиками рекламы, кроме AdGuard.
Доверенные скриптлеты можно использовать только в доверенных фильтрах.
Доверенные скриптлеты не поддерживаются в AdGuard Content Blocker.
Подробнее об отладке скриптлетов
Больше информации о доверенных скриптлетах можно найти на GitHub.
Модификаторы для небазовых правил
Поведение любого правила можно изменить, используя модификаторы, описанные ниже.
Синтаксис {#non-basic-rules-modifiers-syntax}
rule = "[$" modifiers "]" [rule text]
modifiers = modifier0[, modifier1[, ...[, modifierN]]]
modifier
— набор модификаторов, описанных ниже.rule text
— правило, которое нужно модифицировать.
Например: [$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). Используйте \
, чтобы экранировать их. Например, экранированная скобка выглядит так: \]
.
Модификатор \ Продукты | Приложения CoreLibs | AdGuard для Chromium | AdGuard для Firefox | AdGuard для iOS | AdGuard для Safari | AdGuard Content Blocker |
---|---|---|---|---|---|---|
$app | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
$domain | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$path | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$url | ✅ | ⏳ | ⏳ | ❌ | ❌ | ❌ |
- ✅ — полностью поддерживается
- ⏳ — реализован или планируется к реализации, но пока недоступен ни в одном продукте
- ❌ — не поддерживается
$app
Модификатор $app
ограничивает действие правила до конкретного приложения или списка приложений. Поведение и синтаксис модификатора полностью совпадают с соответствующим модификатором $app
для базовых правил.
Примеры
[$app=org.example.app]example.com##.textad
hides adiv
with the classtextad
atexample.com
and all subdomains in requests sent from theorg.example.app
Android app.[$app=~org.example.app1|~org.example.app2]example.com##.textad
hides adiv
with the classtextad
atexample.com
and all subdomains in requests sent from any app exceptorg.example.app1
andorg.example.app2
.[$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300')
применяет скриптлетprevent-setInterval
только в браузере Safari на Mac.[$app=org.example.app]#@#.textad
отключает все правила##.textad
для всех доменов при использованииorg.example.app
.
Такие правила с модификатором $app
поддерживаются AdGuard для Windows, Mac и Android.
$domain
Модификатор $domain
ограничивает область действия правила списком доменов и их поддоменов. Поведение и синтаксис модификатора полностью совпадают с соответствующим модификатором $domain
для базовых правил.
Примеры
[$domain=example.com]##.textad
— hides adiv
with the classtextad
atexample.com
and all subdomains.[$domain=example.com|example.org]
скроет элемент с атрибутомid
равнымadblock
на доменахexample.com
,example.org
и всех их поддоменах.[$domain=~example.com]##.textad
скроет элементыdiv
с классомtextad
на всех доменах, кромеexample.com
и всех его поддоменов.
Существует два способа указать доменные ограничения для косметических правил:
- «классический»: обозначить ограничение на домены перед маской и атрибутами правила:
example.com##.textad
; - с помощью модификаторов: обозначить ограничение на домены через модификатор
$domain
:[$domain=example.com]##.textad
.
Правила, нарушающие эти ограничения, считаются недействительными. So, for example, the rule [$domain=example.org]example.com##.textad
will be ignored.
Правила с модификатором $domain
поддерживаются в AdGuard для Windows, Mac, Android и Браузерном расширении AdGuard для Chrome, Firefox и Edge.
$path
Модификатор $path
ограничивает область применения правила определёнными местами или страницами на сайтах.
Синтаксис
$path ["=" pattern]
pattern
(опциональный) — это маска пути, которой ограничено правило. Его синтаксис и поведение почти такие же, как в шаблоне базовых правил. Вы также можете использовать специальные символы, кроме ||
, который в этом случае не имеет смысла (см. примеры ниже).
Если для $path
не задан pattern
, правило будет применяться только на главной странице сайта.
Модификатор $path
также соответствует строке запроса.
Модификатор $path
поддерживает регулярные выражения так же, как и базовые правила.
Примеры
[$path=page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
or/sub/page.html
or/another_page.html
[$path=/page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
or/sub/page.html
of any domain but not at/another_page.html
[$path=|/page.html]##.textad
hides adiv
with the classtextad
at/page.html
or/page.html?<query>
of any domain but not at/sub/page.html
[$path=/page.html|]##.textad
hides adiv
with the classtextad
at/page.html
or/sub/page.html
of any domain but not at/page.html?<query>
[$path=/page*.html]example.com##.textad
hides adiv
with the classtextad
at/page1.html
or/page2.html
or any other path matching/page<...>.html
ofexample.com
[$path]example.com##.textad
hides adiv
with the classtextad
at the main page ofexample.com
[$domain=example.com,path=/page.html]##.textad
hides adiv
with the classtextad
atpage.html
ofexample.com
and all subdomains but not atanother_page.html
[$path=/\\/(sub1|sub2)\\/page\\.html/]##.textad
hides adiv
with the classtextad
at both/sub1/page.html
and/sub2/page.html
of any domain (please note the escaped special characters)
Правила с модификатором $path
не поддерживаются в AdGuard Content Blocker.
$url
Модификатор $url
ограничивает действие правила запросами, URL которых соответствует указанной маске.
Синтаксис
url = pattern
где pattern
— маска адреса, синтаксис которой соответствует маске адреса pattern
базовых правил за исключением того, что некоторые символы должны быть экранированы. Специальные символы и регулярные выражения также поддерживаются.
Примеры
[$url=||example.com/content/*]##div.textad
hides adiv
with the classtextad
at addresses likehttps://example.com/content/article.html
and evenhttps://subdomain.example.com/content/article.html
.[$url=||example.org^]###adblock
скрывает элемент с атрибутомid
равнымadblock
в запросах кexample.org
и всем его поддоменам.[$url=/\[a-z\]+\\.example\\.com^/]##.textad
скрываетdiv
с классомtextad
в запросах ко всем доменам, соответствующим регулярному выражению[a-z]+\.example\.com^
.
Правила с модификатором $url
поддерживаются в AdGuard для Windows, Mac и Android с CoreLibs версии 1.11 или выше.
Информация для разработчиков фильтров
Если вы разрабатываете сторонний фильтр, известный AdGuard, вам может быть интересна информация, представленная в этом разделе. Имейте в виду, что подсказки будут применяться только к зарегистрированным фильтрам. Фильтр считается зарегистрированным и известным AdGuard, если он присутствует в перечне известных фильтров. Если вы хотите зарегистрировать свой фильтр, направьте запрос в репозиторий AdGuardFilters.
Директивы препроцессора
Мы предоставляем несколько директив препроцессора, которые могут быть использованы разработчиками фильтров для улучшения совместимости с различными блокировщиками рекламы. Директивы могут:
- включать содержимое отдельного файла в фильтр
- применять правила в зависимости от типа блокировщика
- уточнять блокировщик контента для применения правил в Safari
Любая ошибка в директиве препроцессора приведёт к невозможности обновить фильтр, как если бы URL фильтра был недоступен.
Препроцессорные директивы можно использовать в пользовательских правилах или фильтрах.
Включение файла
Директива !#include
позволяет включать в фильтр содержимое заданного файла. Она поддерживает только файлы из того же источника, чтобы удостовериться, что разработчик фильтров является владельцем указанного файла. Включённый файл также может содержать директивы препроцессора (даже другие!#include
-директивы). Блокировщики должны принимать во внимание случай рекурсивного использования !#include
и внедрять защитный механизм.
Синтаксис
!#include file_path
где file_path
— абсолютный или относительный путь к файлу одного и того же источника, который должен быть включён.
The files must originate from the same domain but may be located in a different folder.
Если включённый файл не найден или недоступен, не будут работать обновления всего фильтра.
Для локальных собственных фильтров ограничение на тот же источник не распространяется.
Примеры
URL фильтра: https://example.org/path/filter.txt
! Корректный (тот же источник):
!#include https://example.org/path/includedfile.txt
!
! Корректный (относительный путь):
!#include /includedfile.txt
!#include ../path2/includedfile.txt
!
! Некорректный (другой источник):
!#include https://domain.com/path/includedfile.txt
Условия
Разработчики фильтров могут использовать условия, чтобы подставлять нужные правила, в зависимости от типа блокировщика. A conditional directive beginning with an !#if
directive must explicitly be terminated with an !#endif
directive. Условия поддерживают все основные логические операторы.
Есть два возможных сценария:
Если блокировщик рекламы встречает директиву
!#if
и не встречает директиву!#else
, то он компилирует код между директивами!#if
и!#endif
только в том случае, если указанное условие истинно.Если существует директива
!#else
, код между!#if
и!#else
будет скомпилирован, если условие истинно; в противном случае будет скомпилирован код между!#else
и!#endif
.
Пробелы имеют значение. !#if
— это корректная директива, в то время как !# if
— не корректная.
Синтаксис
!#if (conditions)
rules_list
!#endif
или
!#if (условия)
true_conditions_rules_list
!#else
false_conditions_rules_list
!#endif
где:
!#if (условия)
— начало блока при выполнении условийconditions
— точно так же, как и в случае с некоторыми популярными языками программирования, условия препроцессинга основаны на константах, объявляемых блокировщиками. Разработчики блокировщиков самостоятельно определяют, какие именно константы объявлять. Возможные значения:adguard
объявляется всегда; даёт разработчикам фильтров понять, что это один из продуктов AdGuard; должно быть достаточно в 95% случаев- специфичные для конкретных продуктов константы, которые нужны в редких случаях, когда правило должно работать (или не работать — тогда перед константой используйте
!
) только для конкретного продукта:adguard_app_windows
— AdGuard для Windowsadguard_app_mac
— AdGuard для Macadguard_app_android
— AdGuard для Androidadguard_app_ios
— AdGuard для iOSadguard_ext_safari
— AdGuard для Safariadguard_ext_chromium
— Браузерное расширение AdGuard для Chrome (и браузеры на основе Chrome, например, новый Microsoft Edge)adguard_ext_firefox
— Браузерное расширение AdGuard для Firefoxadguard_ext_edge
— Браузерное расширение AdGuard для Edge Legacyadguard_ext_opera
— Браузерное расширение AdGuard для Operaadguard_ext_android_cb
— AdGuard Content Blocker для мобильных браузеров Samsung и Яндексext_ublock
— особый случай; эта константа объявляется, когда версия фильтра для uBlock компилируется при помощи FiltersRegistrycap_html_filtering
— продукты, поддерживающие правила HTML-фильтрации: AdGuard для Windows, AdGuard для Mac и AdGuard для Android
!#else
— начало блока, когда условия ложныrules_list
,true_conditions_rules_list
,false_conditions_rules_list
— списки правил!#endif
— конец блока
Примеры
! для всех продуктов AdGuard, кроме AdGuard для Safari
!#if (adguard && !adguard_ext_safari)
||example.org^$third-party
domain.com##div.ad
!#endif
! директивы также можно совмещать
!#if (adguard_app_android)
!#include /androidspecific.txt
!#endif
!#if (adguard && !adguard_ext_safari)
! для всех продуктов AdGuard, кроме AdGuard для Safari
||example.org^$third-party
domain.com##div.ad
!#else
! только для AdGuard для Safari
||subdomain.example.org^$third-party
!#endif
Директива !#else
поддерживается FiltersDownloader 1.1.20 или более поздней версии.
Он уже поддерживается для списков фильтров, составленных с помощью FiltersRegistry, но всё ещё может не поддерживаться продуктами AdGuard при добавлении списка фильтров с !#else
в качестве пользовательского. Следующие продукты будут поддерживать его в указанных версиях или более поздних версиях:
- AdGuard для Windows, Mac и Android под управлением CoreLibs 1.13;
- Браузерное расширение AdGuard 4.2.208;
- AdGuard v1.11.16 for Safari.
Правила фильтрации в Safari
Лимит каждого блокировщика контента Safari — 150 000 активных правил. Но в AdGuard для Safari и AdGuard для iOS мы разделили правила на 6 блокировщиков контента, тем самым увеличив лимит правил до 900 000.
Какие фильтры содержатся в каждом блокировщике контента:
- AdGuard General — Блокировка рекламы, Языковые
- AdGuard Privacy — Антитрекинг
- AdGuard Social — Виджеты социальных сетей, Раздражители
- AdGuard Security — Безопасность
- AdGuard Other — Другие
- AdGuard Custom — Собственные
Пользовательские правила и белый список добавляются в каждый блокировщик контента.
Основной недостаток использования нескольких блокировщиков контента в том, что правила из разных блокировщиков применяются независимо друг от друга. На правила блокировки это не влияет, но с правилами разблокировки могут быть проблемы. Если правило блокировки есть в одном блокировщике контента, а исключение — в другом, то исключение не сработает. Разработчики фильтров используют !#safari_cb_affinity
, чтобы указать, к какому блокировщику контента принадлежат правила.
Синтаксис
!#safari_cb_affinity(content_blockers)
rules_list
!#safari_cb_affinity
где:
!#safari_cb_affinity(content_blockers)
— начало блокаcontent_blockers
— список блокировщиков контента, разделённых запятой. Возможные значения:general
— блокировщик контента AdGuard Generalprivacy
— блокировщик контента AdGuard Privacysocial
— блокировщик контента AdGuard Socialsecurity
— блокировщик контента AdGuard Securityother
— блокировщик контента AdGuard Othercustom
— блокировщик контента AdGuard Customall
— специальное ключевое слово, которое означает, что правила должны быть включены во все блокировщики контента
rules_list
— список правил!#safari_cb_affinity
— конец блока
Примеры
! чтобы не скрывать указанный элемент, который скрывается Базовым фильтром:
!#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
Подсказки
Hint (подсказка) — это специальный комментарий, инструкция к компилятору фильтров, используемому на стороне сервера (см. FiltersRegistry).
Синтаксис
!+ HINT_NAME1(PARAMS) HINT_NAME2(PARAMS)
Можно применить несколько подсказок.
Подсказка NOT_OPTIMIZED
Для каждого фильтра AdGuard существуют две версии: полная и оптимизированная. Оптимизированная версия намного легче и не содержит правил, которые не используются вообще или используются редко.
Частота использования правил определяется собранной статистикой по рекламным фильтрам. Но оптимизация основана также на исходной конфигурации для каждого фильтра. Например, вот так это выглядит для Базового фильтра:
"filter": Базовый фильтр AdGuard,
"percent": 30,
"minPercent": 20,
"maxPercent": 40,
"strict": true
где:
- filter — идентификатор фильтра
- percent — ожидаемый процент оптимизации
~= (количество правил в оптимизированном фильтре) / (количество правил в исходном фильтре) * 100
- minPercent — нижняя граница значения
percent
- maxPercent — верхняя граница значения
percent
- Strict — если
percent < minPercent
илиpercent > maxPercent
и включён режим Strict, то компиляция фильтра должна завершиться неудачно, в противном случае должны использоваться оригинальные правила
Другими словами, percent
— это «уровень сжатия». Например, для Базового фильтра он настроен на 40%. Это означает, что алгоритм оптимизации должен убрать 60% правил.
В итоге, вот так выглядят версии Базового фильтра для Браузерного расширения AdGuard для Chrome:
- полная: https://filters.adtidy.org/extension/chromium/filters/2.txt
- оптимизированная: https://filters.adtidy.org/extension/chromium/filters/2_optimized.txt
Если вы хотите добавить правило, которое не должно удаляться при оптимизации, используйте подсказку NOT_OPTIMIZED
:
!+ NOT_OPTIMIZED
||example.org^
А такое правило не будет оптимизировано только для AdGuard для Android:
!+ NOT_OPTIMIZED PLATFORM(android)
||example.org^
Подсказки PLATFORM
и NOT_PLATFORM
Записи этого типа позволяют указывать платформу, для которой применяется правило. Ниже представлен список используемых платформ и ссылки на Базовый фильтр для каждой из них:
windows
— AdGuard для Windows — https://filters.adtidy.org/windows/filters/2.txtmac
— AdGuard для Mac — https://filters.adtidy.org/mac_v2/filters/2.txtandroid
— AdGuard для Android — https://filters.adtidy.org/android/filters/2.txtios
— AdGuard для iOS — https://filters.adtidy.org/ios/filters/2.txtext_chromium
— Браузерное расширение AdGuard для Chrome — https://filters.adtidy.org/extension/chromium/filters/2.txtext_ff
— Браузерное расширение AdGuard для Firefox — https://filters.adtidy.org/extension/firefox/filters/2.txtext_edge
— Браузерное расширение AdGuard для Edge — https://filters.adtidy.org/extension/edge/filters/2.txtext_opera
— Браузерное расширение AdGuard для Opera — https://filters.adtidy.org/extension/opera/filters/2.txtext_safari
— AdGuard для Safari — https://filters.adtidy.org/extension/safari/filters/2.txtext_android_cb
— AdGuard Content Blocker — https://filters.adtidy.org/extension/android-content-blocker/filters/2.txtext_ublock
— uBlock Origin — https://filters.adtidy.org/extension/ublock/filters/2.txt
Примеры
Это правило будет действовать только в AdGuard для 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^
Отладка правил фильтрации
Хоть самые простые правила фильтрации и возможно придумать «в голове», для чего-то чуть более сложного вам потребуются дополнительная помощь в их отладке и повторении. Есть инструменты, которые помогут вам в этом. Вы можете использовать «Инструменты разработчика» в Chrome и их аналоги в других браузерах, но большинство продуктов AdGuard предоставляют и другой инструмент — Журнал фильтрации.
Журнал фильтрации
Журнал фильтрации — продвинутый инструмент, который полезен в основном разработчикам фильтров. В нём отображаются все веб-запросы, проходящие через AdGuard, даётся исчерпывающая информация по каждому из них, предлагаются различные опции сортировки и другие полезные возможности.
В зависимости от того, какой продукт AdGuard вы используете, журнал фильтрации может находиться в разных местах.
- В AdGuard для Windows вы найдёте его во вкладке настроек Антибаннер или через меню трея
- В AdGuard для Mac он располагается в разделе Настройки → Дополнительно → Журнал фильтрации
- В AdGuard для Android его можно найти в разделе Статистика → Недавняя активность. Доступ к недавней активности также можно получить из Помощника
- В Браузерном расширении AdGuard он находится во вкладке настроек Дополнительно, а также доступен по клику правой кнопкой мыши по иконке расширения. Only Chromium- and Firefox-based web browsers show applied element hiding rules (including CSS, ExtCSS) and JS rules and scriptlets in their Filtering logs
В AdGuard для iOS и в AdGuard для Safari Журнал фильтрации отсутствует из-за особенностей реализации блокировщиков контента в Safari. AdGuard сам не видит веб-запросы и поэтому не может отображать их.
Режим отладки селекторов
Иногда может понадобиться проверить производительность того или иного селектора или таблицы стилей. Чтобы сделать это без непосредственного взаимодействия с JavaScript, вы можете использовать свойство стиля debug
. Когда ExtendedCss
встречает это свойство, он включает режим отладки для конкретного селектора или для всех селекторов, в зависимости от значения debug
.
Откройте консоль браузера, находясь на веб-странице, чтобы посмотреть статистику по времени, затраченному на применение селектора(-ов). В режиме отладки следующая статистика отображается в виде объекта, где каждый из отлаживаемых селекторов является ключом, а значение — объектом с такими свойствами:
Всегда выводится:
selectorParsed
— окончательный текст селектора после парсингаtimings
— список узлов DOM, соответствующих селекторуappliesCount
— общее количество раз, когда на странице был применён селекторappliesTimings
— время, которое ушло на применение селектора на странице, для каждого из случаев применения этого селектора (в миллисекундах)meanTiming
— среднее время, ушедшее на применение селектора на страницеstandardDeviation
— стандартное отклонениеtimingsSum
— общее время, ушедшее на все применения селектора на текущей странице
Выводится только для удалённых псевдоэлементов:
removed
— flag to signal if elements were removed
Выводится, если элементы не удалены:
matchedElements
— список узлов DOM, соответствующих селекторуstyleApplied
— объявление обработанного стиля правила, связанного с селектором
Примеры
Отладка конкретного селектора:
Когда значение свойства debug
равно true
, информация только по этому селектору будет отображена в консоли браузера.
#$?#.banner { display: none; debug: true; }
Включение глобальной отладки:
Когда значение свойства debug
равно global
, в консоли будет отображаться информация по всем CSS-селекторам, которые были применены на данной странице, для всех правил из любого из включённых фильтров.
#$?#.banner { display: none; debug: global; }
Тестирование расширенных селекторов без AdGuard
ExtendedCss может быть выполнен на любой странице без использования какого-либо продукта AdGuard. Для этого скопируйте и запустите следующий код в консоли браузера:
!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");
В качестве альтернативы установите пользовательский скрипт ExtendedCssDebugger.
Теперь вы можете использовать ExtendedCss
глобально и запустить его метод query()
как Document.querySelectorAll()
.
Примеры
const selector = 'div.block:has=(.header:matches-css(after, content: Ads))';
// массив HTMLElements, соответствующих `selector`, должен быть возвращён
ExtendedCss.query(selector);
Отладка скриптлетов
Если вы используете браузерное расширение AdGuard и хотите отладить правило скриптлета или доверенного скриптлета, то можете получить дополнительную информацию, открыв журнал фильтрации. В этом случае скриптлеты перейдут в режим отладки и будут записывать больше информации в браузерную консоль.
Следующие скриптлеты разработаны специально для отладки:
debug-current-inline-script
debug-on-property-read
debug-on-property-write
log-addEventListener
log-on-stack-trace
log-eval
log
Следующие скриптлеты тоже могут быть использованы для отладки:
json-prune
prevent-fetch
prevent-requestAnimationFrame
prevent-setInterval
prevent-setTimeout
prevent-window-open
со специальным параметромreplacement
prevent-xhr
trusted-replace-fetch-response
trusted-replace-xhr-response
Легенда таблиц совместимости
Краткие обозначения продуктов
Приложения CoreLibs
— AdGuard для Windows, AdGuard для Mac и AdGuard для AndroidAdGuard для Chromium
— Браузерное расширение AdGuard для Chrome и других браузеров на основе Chromium, таких как Microsoft Edge и OperaAdGuard для Firefox
— Браузерное расширение AdGuard для FirefoxAdGuard для iOS
— AdGuard для iOS и AdGuard Pro для iOS (для мобильного браузера Safari)AdGuard для Safari
— AdGuard для веб-браузера SafariAdGuard Content Blocker
— Content Blocker для мобильных браузеров Android: Samsung Internet и Яндекс Браузер
Краткие обозначения совместимости
- ✅ — полностью поддерживается
- ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
- 🧩 — может быть уже реализован в nightly или бета-версиях, но пока не поддерживается в релизных версиях
- ⏳ — реализован или планируется к реализации, но пока недоступен ни в одном продукте
- ❌ — не поддерживается
- 👎 — устарел; всё ещё поддерживается, но в будущем будет удалён
- 🚫 — удалён и больше не поддерживается