Фильтр — это набор правил фильтрации рекламного контента (баннеров, всплывающих окон и тому подобного). Вместе с AdGuard поставляется набор стандартных фильтров, создаваемых нами. Они постоянно дорабатываются и дополняются, и, как мы надеемся, удовлетворяют требованиям большинства пользователей.
Вместе с тем, AdGuard позволяет создать ваш собственный пользовательский фильтр, используя те же самые правила, которые используем мы в наших фильтрах.
Для описания синтаксиса правил мы используем Augmented BNF for Syntax Specifications, но мы не всегда строго следуем этой спецификации.
Синтаксис правил AdGuard изначально основан на синтаксисе правил Adblock Plus, но расширяет его, добавляя новые типы правил для улучшения фильтрации. Часть информации в этой статье об общих для ABP и AdGuard типах правил взята из этой статьи.
Любое правило, начинающееся с восклицательного знака, содержит комментарий. Оно отображается в списке правил серым цветом. 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/
Это правило блокирует:
http://example.org/
Это правило не блокирует:
https://example.org/banner/img
Правила фильтрации поддерживают множество модификаторов, которые позволяют вам точно настраивать поведение правила. Вот пример правила с некоторыми простыми модификаторами.
Это правило блокирует:
http://example.org/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 Подробнее.
Расширенный CSS позволяет разработчикам фильтров справляться с гораздо более сложными случаями. Однако, чтобы использовать эти расширенные правила, вы должны хорошо понимать, что такое CSS.
Имя | CSS-селектор | Описание |
---|---|---|
ID selector | #banners |
Соответствует всем элементам с атрибутом id равным banners .![]() |
Class selector | .banners |
Соответствует всем элементам типа class содержащих banners .![]() |
Attribute selector | div[class="banners"] |
Соответствует всем div элементам с class равным banners .![]() |
Attribute substring selector | div[class^="advert1"] |
Соответствует всем div элементам класс class которых начинается с advert1 строки.![]() |
Attribute substring selector | div[class$="banners_ads"] |
Соответствует всем div элементам class которых заканчивается на banners_ads .![]() |
Attribute substring selector | a[href^="http://example.com/"] |
Соответствует всем ссылкам загруженным с http://example.com/ ![]() |
Attribute selector | a[href="http://example.com/"] |
Соответствует всем ссылкам конкретно http://example.com/ .![]() |
Так называемые "Базовые правила" — самый простой вид правил. Эти правила предназначены для блокировки запросов на определенный адрес. Либо, при наличии специального маркера @@
в начале правила, для разблокировки запроса. Основной принцип для этого типа правил достаточно прост: необходимо указать адрес и дополнительные параметры, которые ограничивают или расширяют область действия правила.
Подзапросы
Базовые правила, блокирующие запросы, применяются только к подзапросам. То есть, они не будут блокировать загрузку страницы в браузере.
Статус ответа
Браузер определяет заблокированный подзапрос как выполненный с ошибкой.
rule = ["@@"] pattern [ "$" modifiers ]
modifiers = [modifier0, modifier1[, ...[, modifierN]]]
pattern
— маска адреса. URL каждого запроса сопоставляется с этой маской. В шаблоне вы можете использовать некоторые специальные символы, описание которых будет дано ниже. Обратите внимание, что AdGuard обрезает URL до длины 4096 символов, чтобы ускорить процесс подбора и избежать проблем с длинными URL.@@
— маркер, который используется для обозначения правил-исключений. С такого маркера должны начинаться правила, отключающие фильтрацию для запроса.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
.Визуальное представление. Также советуем ознакомиться с этой статьей, чтобы лучше понять, как должны строиться такие правила.
Если вы хотите добиться еще большей гибкости при составлении правил, вы можете использовать регулярные выражения вместо упрощенной маски со специальными символами, которая используется по умолчанию.
Производительность. Такие правила работают медленнее обычных, поэтому рекомендуется избегать их, или хотя бы ограничивать их область действия конкретными доменами.
Чтобы блокировщик определил, что вы хотите использовать регулярное выражение, необходимо, чтобы pattern
имел особый вид:
pattern = "/" regexp "/"
Например, правило /banner\d+/$third-party
применит регулярное выражение banner\d+
ко всем сторонним запросам. Правила-исключения с использованием регулярных выражений выглядят вот так: @@/banner\d+/
.
Совместимость с разными версиями AdGuard. AdGuard для Safari и AdGuard для iOS не полностью поддерживают регулярные выражения в силу ограничений Content Blocking API (в статье по ссылке найдите раздел "The Regular expression format").
||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
Визуальное представление. также советуем ознакомиться с этой статьей, чтобы лучше понять, как должны применяться модификаторы.
Приведенные ниже модификаторы являются наиболее простыми для понимания и часто применяемыми.
domain
Модификатор domain
ограничивает область действия правила списком доменов (и их поддоменов).
Модификатор представляет собой список из одного или нескольких выражений, разделённых символом |
, каждое из которых сопоставляется с доменом определённым образом в зависимости от типа (см. ниже).
domains = ["~"] entry_0 ["|" ["~"] entry_1 ["|" ["~"]entry_2 ["|" ... ["|" ["~"]entry_N]]]]
entry_i = ( regular_domain / any_tld_domain / regexp )
regular_domain
— обычное имя домена (domain.com
). Соответствует указанному домену и его поддоменам. Сопоставляется лексикографически.any_tld_domain
— имя домена, оканчивающееся wildcard-символом в качестве TLD (domain.*
). Соответствует указанному домену и его поддоменам с любым TLD. Сопоставляется лексикографически.regexp
— регулярное выражение, начинается и заканчивается символами /
. Паттерн работает так же, как в базовых URL правилах, однако символы /
, $
, и |
необходимо экранировать с помощью \
.Совместимость с разными версиями AdGuard. Правила с регулярными выражениями в модификаторе
$domain
поддерживаются в AdGuard для Windows, Mac, и Android, с CoreLibs версии 1.11 или выше.
Правила сregular_domain
иany_tld_domain
в модификаторе$domain
поддерживаются во всех продуктах AdGuard.
Символ ~
перед выражением используется для обозначения исключений. Запросы с доменов, соответствующих таким выражениям, не попадают под действие правил, содержащих их.
Примеры:
||baddomain.com^$domain=example.org
— правило для блокировки запросов, которые соответствуют указанной маске, и отправленных с домена или поддомена example.org
.||baddomain.com^$domain=example.org|example.com
— такое же правило, но срабатывать оно будет как для домена example.org
, так и для example.com
.||baddomain.com^$domain=example.*
— такое же правило, но срабатывать оно будет как для домена example
с любым TLD: example.org
, example.com
, example.co.uk
и т.д.||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
с любым TLD (b.com
, b.co.uk
и т.д.), c.com
и c.org
, а также всех поддоменов, всех указанных доменов.domain
соответствует целевому доменуВ некоторых случаях модификатор $domain
может соответствовать не только домену-рефереру, но и целевому домену. Это происходит в случае, когда всё из перечисленного верно:
1) Запрос имеет тип document
2) Паттерн правила не соответствует какому-либо или каким-либо конкретным доменам
3) Паттерн правила не содержит регулярных выражений
4) Модификатор $domain
содержит только исключённые домены
Если будет выполняться условие 1 и ((2 и 3) или 4)
, то модификатор $domain
будет соответствовать как домену-рефереру, так и целевому домену. То есть, если модификатор $domain
содержит только исключённые домены, то правилу не нужно выполнять второе и третье условия, чтобы соответствовать целевому домену $domain
.
Если какие-либо из условий выше не выполнены, но правило содержит модификатор $cookie
или $csp
, модификатор $domain
всё равно будет соответствовать целевому домену.
Если реферер соответствует правилу с $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
указывает на конкретные домены.||*page$domain=targetdomain.com,cookie
сработает несмотря на то, что паттерн ||*page
указывает на конкретные домены, поскольку правило содержит модификатор $cookie
./banner\d+/$domain=targetdomain.com
не сработает, поскольку правило содержит регулярное выражение.page$domain=targetdomain.com|~example.org
не сработает, так как домен реферера явно исключён.Ограничения: Safari не поддерживает одновременно разрешенные и запрещенные домены, поэтому правила вида
||baddomain.com^$domain=example.org|~foo.example.org
не работают в AdGuard для Safari.
third-party
Ограничение на сторонние или собственные запросы. Сторонним является запрос, отправленный с другого домена. Например, запрос к домену example.org
, отправленный с домена domain.com
, является сторонним.
Чтобы считаться таковым, сторонний запрос должен удовлетворять одному из следующих условий:
1) Он не должен быть отправлен с поддомена того же домена или наоборот. Например, запрос кsubdomain.example.org
, отправленный с доменаexample.org
, не является сторонним.
2) Его заголовокSec-Fetch-Site
имеет значениеcross-site
.
Если указан модификатор $third-party
, то правило применяется только к сторонним запросам.
third-party
||domain.com^$third-party
— правило применяется на всех сайтах, кроме domain.com
и его поддоменов. Пример стороннего запроса: http://example.org/banner.jpg
.Если указан модификатор $~third-party
, то правило применяется только к запросам, которые не являются сторонними. То есть, эти запросы отправлены с того же домена.
~third-party
||domain.com$~third-party
— такое правило уже будет применяться только на самом domain.com
, но не на других сайтах. Пример запроса, который не является сторонним: http://domain.com/icon.ico
.popup
AdGuard будет пытаться закрыть браузерную вкладку с любым адресом, подходящим под правило с этим модификатором. Обратите внимание, что закрыть можно не любую вкладку.
popup
||domain.com^$popup
— при попытке перехода на сайт http://domain.com
с любой страницы в браузере, новая вкладка, в которой должен открыться указанный сайт, будет закрыта.Модификатор может не работать, если всплывающая страница закеширована браузером. Также модификатор может не сработать, если для показа попапа используются нестандартные методы. В такие случаях лучше использовать расширение AdGuard Popup Blocker.
Обратите внимание: В отличие от Браузерного расширения AdGuard, модификатор
$popup
крайне нестабильно работает с AdGuard для Windows, Mac и Android. В AdGuard для Safari и iOS$popup
-правила просто заблокируют страницу.
match-case
Определяет правило, которое применяется только к адресам с совпадением регистра символов. По умолчанию регистр символов не учитывается.
match-case
*/BannerAd.gif$match-case
— такое правило будет блокировать http://example.com/BannerAd.gif
, но не http://example.com/bannerad.gif
.header
Модификатор $header
ограничивает область действия правила запросами, ответы которых содержат заголовки, соответствующие правилу.
$header "=" h_name [":" h_value]
h_value = string / regexp
где
h_name
— имя HTTP заголовка. Сопоставляется лексикографически без учёта регистра символов.h_value
— выражения для сопоставления значения HTTP заголовка, может быть одним из:
string
— последовательность символов. Сопоставляется лексикографически с учётом регистра символов.regexp
— регулярное выражение, начинается и заканчивается символом /
. Выражение работает аналогично маске адреса правила, символы /
, $
и ,
должны быть экранированы с помощью \
.Часть модификатора со значением заголовка (":" h_value
) может быть опущена. В этом случае модификатор сопоставляет только имя заголовка.
Совместимость с разными версиями AdGuard. Правила с модификатором
$header
поддерживаются в AdGuard для Windows, Mac, и Android, с CoreLibs версии 1.11 или выше.
||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
.
Существует целый набор модификаторов, которые ограничивают действие правила только запросами к ресурсам определенного типа. Эти модификаторы можно комбинировать, например распространить правило одновременно на картинки и скрипты.
Совместимость с разными версиями AdGuard. Существует большая разница в том, как разные версии AdGuard определяют тип контента. В случае Браузерного расширения AdGuard тип контента для каждого запроса предоставляется самим браузером. В случае AdGuard для Windows, Mac, Android для определения используется следующая методика: вначале мы пытаемся определить тип запроса по расширению загружаемого файла. Если запрос не заблокирован на этом этапе, то тип запроса уточняется с использованием заголовка
Content-Type
в начале ответа, полученного от сервера.
||example.org^$image
— соответствует всем картинкам с домена example.org
.||example.org^$script,stylesheet
— соответствует всем скриптам и стилям с домена example.org
.||example.org^$~image,~script,~stylesheet
— соответствует всем запросам к домену example.org
кроме картинок, скриптов и стилей.document
Правило соответствует запросам основного документа страницы, т.е. HTML-документа, который загружается во вкладке браузера. Оно не подходит для frame-элементов, для которых существует модификатор $subdocument
.
По умолчанию AdGuard не будет блокировать запросы, которые загружаются во вкладке браузера. Идея заключается в том, чтобы не препятствовать загрузке страниц, поскольку пользователь явно указал, что он хочет, чтобы эта страница была загружена. Однако, если использовать модификатор $document
, то AdGuard будет предотвращать загрузку страницы, то есть заблокирует её.
Если этот модификатор используется в правиле-исключении (@@
), то оно полностью отключает блокировку на соответствующих страницах. Это равносильно одновременному использованию модификаторов $elemhide
, $content
, $urlblock
, $jsinject
и $extension
.
document
@@||example.com^$document
— полностью отключает фильтрацию на всех страницах сайта example.com
и всех его поддоменах.
@@|||example.com^$document,~extension
— полностью отключает блокировку на любых страницах сайта 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
.
Совместимость с разными версиями AdGuard. Правила блокировки с модификатором
$document
не поддерживаются в AdGuard Content Blocker.
image
Правило будет соответствовать запросам к изображениям.
stylesheet
Правило будет соответствовать запросам к файлам CSS-стилей.
script
Правило будет соответствовать запросам к файлам скриптов, например, javascript или vbscript.
object
Правило применяется к ресурсам, управляемым браузерными плагинами, например, Java или Flash.
font
Правило будет соответствовать запросам к файлам шрифтов (например, файлам с расширением .woff).
media
Правило будет соответствовать запросам к медиа-файлам — музыка и видео, например, файлы с расширением .mp4.
subdocument
Правило будет соответствовать запросам к встроенным страницам — HTML-теги frame
и iframe
.
subdocument
||example.com^$subdocument
- отключает загрузку встроенных страниц (frame
и iframe
) с example.com
и его поддоменов.||example.com^$subdocument,domain=domain.com
- отключает загрузку встроенных страниц (frame
и iframe
) с example.com
(и поддоменов) на domain.com
и его поддоменах.ping
Правило будет соответствовать запросам, сделанным либо navigator.sendBeacon()
, либо атрибутом ссылки ping
.
Совместимость с разными версиями AdGuard. AdGuard для Windows, Mac, Android не всегда могут корректно определить
navigator.sendBeacon()
. Для надёжного определения используйте Браузерное расширение AdGuard.
xmlhttprequest
Правило применяется только к ajax-запросам. То есть к запросам, отправленным с помощью javascript-объекта XMLHttpRequest
.
Совместимость с разными версиями AdGuard. AdGuard для Windows, Mac и Android не всегда могут корректно определить этот тип контента, и определяют его как
$other
или$script
. Для надёжного определения используйте Браузерное расширение AdGuard.
websocket
Правило применяется только к WebSocket-соединениям.
Совместимость с разными версиями AdGuard. AdGuard для Safari и iOS не могут правильно применять правила с модификатором
$websocket
из-за ограничений Safari.
webrtc
Предупреждение об устаревании. Модификатор
$webrtc
устарел и в будущем его поддержка прекратиться. Если вы хотите блокировать WebRTC, рассмотрите возможность использования скриптлетаnowebrtc
.
Правило применяется только к WebRTC-соединениям.
Обратите внимание, что блокировка WebRTC может мешать работе некоторых браузерных приложений, таких как мессенджеры, чаты, кинотеатры, игры и др.
webrtc
||example.com^$webrtc,domain=example.org
— это правило блокирует WebRTC-соединения c example.com
для example.org
.@@*$webrtc,domain=example.org
— это правило отменяет блокировку всех WebRTC-соединений для example.org
.Совместимость с разными версиями AdGuard. Правила с модификатором
$webrtc
всё ещё поддерживаются Браузерным расширением AdGuard.
other
Правило применяется к запросам, для которых не был определен ни один из перечисленных выше типов.
object-subrequest
(устаревший)Предупреждение об устаревании. Модификатор
$object-subrequest
устарел и больше не поддерживается. Правила с его использованием не работают.
Запросы, инициированные плагинами (чаще всего это Flash).
Правила-исключения отключают действие других базовых правил для адресов, которым они соответствуют. Отличаются правила-исключения тем, что они начинаются со специального маркера @@
. Для таких правил работают все базовые модификаторы, перечисленные выше. Также добавляется несколько специальных модификаторов, которые будут описаны ниже.
Визуальное представление. Также советуем ознакомиться с этой статьей, чтобы лучше понять, как должны строиться правила-исключения.
elemhide
Отключает косметические правила на страницах, подходящих под правило.
elemhide
@@||example.com^$elemhide
— отменяет все косметические правила для страниц на сайте example.com
и на всех его поддоменах.content
Отключает правила фильтрации HTML и replace-правила на страницах, подходящих под правило.
content
@@||example.com^$content
— отменяет все правила фильтрации HTML-элементов для страниц на сайте example.com
и на всех его поддоменах.jsinject
Запрещает добавление javascript-кода на страницу. О javascript правилах речь пойдет ниже.
jsinject
@@||example.com^$jsinject
— отменяет все javascript правила для страниц на сайте example.com
и на всех его поддоменах.urlblock
Отключает блокировку всех запросов, отправленных со страниц, подходящих под это правило.
urlblock
@@||example.com^$urlblock
— запросы, отправленные со страниц на сайте example.com
и всех его поддоменов, не будет блокироваться.extension
Отключает все пользовательские скрипты на страницах, подходящих под это правило.
extension
example@@||example.com^$extension
— пользовательские скрипты не будут работать на всех страницах сайта example.com
.Совместимость с разными версиями AdGuard. Только AdGuard для Windows, Mac, Android имеют технические возможности для поддержки правил с модификатором
$extension
.
stealth
Отключает модуль "Антитрекинг" для всех страниц и запросов, подходящих под это правило.
$stealth [= opt1 [| opt2 [| opt3 [...]]]]
где opt(i)
обозначают опции "Антитрекинга", отключаемые правилами. Модификатор может содержать любое количество опций (см. ниже) или не содержать их вообще. В последнем случае модификатор отключает модуль "Антитрекинг" полностью.
Список доступных опций модификатора:
1p-cookie
— отключает Самоуничтожающиеся куки посещаемого сайта3p-cookie
— отключает Самоуничтожающиеся сторонние куки3p-cache
— отключает Отключить кеш-память для сторонних запросовxclientdata
— отключает Убрать заголовок X-Client-Data из HTTP-запросовdonottrack
— отключает Отправлять заголовок Do-Not-Trackip
— отключает Скрыть IP адрес3p-auth
— отключает Блокировать заголовок Authorizationsearchqueries
- отключает Скрыть поисковые запросыreferrer
— отключает Скрыть Referer от сторонних ресурсовuseragent
— отключает Скрыть User-Agentwebrtc
— отключает Блокировать WebRTCpush
— отключает Блокировать Push APIlocation
— отключает Блокировать Location APIflash
— отключает Блокировать Flashjava
— отключает Блокировать Javadpi
— отключает Защищать от DPIstealth
@@||example.com^$stealth
— полностью отключает модуль Антитрекинг
для запросов к example.com
и поддоменам (кроме блокировки cookies и скрытия параметров отслеживания, см.ниже).@@||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
Совместимость с разными версиями AdGuard.
- Антитрекинг доступен в AdGuard для Windows, Mac, Android и в Браузерном расширении AdGuard для Chrome, Firefox, Edge. Все остальные продукты будут игнорировать правила с модификатором
$stealth
.- Модификатор
$stealth
с опциями поддерживаются в AdGuard для Windows, Mac, и Android, с CoreLibs версии 1.10 или выше.
Перед тем, как перейти к описанию следующих модификаторов, необходимо ввести определение "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
generichide
Отключает все "generic" косметические правила на страницах, подходящих под правило-исключение.
@@||example.com^generichide
— отключает "generic" косметические правила на страницах сайта example.com
и всех его поддоменах.genericblock
Отключает все generic базовые правила на страницах, подходящих под правило-исключение.
@@||example.com^$genericblock
— отключает "generic" базовые правила на страницах сайта example.com
и всех его поддоменах.specifichide
Имеет эффект, противоположный $generichide
. Отключает все "specific" правила сокрытия элементов и CSS-правила, но не отключает "general"-правила.
@@||example.org^$specifichide
— отключит example.org##.banner
, но не ##.banner
.Обратите внимание, что модификатор
$elemhide
может отключить все косметические правила разом.Совместимость с разными версиями AdGuard. Правила с модификатором
$specifichide
поддерживаются в AdGuard для Windows, Mac, Android и Браузерном расширении AdGuard для Chrome, Firefox, Edge.
Модификаторы, описанные в этом разделе, полностью меняют поведение базовых правил, к которым эти модификаторы применены.
important
Модификатор $important
, применённый к правилу, повышает его приоритет относительно любого другого правила без модификатора $important
, даже относительно базовых правил-исключений.
! блокирующее правило заблокирует все запросы, несмотря на правило-исключение.
||example.org^$important
@@||example.org^
! если правило-исключение тоже имеет модификатор `$important`, оно будет иметь более высокий приоритет, и запросы не будут заблокированы
||example.org^$important
@@||example.org^$important
! если применяется правило-исключение на уровне документа, модификатор `$important` будет проигнорирован;
! если запрос к `example.org` отправлен с домена `test.org`, блокирующее правило не будет применено, несмотря на наличие модификатора `$important`
||example.org^$important
@@||test.org^$document
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
содержится отрицание доменаСовместимость с разными версиями AdGuard. Правила блокировки с модификатором
$badfilter
не поддерживаются в AdGuard Content Blocker.
replace
Этот модификатор полностью меняет поведение страницы. Когда он применяется, правило не блокирует запрос. Вместо этого ответ будет модифицирован.
$replace
Вам потребуется знание регулярных выражений, чтобы использовать этот модификатор.
$replace
применяются к любому текстовому ответу, но не будут применяться к binary (media
, image
, object
и т.д.).$replace
не применяются, если размер оригинального ответа превышает 3Мб.$replace
имеют более высокий приоритет, чем другие базовые правила (включая правила-исключения). Так что если запрос соответствует двум различным правилам, одно из которых имеет модификатор $replace
, применится именно это правило.$content
или $document
отменяют срабатывание правил $replace
, даже если запрос им соответствует.$generichide
, $elemhide
или $jsinject
) применяются вместе с правилами $replace
. Это означает, что вы можете изменять содержимое страницы при помощи правила $replace
и одновременно отменять косметические правила.Значение
$replace
может быть пустым в случае правил-исключений. Смотрите раздел с примерами за дополнительной информацией.Несколько правил, соответствующих одному запросу. В случае, когда несколько правил
$replace
соответствуют одному запросу, мы применим каждое из них. Правила будут применяться в алфавитном порядке.
Как правило, синтаксис replace
похож на синтаксис замены при помощи регулярных выражений в Perl.
replace = "/" regexp "/" replacement "/" modifiers
regexp
— регулярное выражение.replacement
— строка, которая будет использована для замены строки в соответствии с regexp
.modifiers
— флаги регулярных выражений. Например, i
— поиск без учёта регистра, или s
— режим одной строки.В значении $replace
необходимо экранировать два символа: запятую (,
) и ($
). Для экранирования используйте (\
). Например, экранированная запятая будет выглядеть так: \,
.
$replace
||example.org^$replace=/(<VAST[\s\S]*?>)[\s\S]*<\/VAST>/\$1<\/VAST>/i
У этого правила три части:
(<VAST(.|\s)*?>)(.|\s)*<\/VAST>
\$1<\/VAST>
(заметьте, что символ $
экранирован)i
(поиск без учёта регистра)Здесь вы можете увидеть, как работает это правило:
http://regexr.com/3cesk
$replace
||example.org^$replace=/X/Y/
||example.org^$replace=/Z/Y/
@@||example.org/page/*$replace=/Z/Y/
example.org
.||example.org/page/
, но правило 1 при этом всё равно работает!.$replace
@@||example.org^$replace
отключит все правила $replace
, соответствующие ||example.org^
.@@||example.org^$document
или @@||example.org^$content
отключит все правила $replace
, исходящие со страниц домена example.org
, включая саму эту страницу.Совместимость с разными версиями AdGuard. Правила с модификатором
$replace
поддерживаются в AdGuard для Windows, Mac, Android и Браузерном расширении AdGuard для Firefox. Такие правила не работают в расширениях для других браузеров, потому что они не могут модифицировать содержимое страниц на сетевом уровне.Ограничения. Правила с модификатором
$replace
могут быть использованы только в доверенных фильтрах. Эта категория включает в себя Пользовательские правила, а также все фильтры, разработанные командой AdGuard.
csp
Этот модификатор полностью меняет поведение правила. Будучи применённым к правилу, он не заблокирует попавший под него запрос. Вместо этого будут изменены заголовки ответа.
Чтобы использовать правила этого типа, необходимо базовое понимание слоя безопасности Политики Безопасности Контента.
Для запросов, подходящих под $csp
-правило, мы усилим политику безопасности ответа, добавив дополнительную политику, равнозначную содержимому модификатора $csp
. Правила $csp
применяются независимо от правил любого другого типа. Прочие базовые правила никак на них не влияют, кроме правил исключений уровня document (смотрите примеры ниже).
Когда несколько правил соответствуют одному запросу. В случае, когда несколько
$csp
-правил соответствуют одному запросу, мы применяем их все.
Синтаксис $csp
Синтаксис значений $csp
похож на синтаксис заголовков Политики Безопасности Контента.
Значение $csp
может быть пустым в случае правил-исключений. Смотрите примеры ниже для более подробной информации.
Ограничения
- Некоторые символы запрещены в значении
$csp
:,
,$
$csp
-правила поддерживают ограниченный список модификаторов:$domain
,$important
,$subdocument
;- Правила с директивами
report-*
считаются некорректными.
$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
-правила на всех страницах, подходящих под паттерн правила.Совместимость с разными версиями AdGuard. Правила с модификатором
$csp
не поддерживается в AdGuard Content Blocker, AdGuard для iOS и для Safari.
all
Модификатор $all
является сборным из модификаторов $document
, $popup
, $csp
. Например, правило ||example.org^$all
конвертируется в такой набор правил:
||example.org^$document,popup
||example.org^$csp=script-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
||example.org^$csp=font-src 'self' 'unsafe-eval' http: https: data: blob: mediastream: filesystem:
||example.org^
cookie
Модификатор $cookie
полностью меняет поведение правила. Вместо того, чтобы блокировать запрос, этот модификатор позволяет нам блокировать или изменять заголовки Cookie
или Set-Cookie
.
Несколько правил, соответствующих одному запросу. В случае, когда несколько правил
$cookie
соответствуют одному запросу, мы применим каждое из них по очереди.
$cookie
Синтаксис правила зависит от того, собираемся ли мы заблокировать все cookie или удалить один cookie. Поведение правила можно изменить с помощью модификаторов maxAge
и sameSite
.
||example.org^$cookie=NAME;maxAge=3600;sameSite=lax
— каждый раз, когда AdGuard встречает cookie с именем NAME
в запросе к example.org
, он будет делать следующее:
3600
секунд||example.org^$cookie
— блокирует все cookie, установленные example.org
; это эквивалентно установке maxAge=0
||example.org^$cookie=NAME
— блокирует единственную cookie с именем NAME
||example.org^$cookie=/regexp/
— блокирует все cookie, соответствующие заданному регулярному выражению regexp
Экранирование специальных символов: в случае использования регулярных выражений необходимо экранировать запятую
,
и знак доллара$
. Используйте для этого бекслеш\
. Например, экранированная запятая выглядит так:\,
.
Правила исключения (@@
) не влияют на правила $cookie
, только если это не правило исключение $document
. Чтобы отключить правило $cookie
, правило исключение также должно иметь модификатор $cookie
. Вот как это работает:
@@||example.org^$cookie
— разблокирует все cookie, установленные example.org
@@||example.org^$cookie=NAME
— разблокирует одну cookie с именем NAME
@@||example.org^$cookie=/regexp/
— разблокирует все cookie, соответствующие заданному регулярному выражению regexp
Ограничения:
$cookie
правила поддерживают ограниченный список модификаторов:$domain
,$~domain
,$important
,$third-party
,$~third-party
.
$cookie
$cookie=__cfduid
— блокирует CloudFlare cookie везде$cookie=/__utm[a-z]/
— блокирует Google Analytics cookie везде||facebook.com^$third-party,cookie=c_user
— не позволяет Facebook'у отслеживать вас, даже если вы вошли в системуСовместимость с разными версиями AdGuard. Правила с модификатором
$cookie
не поддерживается в AdGuard Content Blocker, AdGuard для iOS и для Safari.
network
Правила этого типа позволяют полностью блокировать доступ к указанному удалённому адресу, то есть фактически работают как Брандмауэр.
$network
-правила соответствуют только IP-адресам! Эти правила не получится использовать для блокирования или разблокирования доступа к домену.[2001:4860:4860::8888]$network
вместо [2001:4860:4860:0:0:0:0:8888]$network
.$network
-правило заставит AdGuard направлять трафик в подходящую под соответствие конечную точку, например, тем самым можно прекратить всю последующую фильтрацию./
, то она считается регулярным выражением.network
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. Только AdGuard для Windows, Mac, Android имеют технические возможности для поддержки правила с модификатором
$network
.
app
Этот модификатор ограничивает действие правила до конкретного приложения (или списка приложений). Это может быть не так критично на Windows или Mac, но на мобильных устройствах, где для корректной работы некоторые правила должны быть специфичны для конкретных приложений, данная функция крайне важна.
org.example.app
).chrome.exe
).com.google.Chrome
).На Mac вы можете найти bundle ID или имя процесса интересующего вас приложения в деталях соответствующих запросов в Журнале фильтрации.
app
||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
.Если вы хотите, чтобы правило не применялось к заданному приложению, предваряйте имя приложения символом ~
.
app
и ~
||baddomain.com^$app=~org.example.app
— правило, блокирующее запросы, подходящие под заданную маску и посылаемые любым приложением кроме org.example.app
.||baddomain.com^$app=~org.example.app1|~org.example.app2
— аналогично, но в исключениях два приложения: org.example.app1
и org.example.app2
.Совместимость с разными версиями AdGuard. Только AdGuard для Windows, Mac, Android имеют технические возможности для поддержки правила с модификатором
$app
.
redirect
AdGuard может перенаправлять веб-запросы к локальному "ресурсу".
redirect
AdGuard использует тот же синтаксис правил фильтрации, что и uBlock Origin. Он совместим с модификатором $rewrite=abp-resource
Adblock Plus.
Значение модификатора
$redirect
должно быть именем ресурса, который будет использован для переадресации.Приоритет правил
$redirect
выше, чем у обычных базовых правил блокировки. Это означает, что, если есть базовое правило (даже с модификатором$important
),$redirect
будет иметь над ним преимущество. Если есть белый список (@@
) с совпадающим URL, он также заблокирует переадресацию (только если правило$redirect
также не отмечено как$important
).
$redirect
@@||example.org^$redirect
отключит все правила $redirect
для всех запросов, соответствующих ||example.org^
.@@||example.org^$redirect=redirectName
отключит правила с $redirect=redirectName
для всех запросов, соответствующих ||example.org^
.redirect
||example.org/script.js$script,redirect=noopjs
Это правило перенаправляет все запросы к example.org/script.js
к ресурсу noopjs
.
||example.org/test.mp4$media,redirect=noopmp4-1s
Это правило перенаправляет все запросы example.org/test.mp4
к ресурсу noopmp4-1s
.
Больше информации о редиректах и их использовании доступно на GitHub.
Совместимость с другими модификаторами
Правила с$redirect
совместимы с базовыми модификаторами, модификаторами с ограничением по типу контента, а также с модификаторами$important
и$app
. Правила, содержащие другие типы модификаторов, будут считаться некорректными и не будут применены.Совместимость с разными версиями AdGuard.
Правила с модификатором$redirect
не поддерживается в AdGuard Content Blocker, AdGuard для iOS и для Safari.
Правила с$redirect
приоритетами (например,*$redirect=noopjs:42
) поддерживаются в AdGuard для Windows, Mac, и Android, с CoreLibs версии 1.11 или выше.
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
будут перенаправлены. Все остальные запросы к example.org
изменены не будут.
Совместимость с разными версиями AdGuard. Правила с модификатором
$redirect-rule
не поддерживается в AdGuard Content Blocker, AdGuard для iOS и для Safari.
denyallow
Модификатор $denyallow
позволяет избежать создания дополнительных правил, когда требуется отключить то или иное правило для определённого домена(-ов). Модификатор $denyallow
соответствует только целевым доменам, но не доменам реферера.
Добавление этого модификатора в правило равносильно исключению доменов при помощи паттерна правила либо при помощи добавления дополнительных правил-исключений. Чтобы указать несколько доменов в одном правиле, используйте символ |
в качестве разделителя.
Пожалуйста, обратите внимание, что правила с модификатором $denyallow
имеют следующие ограничения:
||
)$denyallow
, не могут иметь отрицание (т.е. $denyallow=~x.com
) или иметь *
вместо домена верхнего уровня ($denyallow=x.*
)Правила, нарушающие эти ограничения, считаются недействительными.
Пример:
Данное правило:
*$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
Совместимость с разными версиями AdGuard. Правила с модификатором
$denyallow
не поддерживаются в AdGuard Content Blocker.
removeparam
Модификатор
$removeparam
является полным аналогом модификатора$queryprune
. При этом модификатор$queryprune
считается устаревшим, мы рекомендуем везде использовать только модификатор$removeparam
.
Правила с модификатором $removeparam
предназначены для того, чтобы убирать параметры из URL запросов. Такие правила применяются только к запросам типов GET
, HEAD
, и OPTIONS
.
Правила с модификатором
$removeparam
, не содержащие модификаторов типа контента, будут соответствовать только тем запросам, которые имеют тип контентаdocument
.
$removeparam=param
— убирает параметр запроса с именем param
из URL любого запроса. Например, запрос к http://example.com/page?param=1&another=2
будет преобразован в http://example.com/page?another=2
.Базовый синтаксис
$removeparam
поддерживается начиная с версии 1.7 CoreLibs и версии 3.6 Браузерного расширения AdGuard.
Вы также можете использовать регулярные выражения для соответствия параметрам запроса и/или их значениям:
$removeparam=/regexp/[options]
— убирает из URL-адреса любого запроса все параметры, соответствующие заданному регулярному выражению regexp
. В отличие от базового синтаксиса, это означает "убрать параметры запроса, нормализованные к строке name=value
, которая соответствует регулярному выражению". Здесь [options]
— это список опций регулярного выражения. На данный момент, единственная поддерживаемая опция — это i
, делающая соответствие нечувствительным к регистру.Синтаксис
$removeparam
для регулярных выражений будет доступен начиная с версии 1.8 CoreLibs и версии 4.0. Браузерного расширения AdGuard, а пока используйте упрощенный вариант:$removeparam=param
.Экранирование специальных символов: не забудьте экранировать специальные символы в регулярных выражениях, такие как
,
,/
и$
. Для этой цели используйте символ\
. Например, экранированная запятая должна выглядеть так:\,
.Обратите внимание, что правила с регулярными выражениями смотрят как на имя, так и на значение параметра. Чтобы минимизировать риск ошибки, рекомендуем начинать регулярное выражение с
/^
, если только вы не хотите специально работать с значениями параметров.Мы будем стараться обнаруживать и игнорировать неэкранированные символы
$
автоматически, используя следующее правило большого пальца:
Это не является разделителем опций, если:
Оно выглядит как$/
,
Существует другой символ слеша (/
) слева от него,
Существует другой неэкранированный символ$
слева от этого символа слеша.
Укажите "голый" $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_source
из всех запросов.
$removeparam=/utm_.*/
— убирает все параметры utm_* query
из 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, Yandex, и 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.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
совместимы с базовыми модификаторами, модификаторами с ограничением по типу контента, а также с модификаторами$important
и$app
. Правила, содержащие другие типы модификаторов, будут считаться некорректными и не будут применены.Обратите внимание, что блокировку правил
$removeparam
также можно отключить с помощью правил исключений$document
и$urlblock
. Но базовые правила исключений без модификаторов не могут этого сделать. Например,@@||example.com^
не отключит$removeparam=p
для запросов к example.com, а вот@@||example.com^$urlblock
— отключит.Совместимость с разными версиями AdGuard. Правила с модификатором
$removeparam
поддерживаются в AdGuard для Windows, Mac, Android, а также браузерными расширениями AdGuard для Chrome, Firefox, Edge.Ограничения. Правила с модификатором
$removeparam
могут быть использованы только в доверенных фильтрах — то есть в Пользовательских правилах и всех фильтрах, разработанных командой AdGuard.
$removeheader
Правила с модификатором $removeheader
предназначены для того, чтобы убирать заголовки HTTP-запросов и ответов. Изначальная мотивация для создания этого типа правил заключалась в том, чтобы иметь возможность избавиться от заголовка Refresh
, который часто используется для перенаправления пользователей на нежелаемую страницу. Однако, применение данного модификатора не ограничивается этим случаем.
Как и в случае с $csp
, $redirect
, $removeparam
и $cookie
, этот модификатор существует независимо, правила с ним не зависят от обычных базовых правил, то есть регулярные выражения или блокирующие правила никак на них не повлияют. По умолчанию, они работают только применительно к заголовкам ответов. Однако, вы также можете использовать модификатор $removeheader
, чтобы убирать заголовки запросов.
Базовый синтаксис
||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
соответствуют одному запросу, мы будем применять их все по очереди.
$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
, имеющие другие модификаторы, считаются некорректными и будут игнорироваться.||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
Совместимость с разными версиями AdGuard. Правила с модификатором
$removeheader
поддерживаются в AdGuard для Windows, Mac, Android и Браузерном расширении AdGuard для Chrome, Firefox, Edge.
$hls
Правила $hls
модифицируют ответ на соответствующий правилу запрос. Они предназначены для удаления сегментов из HLS-плейлистов (RFC 8216).
Слово "сегмент" в данной документации подразумевает как "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]
изменяют поведение правила как описано ниже.Доступные значения options
:
t
– вместо URL, тестировать теги сегмента на соответствие регулярному выражению. Сегмент с соответствующим тегом будет удален.i
– сделать регулярное выражение нечувствительным к регистру символов.Как и в случае с паттерном, символы /
, $
и ,
в regexp
необходимо экранировать с помощью \
.
$hls
Базовые правила-исключения не отключают правила $hls
. Отключить их можно следующим образом:
@@||example.org^$hls
– отключить все правила $hls
для ответов на запросы к соответствующим паттерну ||example.org^
URL.@@||example.org^$hls=text
– отключить все правила $hls
, у которых значение модификатора hls
равно text
, для ответов на запросы к соответствующим паттерну ||example.org^
URL.$hls
также можно отключить с помощью правил-исключений с модификаторами $document
, $content
и $urlblock
.$hls
разрешены только в доверенных фильтрах.$hls
не могут иметь других модификаторов, кроме $domain
, $third-party
, $app
, $important
, $match-case
и $xmlhttprequest
.$hls
применимы только к HLS-плейлистам, т.е. к тексту в кодировке UTF-8, начинающемуся со строки #EXTM3U
. Никакие другие ответы не будут модифицированы правилами $hls
.$hls
не будут применены к ответам размером больше 3 МБ.Если несколько правил $hls
соответствуют одному и тому же запросу, их эффект суммируется.
||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads
— удалить все сегменты с соответствующим URL.||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i
— то же, но с помощью регулярного выражения.||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t
— удалить все сегменты с соответствующим тегом.Из спецификации следует:
#
), тегом (начинается с #
и имени тега) или URL.Замечания, касающиеся правил $hls
:
$hls
распознают все теги, описанные в RFC, а также несколько распространенных нестандартных тегов. Все остальные строки, начинающиеся с #
, считаются комментариями и остаются нетронутыми.$hls
не могут удалить теги, относящиеся ко всему плейлисту. В данном случае могут быть использованы правила $replace
.Пример работы правил $hls
:
Совместимость с разными версиями AdGuard. Правила с модификатором
$hls
поддерживаются в AdGuard для Windows, Mac, и Android, с CoreLibs версии 1.10 или выше.
$jsonprune
Правила $jsonprune
модифицируют JSON-ответы на соответствующий правилу запрос. Они предназначены для удаления
элементов JSON-документа, выбираемых с помощью особого JSONPath
выражения (см. ниже). Эти правила не модифицируют ответы, не являющиеся валидным JSON-документом.
||example.org^$jsonprune=expression
– удалить элементы, соответствующие особому JSONPath-выражению expression
из ответа на запрос к URL, соответствующему ||example.org
.Символы $
и ,
в expression
необходимо экранировать с помощью \
.
Особые JSONPath-выражения отступают от оригинальной спецификации в следующем:
?(has <key>)
— true
если текущий объект обладает свойством <key>
.?(key-eq <key> <value>)
— true
если текущий объект обладает свойством <key>
, равным <value>
.?(key-substr <key> <value>)
— true
если текущий объект обладает свойством <key>
, чье значение<value>
является подстрокой этой строки...
, не поддерживаются.array slices
в квадратных скобках.Существуют различные online-инструменты для проверки JSONPath-выражений:
https://jsonpath.herokuapp.com/
https://jsonpath.com/
Обратите внимание, что различные имплементации JSONPath обладают
уникальными особенностями и могут быть несовместимы друг с другом.
$jsonprune
Базовые правила-исключения не отключают правила $jsonprune
. Отключить их можно следующим образом:
@@||example.org^$jsonprune
– отключить все правила $jsonprune
для запросов к URL, соответствующим ||example.org^
.@@||example.org^$jsonprune=text
– отключить все правила $jsonprune
, у которых значение модификатора jsonprune
равно text
, для запросов к URL, соответствующим ||example.org^
.$jsonprune
также можно отключить с помощью правил-исключений с модификаторами $document
, $content
и $urlblock
.$jsonprune
не могут иметь других модификаторов, кроме $domain
, $third-party
, $app
, $important
, $match-case
и $xmlhttprequest
.$jsonprune
не будут применены к ответам размером больше 3 МБ.$jsonprune
правил соответствуют одному запросу, их эффект суммируется.||example.org^$jsonprune=\$..[one\, "two three"]
— удалить все вхождения свойств "one" и "two three" в JSON-документ.||example.org^$jsonprune=\$.a[?(has ad_origin)]
— удалить всех прямых потомков a
, которые обладают свойством ad_origin
.||example.org^$jsonprune=\$.*.*[?(key-eq 'Some key' 'Some value')]
— удалить все элементы на уровне вложенности 3, обладающие свойством "Some key", равным "Some value".Совместимость с разными версиями AdGuard. Правила с модификатором
$jsonprune
поддерживаются в AdGuard для Windows, Mac и Android, с CoreLibs версии 1.10 или выше.
noop
Модификатор noop
не делает ничего и может быть использован исключительно в целях улучшения читабельности правил. Он состоит из последовательности символов нижнего подчёркивания (_
) любой длины и может фигурировать в правиле столько раз, сколько требуется.
noop
:||example.com$_,removeparam=/^ss\\$/,_,image
||example.com$replace=/bad/good/,___,~third-party
Совместимость с разными версиями AdGuard. Правила с модификатором
noop
не поддерживаются в AdGuard Content Blocker.
empty
(устаревший)Предупреждение об устаревании. Этот модификатор считаются устаревшими. Вместо него теперь используется модификатор
$redirect
. Правила с$empty
конвертируются в$redirect=nooptext
.
Обычно заблокированный запрос выглядит для браузера как ошибка сервера. В случае применения модификатора $empty
, AdGuard эмулирует пустой ответ сервера со статусом 200 OK
.
empty
||example.org^$empty
— возвращает пустой ответ для всех запросов к домену example.org
и всех его поддоменов.Совместимость с разными версиями AdGuard. Правила с модификатором
$empty
не поддерживаются в AdGuard Content Blocker, AdGuard для Safari и для iOS.
mp4
(устаревший)Предупреждение об устаревании. Этот модификатор считаются устаревшими. Вместо него теперь используется модификатор
$redirect
. Правила с$mp4
конвертируются в$redirect=noopmp4-1s,media
.
В качестве ответа на заблокированный запрос AdGuard возвращает короткую видео-заглушку.
mp4
||example.com/videos/$mp4
— блокирует загрузку видео с адресов ||example.com/videos/*
и заменяет ответ на видео-заглушку.Совместимость с разными версиями AdGuard. Правила с модификатором
$mp4
не поддерживаются в AdGuard Content Blocker, AdGuard для Safari и для iOS.
Однако возможностей базовых правил может быть недостаточно, чтобы заблокировать рекламу. Иногда для этого требуется скрыть какой-нибудь элемент или изменить часть HTML-кода страницы, при этом ничего не сломав. Для этого предназначены правила, описанные в этом разделе.
Вы можете использовать wildcard-символ для доменов верхнего уровня в паттернах косметических, html и js правил. Например, правило example.*##.banner
будет соответствовать всем example.TLD
доменам: example.ru
, example.com
, example.net
, example.org
и т.д.
При составлении базовых правил вы можете использовать wildcard-символ для TLD только вместе с модификатором $domain
. Например, ||*/banners/*$image,domain=example.*
Совместимость с разными версиями AdGuard. Правила с wildcard для TLD поддерживается в AdGuard для Windows, Mac, Android, Safari, iOS и в Браузерном расширении AdGuard для Chrome, Firefox, Edge.
Для работы с косметическими правилами необходимы знания 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
— скроет элемент div
с классом textad
на домене example.com
и всех его поддоменах.example.com,example.org###adblock
— скроет элемент с атрибутом id
равным adblock
на доменах example.com
, example.org
и всех их поддоменах.~example.com##.textad
— скроет элемент с классом textad
на всех доменах, кроме example.com
и всех его поддоменах.Ограничения: Safari не поддерживает одновременно разрешенные и запрещенные домены, поэтому правила вида
example.org,~foo.example.org##.textad
не работают в AdGuard для Safari.
Существует специальный тип правил, "выключающий" отдельные правила скрытия на определенных доменах. Синтаксис таких правил очень похож на обычные правила скрытия, но вместо маркера ##
используется #@#
.
Например, пусть в фильтре есть следующее правило.
##.textad
Если вы хотите отключить это правило для домена example.com
, можно воспользоваться правилом-исключением.
example.com#@#.textad
В некоторых случаях может потребоваться отключение всех запрещающих правил. Например, на время тестирования. Для этого следует воспользоваться правилом исключения без указания домена. Оно полностью отключит соответствующее косметическое правило на ВСЕХ доменах:
#@#.textad
Правило такого вида даст аналогичный результат:
*#@#.textad
Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия не представляется возможным. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.
Иногда недостаточно просто скрыть какой-либо элемент, чтобы заблокировать рекламу. Например, блокировка рекламного элемента может просто сломать верстку сайта. Для таких случаев AdGuard позволяет использовать гораздо более гибкие правила, чем обычные правила скрытия. По сути, с помощью таких правил вы можете добавить на страницу любой CSS-стиль.
Ограничения. Запрещено использование стилей, которые могут приводить к загрузке каких-либо ресурсов. По сути это означает, что запрещено использование атрибутов типа
<url>
.Совместимость с разными версиями AdGuard. Правила CSS-стилей не поддерживаются в AdGuard Content Blocker.
Правила CSS-стилей работают по-разному и их приоритет меняется в зависимости от платформы.
rule = [domains] "#$#" selector "{" style "}"
domains = [domain0, domain1[, ...[, domainN]]]
selector
— CSS-селектор, задающий элементы, которые должны быть скрыты.domains
— ограничение на домены, на страницах которых будет применено правило. Строится по тем же правилам, что и в случае правил скрытия элементов.style
— CSS-стиль, который мы хотим применить к элементам, выбранным selector
.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-стиля не представляется возможным. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.
Возможностей CSS 3.0 не всегда хватает для блокировки рекламы. Чтобы решить эту проблему, AdGuard расширяет возможности CSS, добавляя поддержку новых псевдоэлементов. Для поддержки расширенных CSS-селекторов мы разработали модуль с открытым кодом.
Область применения. Расширенные селекторы можно применять в любом косметическом правиле, будь то правила скрытия или правила CSS-стилей.
Совместимость с разными версиями AdGuard. Правила с расширенными CSS-селекторами не поддерживаются в AdGuard Content Blocker.
Независимо от того, какие CSS-псевдоклассы вы используете в правилах, вы можете использовать специальные маркеры, чтобы эти правила обрабатывались движком "Extended CSS". Рекомендуется использовать эти маркеры для всех косметических расширенных 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)
— это правило отменяет действие предыдущего правила.Обратите внимание, что вы можете использовать движок ExtCss для простых селекторов, применяя правило вида:
#?#div
.Подробнее об отладке расширенных селекторов.
:has()
Рабочий черновик спецификации CSS 4.0 описывает псевдокласс :has
. К сожалению, пока что не многие браузеры поддерживают его.
Синтаксис
:has(selector)
Обратно-совместимый синтаксис:
[-ext-has="selector"]
Поддерживаемые синонимы для лучшей совместимости: :-abp-has
, :if
.
Псевдокласс :has()
выбирает те элементы, внутри которых есть элементы, подходящие под selector
.
Примеры
Выделение всех элементов div
, содержащих элемент с классом banner
:
<!-- HTML code -->
<div>Do not select this div</div>
<div>Select this div<span class="banner"></span></div>
Селектор:
div:has(.banner)
Обратно-совместимый синтаксис:
div[-ext-has=".banner"]
:if-not()
Этот псевдокласс фактически является сокращением от :not(:has())
. Он поддерживается ExtendedCSS для лучшей совместимости с некоторыми фильтрами, но не рекомендуется к использованию в фильтрах AdGuard. Обосновывается это тем, что однажды браузеры будет добавлять встроенную поддержку :has
, но этого никогда не случится для этого псевдокласса.
:contains()
Принцип действия этого псевдокласса очень прост: он позволяет выбрать элементы, которые содержат внутри заданный текст, либо чьё содержимое соответствует указанному регулярному выражению. Пожалуйста, обратите внимание, что этот псевдокласс использует свойство элемента textContent
для определения соответствия (а не innerHTML
).
Синтаксис
// соответствие обычному тексту
:contains(text)
// соответствие регулярному выражению
:contains(/regexp/i)
Обратно-совместимый синтаксис:
// соответствие обычному тексту
[-ext-contains="text"]
// соответствие регулярному выражению
[-ext-contains="/regexp/"]
Поддерживаемые синонимы для лучшей совместимости:
:-abp-contains
,:has-text
.
Примеры
Выделение всех элементов div
, содержащих текст banner
:
<!-- HTML code -->
<div>Do not select this div</div>
<div id="selected">Select this div (banner)</div>
<div>Do not select this div <div class="banner"></div></div>
Селектор:
// соответствие обычному тексту
div:contains(banner)
// соответствие регулярному выражению
div:contains(/this .* banner/)
// поддерживаются флаги регулярных выражений
div:contains(/this .* banner/gi)
Обратно-совместимый синтаксис:
// соответствие обычному тексту
div[-ext-contains="banner"]
// соответствие регулярному выражению
div[-ext-contains="/this .* banner/"]
Обратите внимание, что в этом примере будет выбран только
div
сid=selected
, так как следующий за ним элемент не содержит текст (banner
является частью кода, а не текста).
:matches-css()
Эти псевдоклассы позволяют выделять элемент по его текущему свойству стиля. Работа этого псевдокласса основана на использовании функции window.getComputedStyle
.
Синтаксис
/* element style matching */
selector:matches-css(property-name ":" pattern)
/* ::before pseudo-element style matching */
selector:matches-css-before(property-name ":" pattern)
/* ::after pseudo-element style matching */
selector:matches-css-after(property-name ":" pattern)
Обратно-совместимый синтаксис:
selector[-ext-matches-css="property-name ":" pattern"]
selector[-ext-matches-css-after="property-name ":" pattern"]
selector[-ext-matches-css-before="property-name ":" pattern"]
property-name
— название CSS свойства, которое будет проверено у элементаpattern
— паттерн значений, использующий то же простое соответствие по вайлдкардам как и базовые правила URL-фильтрации ИЛИ регулярное выражение. Для этого типа соответствия AdGuard не обращает внимание на регистр. В случае с регулярными выражениями, паттерн будет выглядеть как /regexp/
.Для паттернов, не являющихся регулярными выражениями, символы
(
,)
,[
,]
должны быть экранированы, потому что мы экранируем их в правилах фильтрации.Для регулярных выражений символы
"
и\
должны быть экранированы, потому что мы вручную экранируем их в extended-css-selector.js.
Примеры
Выделение всех элементов div
, содержащих псевдокласс ::before
с указанным содержимым:
<!-- HTML code -->
<style type="text/css">
#to-be-blocked::before {
content: "Block me"
}
</style>
<div id="to-be-blocked" class="banner"></div>
<div id="not-to-be-blocked" class="banner"></div>
Селектор:
// Обычное соответствие
div.banner:matches-css-before(content: block me)
// Регулярные выражения
div.banner:matches-css-before(content: /block me/)
Обратно-совместимый синтаксис:
// Обычное соответствие
div.banner[-ext-matches-css-before="content: block me"]
// Регулярные выражения
div.banner[-ext-matches-css-before="content: /block me/"]
:matches-attr()
Этот псевдокласс позволяет выделить элемент по его атрибутам, особенно если они рандомизированы и не постоянные.
Синтаксис
selector:matches-attr("name"[="value"])
name
— название атрибута ИЛИ регулярное выражение для названия атрибутаvalue
— необязательно, значение атрибута ИЛИ регулярное выражение для значения атрибутаДля регулярных выражений символы
"
и\
должны быть экранированы.
Примеры
<!-- HTML code -->
<div id="targer1" class="matches-attr" hsd4jkf-link="ssdgsg-banner_240x400"></div>
<div id="targer2" class="has matches-attr">
<div data-sdfghlhw="adbanner"></div>
</div>
<div id="targer3-host" class="matches-attr has contains">
<div id="not-targer3" wsdfg-unit012="click">
<span>socials</span>
</div>
<div id="targer3" hrewq-unit094="click">
<span>ads</span>
</div>
</div>
<div id="targer4" class="matches-attr upward">
<div >
<inner-afhhw class="nyf5tx3" nt4f5be90delay="1000"></inner-afhhw>
</div>
</div>
// для div#targer1
div:matches-attr("/-link/")
// для div#targer2
div:has(> div:matches-attr("/data-/"="adbanner"))
// для div#targer3
div:matches-attr("/-unit/"="/click/"):has(> span:contains(ads))
// для div#targer4
*[class]:matches-attr("/.{5,}delay$/"="/^[0-9]*$/"):upward(2)
:matches-property()
Этот псевдокласс позволяет выделить элемент по его свойствам.
Синтаксис
selector:matches-property("name"[="value"])
name
— название свойства ИЛИ регулярное выражение для названия свойстваvalue
— необязательно, значение свойства ИЛИ регулярное выражение для значения свойстваДля регулярных выражений символы
"
и\
должны быть экранированы.
name
поддерживает регулярные выражения для обозначения свойства в цепи, например,prop./^unit[\\d]{4}$/.type
Примеры
divProperties = {
id: 1,
check: {
track: true,
unit_2ksdf1: true,
},
memoizedProps: {
key: null,
tag: 12,
_owner: {
effectTag: 1,
src: 'ad.com',
},
},
};
// элемент с такими свойствами может быть выделен любым из таких правил:
div:matches-property("check.track")
div:matches-property("check./^unit_.{4,6}$/"))
div:matches-property("memoizedProps.key"="null")
div:matches-property("memoizedProps._owner.src"="/ad/")
Для разработчиков фильтров: Чтобы проверить свойства элемента, нужно:
- Исследовать нужный элемент на странице или выбрать его во вкладке
Элементы
в Инструментах разработчика браузера.- Выполнить
console.dir($0)
во вкладкеConsole
.
:xpath()
Этот псевдокласс позволяет выбирать элементы согласно Xpath выражению.
Может быть только в конце выражения, за исключением использования псевдокласса
:remove()
.
Этот псевдокласс отличается от других тем, что он может использоваться не только для фильтрации текущей выборки элементов, но и для расширения или создания новой. По этой причине selector
является необязательным параметром. Например, выражение :xpath()
может использоваться для выбора всех родительских элементов, что невозможно было бы сделать с помощью css-селекторов.
Синтаксис
[selector]:xpath(expression)
selector
- необязательно, CSS-селекторexpression
— XPath выражениеПримеры
// Фильтрация результатов выборки селектора
div:xpath(//*[@class="test-xpath-class"])
div:has-text(/test-xpath-content/):xpath(../../..)
// Использование xpath для выборки элементов
facebook.com##:xpath(//div[@id="stream_pagelet"]//div[starts-with(@id,"hyperfeed_story_id_")][.//h6//span/text()="People You May Know"])
:nth-ancestor()
Этот псевдокласс позволяет выбирать родительские элементы указанного n-поколения относительно элемента.
Это своего рода эквивалент :xpath(..[/..]*)
.
Может быть только в конце выражения, за исключением использования псевдокласса
:remove()
.
Синтаксис
selector:nth-ancestor(n)
selector
— CSS-селекторn
— натуральное число от 1 до 255, количество поколений от выбранного элементаПримеры
div.test:nth-ancestor(4)
div:has-text(/test/):nth-ancestor(2)
:upward()
Этот псевдокласс позволяет выбирать ближайшие родительские элементы относительно указанного элемента.
Может быть только в конце выражения, за исключением использования псевдокласса
:remove()
.
Синтаксис
/* параметр в виде селектора */
subjectSelector:upward(targetSelector)
/* параметр в виде числа */
subjectSelector:upward(n)
subjectSelector
— CSS-селектор — элемент, относительно которого будет искаться родительский элементtargetSelector
— CSS-селектор — условный родительский элементn
— натуральное число от 1 до 255, количество поколений от выбранного элементаПримеры
div.child:upward(div[id])
div:contains(test):upward(div[class^="parent-wrapper-")
div.test:upward(4)
div:has-text(/test/):upward(2)
:remove()
и псевдосвойство remove
Иногда необходимо именно удалить определенный элемент, а не просто скрыть его или применить какие-либо правила стиля. В таких случаях можно использовать псевдокласс :remove()
или псевдосвойство remove
.
Псевдокласс
:remove()
может быть только в конце выражения.
Синтаксис
! псевдокласс
selector:remove()
! псевдосвойство
selector { remove: true; }
selector
— CSS-селекторПримеры
div.inner:remove()
div:has(> div[ad-attr]):remove()
div:xpath(../..):remove()
div:contains(target text) { remove: true; }
div[class]:has(> a:not([id])) { remove: true; }
Обратите внимание, если используется псевдокласс
:remove()
или псевдосвойствоremove
, то другие свойства этого стиля будут проигнорированы.
То, как применяются правила скрытия элементов и правила CSS-стилей, зависит от платформы.
В AdGuard для Windows, Mac, Android мы используем таблицу стилей, встроенную в страницу. Приоритет у косметических правил такой же, как и у любых других таблиц стилей CSS на сайтах. Но есть ограничение: правила скрытия элементов и правила CSS-стилей не могут обходить встроенные стили. В таких случаях рекомендуется использовать расширенные селекторы или HTML-фильтрацию.
В Браузерном расширении AdGuard используются так называемые "пользовательские таблицы стилей". Их приоритет выше, даже чем у встроенных стилей.
Расширенные CSS-селекторы используют для работы Javascript и добавляют встроенные стили сами, поэтому могут игнорировать любой стиль.
В большинстве случаев достаточно использовать базовые и косметические правила. Но иногда для фильтрации рекламы необходимо изменять HTML-код самой страницы до того, как он будет загружен браузером. Для того чтобы сделать это, применяются правила фильтрации HTML-контента. Они позволяют указать, какие HTML-элементы необходимо вырезать из страницы перед тем, как страница попадет в браузер.
Совместимость с разными версиями AdGuard. Правила фильтрации HTML поддерживаются в AdGuard для Windows, Mac, Android и Браузерном расширеним AdGuard для Firefox. Они не работают в расширениях для других браузеров, потому что они не могут модифицировать содержимое страниц на сетевом уровне.
rule = [domains] "$$" tagName [attributes]
domains = [domain0, domain1[, ...[, domainN]]]
attributes = "[" name0 = value0 "]" "[" name1 = value2 "]" ... "[" nameN = valueN "]"
tagName
— имя элемента в нижнем регистре, например, div
или script
.domains
— ограничение на домены, на страницах которых будет применено правило. Строится по тем же правилам, что и в случае правил скрытия элементов.attributes
— список атрибутов, ограничивающих выбор элементов. name
— название атрибута, value
— подстрока, которая содержится в значении атрибута.HTML code
<script data-src="/banner.js"></script>
Правило
example.org$$script[data-src="banner"]
Это правило удалит из кода страниц все элементы script
со значением data-src
, содержащим подстроку banner
. При этом правило будет работать только для домена example.org
и всех его поддоменов.
Помимо обычных атрибутов, значение которых проверяется у каждого элемента, существует набор специальных атрибутов правила, которые изменяют способ работы правила. Ниже мы перечислим все эти атрибуты.
tag-content
Пожалуй, наиболее часто используемый специальный атрибут. Он ограничивает выбор теми элементами, внутренний HTML код которых (innerHTML) содержит указанную подстроку.
Используйте
""
для экранирования"
, например:
$$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"]
Вложенные элементы. Если мы имеем дело с несколькими вложенными друг в друга элементами, каждый из которых подходит под одно и то же правило фильтрации HTML-контента, то удалены будут все эти элементы.
wildcard
Этот специальный атрибут работает практически также как tag-content
и позволяет проверить внутренний HTML-код элемента. Правило проверит, удовлетворяет ли HTML-код элемента заданному шаблону поиска.
Используйте
""
для экранирования"
, например:
$$script[wildcard=""banner""]
Возьмем для примера следующее правило:
$$script[wildcard="*banner*text*"]
Оно проверит, что код элемента содержит две последовательные подстроки banner
и text
.
max-length
Задает максимальную длину содержимого HTML-элемента. Если этот параметр задан, и длина содержимого превышает заданное значение — правило не применяется к элементу.
Значение по умолчанию. Если этот параметр не задан, то
max-length
считается равным 8192.
Например, возьмем следующее правило:
$$div[tag-content="banner"][max-length="400"]
Это правило удалит все элементы div
, код которых содержит подстроку banner
, и длина которых не превышает 400
символов.
min-length
Задает минимальную длину содержимого HTML-элемента. Если этот параметр задан, и длина содержимого меньше заданного значения — правило не применяется к элементу.
Например, возьмем следующее правило:
$$div[tag-content="banner"][min-length="400"]
Это правило удалит все элементы div
, код которых содержит подстроку banner
, и длина которых превышает 400
символов.
По аналогии с правилами скрытия, существует специальный тип правил, отключающий действие выбранного правила фильтрации HTML для определенных доменов. Синтаксис правил-исключений такой же, только маркер $$
заменяется на $@$
.
Например, пусть в фильтре есть следующее правило.
$$script[tag-content="banner"]
Если вы хотите отключить это правило для домена example.com
, можно воспользоваться правилом-исключением.
example.com$@$script[tag-content="banner"]
В некоторых случаях может потребоваться отключение всех запрещающих правил. Например, на время тестирования. Для этого следует воспользоваться правилом исключения без указания домена.
$@$script[tag-content="banner"]
Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия не представляется возможным. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.
AdGuard поддерживает специальный тип правил, позволяющий вставить любой javascript-код на страницы интернет-сайтов.
Ограничения. JavaScript-правила могут быть использованы только в доверенных фильтрах. В эту категорию попадают ваши Пользовательские правила, и фильтры, которые создаются командой AdGuard.
Совместимость с разными версиями AdGuard. Javascript-правила не поддерживаются в AdGuard Content Blocker.
Мы крайне рекомендуем использовать скриптлеты вместо 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, которая предоставляет расширенные возможности для блокирования контента. Такие функции могут использоваться в декларативной манере в правилах фильтрации AdGuard.
AdGuard поддерживает множество различных скриптлетов. Чтобы добиться совместимости между различными блокировщиками, мы также поддерживаем синтаксис uBO и ABP.
rule = [domains] "#%#//scriptlet(" scriptletName arguments ")"
scriptletName
(обязательно) — это имя скриптлета из библиотеки скриптлетов AdGuard
arguments
(опционально) — это список аргументов в формате String (другие типы аргументов не поддерживаются)
example.org#%#//scriptlet("abort-on-property-read", "alert")
Это правило применится на страницах домена example.org (и его поддоменов) и выполнит скриптлет "abort-on-property-read" с параметром "alert".
Подробнее об отладке скриптлетов.
Больше информации о скриптлетах можно найти на GitHub.
Совместимость с разными версиями AdGuard. Скриптлеты не поддерживаются в AdGuard Content Blocker.
Поведение любого правила можно изменить, используя модификаторы, описанные ниже.
rule = "[$" modifiers "]" [rule text]
modifiers = modifier0[, modifier1[, ...[, modifierN]]]
modifier
— группа модификаторов, описанных ниже.rule text
— косметическое правило, которое нужно модифицировать.Например: [$domain=example.com,app=test_app]##selector
.
В значениях модификаторов следующие символы должны быть экранированы: [
, ]
, ,
и \
(если он не используется для экранирования). Используйте \
, чтобы экранировать их. Например, экранированная скобка выглядит так: \]
.
app
Модификатор $app
ограничивает действие правила до конкретного приложения или списка приложений. Поведение и синтаксис модификатора полностью совпадают с соответствующим модификатором $app
для базовых правил.
app
:[$app=org.example.app]example.com##.textad
— скрывает div
и заменяет его на класс textad
на example.com
и всех поддоменах в запросах, посланных из org.example.app
приложения Android.[$app=~org.example.app1|~org.example.app2]example.com##.textad
— скрывает div
и заменяет его на класс textad
на example.com
и всех поддоменах в запросах, посланных из любого приложения кроме org.example.app1
и org.example.app2
.[$app=com.apple.Safari]example.org#%#//scriptlet('prevent-setInterval', 'check', '!300')
— это правило применит соответствующий скриптлет только в браузере Safari на Mac.[$app=org.example.app]#@#.textad
— отключит все правила ##.textad
для всех доменов при использовании приложения org.example.app
.Совместимость с разными версиями AdGuard. Этот тип правил поддерживается AdGuard для Windows, Mac и Android. На данный момент только в девелоперских сборках.
domain
Модификатор $domain
ограничивает область действия правила списком доменов и их поддоменов.
Поведение и синтаксис модификатора почти полностью совпадают с соответствующим модификатором $domain
для базовых правил.
Единственное отличие в том, что разделитель доменов |
в регулярных выражениях экранировать не требуется.
domain
:[$domain=example.com]##.textad
— скрывает div
и заменяет его на класс textad
на example.com
и всех поддоменах.[$domain=example.com|example.org]###adblock
— скрывает элемент с атрибутом id
, равным adblock
, на example.com
, example.org
и всех поддоменах.[$domain=~example.com]##.textad
— скрывает div
и заменяет его на класс textad
на всех доменах кроме example.com
и его поддоменов.[$domain=/(^|.+\.)example\.(com|org)\$/]##.textad
— скрывает элемент с атрибутом id
, равным adblock
, на example.com
, example.org
и всех поддоменах.Существует 2 способа указать доменные ограничения для косметических правил:
1) «классический»: обозначить ограничение на домены перед маской и атрибутами правила: example.com##.textad
;
2) с помощью модификаторов: обозначить ограничение на домены через модификатор domain
: [$domain=example.com]##.textad
.
Но правила, в которых используется смешанный стиль ограничения на домены, считаются некорректными. Так, например, правило [$domain=example.org]example.com##.textad
будет отклонено.
path
Модификатор $path
ограничивает действие правила определенным местоположением или страницей на сайтах.
$path ["=" pattern]
pattern
— необязательный, это маска пути, которой ограничено правило. Его синтаксис и поведение почти такие же, как в шаблоне базовых правил. Вы также можете использовать специальные символы, за исключением ||
, поскольку в этом случае это не имеет никакого смысла (см. примеры ниже).
Если
pattern
не указан для модификатора$path
, правило применится только на главной странице сайта.Обратите внимание, что модификатор
$path
также соответствует параметрам запроса.Модификатор
$path
поддерживает регулярные выражения таким же образом, что и базовые правила.
$path
:[$path=page.html]##.textad
скрывает div
с классом textad
на /page.html
, /page.html?<query>
, /sub/page.html
или /another_page.html
[$path=/page.html]##.textad
скрывает div
с классом textad
на /page.html
, /page.html?<query>
, /sub/page.html
любого домена, но не на /another_page.html
[$path=|/page.html]##.textad
скрывает div
с классом textad
на /page.html
или /page.html?<query>
любого домена, но не на /sub/page.html
[$path=/page.html|]##.textad
скрывает div
с классом textad
на /page.html
или /sub/page.html
любого домена, но не на /page.html?<query>
[$path=/page*.html]example.com##.textad
скрывает div
с классом textad
на /page1.html
, /page2.html
или любом другом пути, соответствующим /page<...>.html
, на домене example.com
[$path]example.com##.textad
скрывает div
с классом textad
на главной странице сайта example.com
[$domain=example.com,path=/page.html]##.textad
скрывает div
с классом textad
на page.html
домена example.com
и всех его поддоменах, но не на another_page.html
[$path=/\\/(sub1|sub2)\\/page\\.html/]##.textad
скрывает div
с классом textad
как на /sub1/page.html
, так и /sub2/page.html
любого домена (обратите внимание на экранированные символы)Совместимость с разными версиями AdGuard. Правила с модификатором
$path
поддерживаются в AdGuard для Windows, Mac, Android и Браузерном расширении AdGuard для Chrome, Firefox, Edge.
Модификатор $url
ограничивает действие правила запросами, URL которых соответствует указанной маске.
url = pattern
где pattern
— маска адреса, синтаксис которой соответсвует маске адреса (pattern
) базовых правил за исключением того, что некоторые символы должны быть экранированны.
Специальные символы и регулярные выражения также поддерживаются.
[$url=||example.com/ads/*]##.textad
— скрывает div
с классом textad
в запросах, например, к http://example.com/ads/banner.jpg
и http://subdomain.example.com/ads/otherbanner.jpg
.[$url=||example.org^]###adblock
— скрывает элемент с атрибутом id
равным adblock
в запросах к example.org
и всем его поддоменам.[$url=/\[a-z\]+\\.example\\.com^/]##.textad
— скрывает div
с классом textad
в запросах к доменам, соответствующих регулярному выражению [a-z]+\.example\.com^
.Совместимость с разными версиями AdGuard. Правила с модификатором
$url
поддерживаются в AdGuard для Windows, Mac, и Android, с CoreLibs версии 1.11 или выше.
Если вы разрабатываете сторонний фильтр, известный AdGuard, вам может быть интересна информация, представленная в настоящем разделе. Пожалуйста, имейте в виду, что специальные комментарии hint будут применяться только к зарегистрированным фильтрам. Фильтр считается зарегистрированным и известным AdGuard, если он присутствует в перечне известных фильтров. Если вы желаете зарегистрировать свой фильтр, пожалуйста, направьте запрос в репозиторий AdGuardFilters.
Мы предоставляем несколько директив пре-процессинга, которые могут быть использованы разработчиками фильтров для улучшения совместимости с различными блокировщиками рекламы. Директивы могут
Любая ошибка в пре-процессинговой директиве приведёт к невозможности обновить фильтр, как если бы URL фильтра был недоступен.
Директивы пре-процессинга можно использовать в Пользовательских правилах в собственных (кастомных) фильтрах.
Директива !#include
позволяет включать в фильтр содержимое заданного файла. Она поддерживает только файлы из того же источника, чтобы удостовериться, что разработчик фильтров является владельцем указанного файла. Включённый файл также может содержать директивы пре-процессинга (даже другие !#include
директивы). Блокировщики должны принимать во внимание случай рекурсивного использования !#include
и внедрять защитный механизм.
Синтаксис
!#include file_path
file_path
— абсолютный (того же источника) или относительный путь к файлуФайлы должны находиться на том же домене, но могут быть расположены в другой директории.
Если включённый файл не найден или недоступен, не будут работать обновления всего фильтра.
Для локальных собственных фильтров ограничение на тот же источник не распространяется.
Примеры
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
Разработчики фильтров могут использовать условия, чтобы подставлять нужные правила, в зависимости от типа блокировщика. Когда блокировщик рекламы сталкивается с директивой !#if
, за которой затем следует директива !#endif
, он скомпилирует код внутри блока, только если выполнено указанное условие. Условие поддерживает базовые логические операторы.
Директива с условием, начинающаяся с директивы
!#if
, должна явно прерываться директивой!#endif
.Пробелы имеют значение.
!#if
— это корректная директива, в то время как!# if
— нет.
Синтаксис
!#if (conditions)
rules_list
!#endif
!#if (conditions)
— начало блока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 (и браузеров на базе Chromium, например, новый Microsoft Edge)adguard_ext_firefox
— Браузерное расширение AdGuard для Firefoxadguard_ext_edge
— Браузерное расширение AdGuard для Edge Legacyadguard_ext_opera
— Браузерное расширение AdGuard для Operaadguard_ext_android_cb
— AdGuard Content Blocker для мобильных браузеров Samsung и Yandexext_ublock
— особый случай; эта константа объявляется, когда версия фильтра для ublock компилируется при помощи FiltersRegistryrules_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
В Safari существует строгое ограничение в 50 тысяч правил на один блокировщик контента. Но в AdGuard для Safari и в AdGuard для iOS максимальное число поддерживаемых правил увеличено до 300 тысяч. Это получилось благодаря условному их разделению на несколько блокировщиков контента. В целом, отдельные категории фильтров более-менее независимы, поэтому они поделены между блокировщиками контента следующим образом:
Пользовательские правила
иБелый список
добавляются в каждый блокировщик контента.
Главным недостатком использования нескольких блокировщиков контента является то, что они не могут работать вместе и ссылаться в своих правилах фильтрации друг на друга. И из-за этого бывают весьма неожиданные проблемы. Чтобы избежать этого и заставить правила внутри блока (из одного блокировщика) применяться вместе с правилами из другого блокировщика контента, разработчики фильтров могут использовать директиву !#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
! чтобы разблокировать запрос, который блокируется Фильтр счетчиков и систем аналитики:
!#safari_cb_affinity(privacy)
@@||example.org^
!#safari_cb_affinity
"Hint" — это специальный комментарий, инструкция для компилятора фильтров, работающего на стороне сервера (см. FiltersRegistry).
!+ HINT_NAME1(PARAMS) HINT_NAME2(PARAMS)
Обратите внимание: вы можете использовать несколько комментариев hint.
Для каждого фильтра AdGuard существуют две версии: полная и оптимизированная. Оптимизированная версия имеет намного меньший объем и не включает правила, которые не используются совсем или используются редко.
Частота использования правил определяется собранной статистикой по рекламным фильтрам. Но оптимизация основана также на исходной конфигурации для каждого фильтра. Например, вот так это выглядит для Базового фильтра:
"filter": Базовый фильтр AdGuard,
"percent": 30,
"minPercent": 20,
"maxPercent": 40,
"strict": true
Где:
~= (количество правил в оптимизированном фильтре) / (количество правил в исходном фильтре) * 100
percent
percent
percent < minPercent
ИЛИ percent > maxPercent
и включен режим strict, то компиляция фильтра должна завершиться неудачно, в противном случае должны использоваться оригинальные правилаИными словами,
percent
это "уровень сжатия". Например, для Базового фильтра он настроен на 40%. Это значит, что алгоритм оптимизации удалит 60% правил.
В итоге, вот так выглядят версии Базового фильтра для Браузерного расширения AdGuard для Chrome:
Если вы хотите добавить правило, которое не должно удаляться при оптимизации, используйте хинт NOT_OPTIMIZED
:
!+ NOT_OPTIMIZED
||example.org^
А такое правило не будет оптимизировано только для AdGuard для Android:
!+ NOT_OPTIMIZED PLATFORM(android)
||example.org^
Записи этого типа позволяют указывать системную платформу, для которой применяется правило. Ниже представлен список используемых платформ:
windows
— например, Базовый фильтр для Windows — https://filters.adtidy.org/windows/filters/2.txt
mac
— например, Базовый фильтр для Mac — https://filters.adtidy.org/mac_v2/filters/2.txt
android
— например, Базовый фильтр для Android — https://filters.adtidy.org/android/filters/2.txt
ios
— например, Базовый фильтр для iOS — https://filters.adtidy.org/ios/filters/2.txt
ext_chromium
— например, Базовый фильтр для Браузерного расширения AdGuard для Chrome — https://filters.adtidy.org/extension/chromium/filters/2.txt
ext_ff
— например, Базовый фильтр для Браузерного расширения AdGuard для Firefox — https://filters.adtidy.org/extension/firefox/filters/2.txt
ext_edge
— например, Базовый фильтр для Браузерного расширения AdGuard для Edge — https://filters.adtidy.org/extension/edge/filters/2.txt
ext_opera
— например, Базовый фильтр для Браузерного расширения AdGuard для Opera — https://filters.adtidy.org/extension/opera/filters/2.txt
ext_ublock
— например, Базовый фильтр для uBlock Origin — https://filters.adtidy.org/extension/ublock/filters/2.txt
ext_safari
— например, Базовый фильтр для AdGuard для Safari — https://filters.adtidy.org/extension/safari/filters/2.txt
ext_android_cb
— например, Базовый фильтр для AdGuard Content Blocker — https://filters.adtidy.org/extension/android-content-blocker/filters/2.txt
Примеры:
Это правило будет действовать только в AdGuard для Windows, Mac, Android:
!+ PLATFORM(windows,mac,android)
||example.org^
Это правило будет действовать для всех платформ, кроме AdGuard для Safari, Android Content Blocker и AdGuard для iOS:
!+ NOT_PLATFORM(ext_safari, ext_android_cb, ios)
||example.org^
Хоть самые простые правила фильтрации и возможно придумать "в голове", для чего-либо даже немного более сложного вам потребуются дополнительная помощь в отладке и итерировании. Для этой цели существуют различные инструменты. Вы можете использовать Инструменты разработчика в Chrome и их аналоги в других браузерах, но большинство продуктов AdGuard предоставляют и другой инструмент: Журнал фильтрации.
Журнал фильтрации — продвинутый инструмент, который полезен в основном для разработчиков фильтров. В нём отображаются все веб-запросы, проходящие через AdGuard, даётся исчерпывающая информация по каждому из них, предлагаются различные опции сортировки и другие полезные возможности.
В зависимости от используемого вами продукта AdGuard, Журнал фильтрации может находиться в различных пунктах меню.
В AdGuard для iOS и в AdGuard для Safari Журнал фильтрации отсутствует из-за особенностей реализации блокировщиков контента в Safari. AdGuard сам не видит веб-запросы и поэтому не может отображать их.
Иногда у вас может возникнуть необходимость проверить быстродействие того или иного селектора или таблицы стилей. Чтобы сделать это без непосредственного взаимодействия с JavaScript, вы можете использовать свойство стиля debug
. Когда ExtendedCSS
встречает это свойство, он включает режим отладки для конкретного селектора или для всех селекторов, в зависимости от значения debug
. Откройте консоль браузера, находясь на веб-странице, чтобы посмотреть статистику по времени, затраченному на применение селектора(-ов). Режим отладки покажет следующую статистику для каждого из отлаживаемых селекторов:
array
: время, которое ушло на применение селектора на странице, для каждого из случаев применения этого селектора (в миллисекундах)
length
: общее количество раз, когда на странице был применён данный селектор
mean
: среднее время, ушедшее на применение данного селектора на странице
stddev
: стандартное отклонение
squaredSum
: сумма квадратичных отклонений от среднего значения
sum
: общее время, ушедшее на все применения данного селектора на текущей странице
Отладка конкретного селектора
Когда значение свойства debug
равно true
, информация только по этому селектору будет отображена в консоли браузера.
#$?#.banner { display: none; debug: true; }
Включение глобальной отладки
Когда значение свойства debug
равно global
, в консоли будет отображаться информация по всем ExtendedCSS-селекторам, которые были применены на данной странице, для всех ExtendedCSS-правил из любого из включённых фильтров.
#$?#.banner { display: none; debug: global; }
Если у вас не установлен AdGuard, вы всё равно можете тестировать расширенные селекторы, но для этого вам потребуется сначала загрузить в текущую страницу ExtendedCSS. Чтобы сделать это, скопируйте и запустите следующий код в консоли браузера:
!function(E,x,t,C,s,s_){C=E.createElement(x),s=E.getElementsByTagName(x)[0],C.src=t,
C.onload=function(){alert('ExtCss loaded successfully')},s.parentNode.insertBefore(C,s)}
(document,'script','https://AdguardTeam.github.io/ExtendedCss/extended-css.min.js')
В качестве альтернативы вы можете установить пользовательский скрипт "ExtendedCssDebugger": https://github.com/AdguardTeam/Userscripts/blob/master/extendedCssDebugger/extended-css.debugger.user.js
Теперь вы можете использовать конструктор ExtendedCss
в глобальном масштабе, а его метод ExtendedCss.query
как document.querySelectorAll
.
var selectorText = "div.block[-ext-has='.header:matches-css-after(content: Anzeige)']";
ExtendedCss.query(selectorText) // returns an array of Elements matching selectorText
Если вы используете Браузерное расширение 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
Желаем вам удачи в составлении собственных фильтров.
Если вы хотите спросить совета о том, как правильно составлять фильтры, на нашем форуме есть специальный раздел, посвященный написанию собственных правил.