Как составлять свои фильтры

информация

В этой статье мы рассказываем, как писать пользовательские правила фильтрации для использования в продуктах AdGuard. Чтобы проверить правила, скачайте приложение AdGuard

Фильтр — это набор правил фильтрации рекламного контента (баннеров, всплывающих окон и тому подобного). В AdGuard есть список базовых фильтров, созданных нашей командой. Они постоянно дорабатываются и дополняются, и, как мы надеемся, удовлетворяют требованиям большинства пользователей.

В то же время AdGuard позволяет создавать пользовательские фильтры, используя те же типы правил, что и в наших фильтрах.

Для описания синтаксиса правил мы используем Augmented BNF for Syntax Specifications, но не всегда строго следуем этой спецификации.

информация

Синтаксис правил AdGuard изначально основан на синтаксисе правил Adblock Plus. Позже мы расширили его новыми типами правил для лучшей фильтрации рекламы. Часть информации в этой статье об общих для ABP и AdGuard типах правил взята из руководства Adblock Plus по написанию фильтров.

Комментарии

Любая строка, начинающаяся с восклицательного знака, является комментарием. В списке правил она подсвечивается серым цветом. AdGuard будет игнорировать эту строку, так что можете спокойно писать там всё, что хотите. Комментарии обычно размещаются над правилами и описывают то, что они делают.

Например:

! Это комментарий. Под этой строкой находится правило фильтрации.
||example.org^

Примеры

Блокировка по имени домена

Это правило блокирует:

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

Это правило не блокирует:

• http://ads.example.org.us/ad1.gif
• http://example.com/redirect/http://ads.example.org/

По умолчанию такие правила не действуют для запросов документов. Это означает, что правило ||example.org^ будет блокировать запрос к example.org, когда вы попытаетесь перейти на этот домен с другого сайта, но если вы введёте example.org в адресную строку и попытаетесь перейти на него, сайт откроется. Чтобы заблокировать запрос документа, нужно использовать правило с модификатором$document: ||example.org^$document.

Блокировка конкретного адреса

Это правило блокирует:

• http://example.org/

Это правило не блокирует:

• https://example.org/banner/img

Модификаторы базовых правил

Правила фильтрации поддерживают множество модификаторов, которые позволяют вам точно настраивать поведение правила. Вот пример правила с некоторыми простыми модификаторами.

Это правило блокирует:

• http://example.com/script.js, если этот скрипт загружен с example.com.

Это правило не блокирует:

• https://example.org/script.js если этот скрипт загружен с example.org.
• https://example.org/banner.png потому что это не скрипт.

Разблокировка адреса

Это правило разблокирует:

• http://example.org/banner.png, даже если для этого адреса есть правило блокировки.

Правила блокировки с модификатором $important приоритетнее, чем обычные правила разблокировки.

Разблокировка всего сайта

Это правило разблокирует

• Оно отключает все косметические правила на example.com.
• Оно блокирует все запросы, отправленные с этого сайта, даже если есть правила блокировки, соответствующие этим запросам.

Косметические правила

Косметические правила применяются с использованием CSS — специального языка программирования, который понимает каждый браузер. В основном, он добавляет новый стиль CSS на сайт, цель которого — скрыть определённые элементы. Вы можете узнать больше о CSS в целом здесь.

AdGuard расширяет возможности CSS и позволяет разработчикам фильтров решать гораздо более сложные задачи. Но чтобы использовать эти расширенные правила, вы должны хорошо понимать, что такое CSS.

Популярные CSS-селекторы

Имя	CSS-селектор	Описание
Селектор ID	#banners	Выбирает все элементы, id которых равен banners.
Селектор класса	.banners	Выбирает все элементы с атрибутом class, содержащие banners.
Селектор атрибута	div[class="banners"]	Соответствует всем div элементам с атрибутом class , равным banners.
Селектор вхождения подстроки	div[class^="advert1"]	Выбирает все div-элементы, атрибут class которых начинается с advert1.
Селектор вхождения подстроки	div[class$="banners_ads"]	Выбирает все div-элементы, атрибут class которых заканчивается на banners_ads.
Селектор вхождения подстроки	a[href^="http://example.com/"]	Выбирает все ссылки, загруженные с домена http://example.com/.
Селектор атрибута	a[href="http://example.com/"]	Выбирает все ссылки, которые точное соответствуют http://example.com/.

Ограничения и запреты

Доверенные фильтры

Некоторые правила можно использовать только в доверенных фильтрах. В эту категорию входят:

• Списки фильтров, созданные командой AdGuard
• Пользовательские списки фильтров, помеченные как trusted (доверенные)
• Пользовательские правила

AdGuard Content Blocker

AdGuard Content Blocker — это расширение для браузеров Samsung и Яндекс, которое можно установить из Google Play. Его не следует путать с полнофункциональным AdGuard для Android, который можно загрузить только с нашего сайта. К сожалению, возможности AdGuard Content Blocker ограничены тем, что позволяют браузеры, а они поддерживают только старый синтаксис фильтров Adblock Plus:

• Базовые правила блокировки со следующими модификаторами: $domain, $third-party и модификаторы типа контента.
• Базовые правила исключения со следующими модификаторами: $document, $elemhide.
• Базовые правила скрытия элементов без поддержки расширенного CSS.

Из-за указанных выше ограничений AdGuard Content Blocker не будет упоминаться в примечаниях по совместимости.

SafariConverterLib

Конвертер Safari стремится поддерживать синтаксис правил фильтрации AdGuard, насколько это возможно, но всё же существуют ограничения и недостатки, которые трудно преодолеть.

Базовые (сетевые) правила

Конвертер Safari поддерживает значительное подмножество базовых правил и, безусловно, самые важные их типы.

Поддержка с ограничениями

• Правила регулярных выражений ограничены подмножеством регулярных выражений, которые поддерживаются Safari.

• $domain — модификатор домена поддерживается с несколькими ограничениями.

  • Невозможно смешивать разрешённые и запрещённые домены (например, $domain=example.org|~sub.example.org). Пожалуйста, проголосуйте за запрос на добавление функции в WebKit, чтобы снять это ограничение.
  • «Любой TLD» (т.е. domain.*) поддерживается не полностью. В текущей реализации конвертер просто заменяет .* на 100 самых популярных TLD. Эта реализация будет улучшена в будущем.
  • Использование регулярных выражений в $domain не поддерживается, но это также будет улучшено в будущем.

• $denyallow — этот модификатор поддерживается через преобразование правила $denyallow в набор правил (одно блокирующее правило + несколько разблокирующих).

  Из-за этого ограничения $denyallow разрешено использовать только когда у правила также есть модификатор $domain.

  • Общее правило *$denyallow=x.com,image,domain=a.com будет конвертировано в:

    *$image,domain=a.com
    @@||x.com$image,domain=a.com

  • Правило /banner.png$image,denyallow=test1.com|test2.com,domain=example.org будет конвертировано в:

    /banner.png$image,domain=example.org
    @@||test1.com/banner.png$image,domain=example.org
    @@||test1.com/*/banner.png$image,domain=example.org
    @@||test2.com/banner.png$image,domain=example.org
    @@||test2.com/*/banner.png$image,domain=example.org

  • Правило без $domain не поддерживается: $denyallow=a.com|b.com.

• $popup — правила всплывающих окон поддерживаются, но они по сути такие же, как и правила блокировки $document, и не попытаются закрыть вкладку.

• Правила исключений (@@) отключают косметическую фильтрацию на соответствующих доменах.

  Правила исключений в Safari зависят от типа правила ignore-previous-rules, поэтому для их работы мы должны расставить правила в определённом порядке. Правила исключений без модификаторов размещаются в конце списка и, следовательно, они отключают не только блокировку URL, но и косметические правила.

  Это ограничение может быть снято, если будет реализована #70.

• $urlblock, $genericblock по сути то же самое, что и $document, т.е. оно отключает все виды фильтрации на сайтах.

  Эти ограничения могут быть сняты, когда #69 и #71 будут реализованы.

• $content не имеет смысла в случае Safari, поскольку правила HTML-фильтрации не поддерживаются, поэтому оно используется только для совместимости. Правила с модификатором $content ограничиваются типом document.

• $specifichide реализован путём сканирования существующих правил скрытия элементов и удаления целевого домена из их if-domain-массива.

  • Правила $specifichide ДОЛЖНЫ таргетироваться на домен, т.е. быть такими: ||example.org^$specifichide. Правила с более специфичными шаблонами будут отклонены, т.е. ||example.org/path$specifichide не будут поддерживаться.
  • Правила $specifichide охватывают только правила, таргетированные на тот же домен, что и само правило, поддомены игнорируются. Т.е. правило @@||example.org^$specifichide отключит example.org##.banner, но проигнорирует sub.example.org##.banner. Это ограничение может быть снято, если будет реализована #72.

• Модификаторы urlblock, genericblock, generichide, elemhide, specifichide и jsinject могут использоваться только в качестве единственного модификатора в правиле. Это ограничение может быть снято в будущем: #73.

• $websocket (полностью поддерживается начиная с Safari 15).

• $ping (полностью поддерживается начиная с Safari 14).

Не поддерживается

• $app
• $header
• $method
• $strict-first-party (будет поддерживаться в будущем: #64)
• $strict-third-party (будет поддерживаться в будущем: #65)
• $to (будет поддерживаться в будущем: #60)
• $extension
• $stealth
• $cookie (частичная поддержка в будущем: #54)
• $csp
• $hls
• $inline-script
• $inline-font
• $jsonprune
• $xmlprune
• $network
• $permissions
• $redirect
• $redirect-rule
• $referrerpolicy
• $removeheader
• $removeparam
• $replace
• $urltransform

Косметические правила

Конвертер Safari поддерживает большинство косметических правил, хотя поддерживаются только правила сокрытия элементов с базовыми CSS-селекторами нативно через блокировку контента Safari, все остальные необходимо интерпретировать с помощью дополнительного расширения.

Ограничения косметических правил

• Specifying domains is subject to the same limitations as the $domain modifier of basic rules.

• Небазовые модификаторы правил поддерживаются с некоторыми ограничениями:

  • $domain — те же ограничения, что и везде.
  • $path — поддерживается, но если вы используете регулярные выражения, они будут ограничены подмножеством регулярных выражений, которые поддерживаются Safari.
  • $url — будет поддерживаться в будущем: #68

Правила скриптов/скриптлетов

Safari Converter полностью поддерживает как правила скриптов, так и правила скриптлетов. Однако эти правила могут быть интерпретированы только отдельным расширением.

опасность

For scriptlet rules, it is very important that they are run as early as possible when the page loads. The reason for that is that it's important to run them before the page scripts. К сожалению, в Safari всегда будет небольшая задержка, которая может снизить качество блокировки.

Правила фильтрации HTML

Правила HTML-фильтрации не поддерживаются и не будут поддерживаться в будущем. К сожалению, Safari не предоставляет необходимых технических возможностей для их реализации.

Базовые правила

Самые простые правила — это так называемые Базовые правила. Они используются для блокировки запросов к определённым URL-адресам. Либо, при наличии специального маркера @@ в начале правила, для разблокировки запроса. Основной принцип для этого типа правил достаточно прост: необходимо указать адрес и дополнительные параметры, которые ограничивают или расширяют область действия правила.

Подзапросы

Базовые правила, блокирующие запросы, применяются только к подзапросам. Это означает, что они не будут блокировать загрузку страницы, если это не будет явно указано с помощью модификатора $document.

Статус ответа

Браузер определяет заблокированный подзапрос как выполненный с ошибкой.

Длина правила

Правила короче 4 символов считаются некорректными и игнорируются.

Синтаксис базовых правил

      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.

комментарий

|, ||, ^ можно использовать только в правилах, содержащих шаблон URL. Например, ||example.com##.advert неверно и будет проигнорировано блокировщиком.

Визуальное представление

Рекомендуем также прочитать шпаргалку по фильтрам от Adblock Plus, чтобы лучше понять, как строятся такие правила.

Поддержка регулярных выражений

Если вы хотите добиться ещё большей гибкости при составлении правил, вы можете использовать регулярные выражения вместо упрощённой маски со специальными символами, которая используется по умолчанию.

Производительность

Такие правила работают медленнее обычных, поэтому рекомендуется избегать их или хотя бы ограничивать их область действия конкретными доменами.

Чтобы блокировщик определил, что вы хотите использовать регулярное выражение, необходимо, чтобы pattern имел особый вид:

pattern = "/" regexp "/"

Например, правило /banner\d+/$third-party применит регулярное выражение banner\d+ ко всем сторонним запросам. Правила-исключения с использованием регулярных выражений выглядят вот так: @@/banner\d+/.

Совместимость

AdGuard для Safari и AdGuard для iOS не полностью поддерживают регулярные выражения в силу ограничений Content Blocking API (см. раздел The Regular expression format).

Поддержка wildcard для доменов верхнего уровня (TLD)

Wildcard-символы поддерживаются для TLD-доменов в шаблонах косметических правил, правил HTML-фильтрации и JavaScript.

Для косметических правил, например, example.*##.banner, несколько доменов будут сопоставлены благодаря части .*, т.е. example.com, sub.example.net, example.co.uk и т. д.

При составлении базовых правил вы можете использовать wildcard-символ для TLD только вместе с модификатором $domain. Например, ||*/banners/*$image,domain=example.*.

Совместимость

В AdGuard для Windows, Mac и Android и в браузерном расширении AdGuard правила с подстановочным знаком .* соответствуют любому публичному суффиксу (или eTLD). Но для AdGuard для Safari и iOS поддерживаемый список доменов верхнего уровня ограничен из-за ограничений Safari.

Правила с wildcard для доменов верхнего уровня не поддерживаются в AdGuard Content Blocker.

Примеры базовых правил

• ||example.com/ads/* — простое правило, которое соответствует адресам типа http://example.com/ads/banner.jpg и даже http://subdomain.example.com/ads/otherbanner.jpg.

• ||example.org^$third-party — правило, которое блокирует сторонние запросы к домену example.org и его поддоменам.

• @@||example.com$document — наиболее общее правило-исключение. Такое правило полностью отключает фильтрацию на домене example.com и всех его поддоменах. Существует ряд параметров, которые также можно использовать в правилах-исключениях. Более подробно о правилах-исключениях и параметрах, которые могут в таких правилах использоваться, написано ниже.

Модификаторы базовых правил

• Базовые модификаторы
• Модификаторы типа контента
• Модификаторы правил-исключений

комментарий

Возможности, описанные в этом разделе, предназначены для опытных пользователей. Они расширяют возможности «Общих правил», но для их применения необходимо представлять, как работает браузер.

Вы можете изменить поведение «общего правила», используя дополнительные модификаторы. Список этих параметров располагается в конце правила за знаком доллара $ и разделяется запятыми.

Пример:

||domain.com^$popup,third-party

Базовые модификаторы

Приведённые ниже модификаторы самые простые и часто применяемые. В основном, они просто ограничивают сферу применения правила.

Модификатор \ Продукты	Приложения CoreLibs	AdGuard для Chromium	AdGuard для Chrome MV3	AdGuard для Firefox	AdGuard для iOS	AdGuard для Safari	AdGuard Content Blocker
$app	✅	❌	❌	❌	❌	❌	❌
$denyallow	✅	✅	✅	✅	✅	✅	❌
$domain	✅	✅	✅ *[1]	✅	✅ *[1]	✅ *[1]	✅
$header	✅	✅ *[2]	❌	✅ *[2]	❌	❌	❌
$important	✅	✅	✅	✅	✅	✅	❌
$match-case	✅	✅	✅	✅	✅	✅	✅
$method	✅	✅	✅	✅	❌	❌	❌
$popup	✅ *[3]	✅	✅ *[3]	✅	✅ *[3]	✅ *[3]	❌
$strict-first-party	⏳	❌	❌	❌	❌	❌	❌
$strict-third-party	⏳	❌	❌	❌	❌	❌	❌
$third-party	✅	✅	✅	✅	✅	✅	✅
$to	✅	✅	✅	✅	❌	❌	❌

комментарий

• ✅ — полностью поддерживается
• ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
• ⏳ — планируется к реализации, но пока недоступен ни в одном продукте
• ❌ — не поддерживается

$app

Этот модификатор ограничивает действие правила до конкретного приложения (или списка приложений). Это может быть не слишком важно для Windows и Mac, но это очень важно для мобильных устройств, где некоторые правила фильтрации должны быть связаны с конкретным приложением.

• Android — используйте имя пакета приложения, например, org.example.app.
• Windows — используйте имя процесса, например, chrome.exe.
• Mac — используйте bundle ID или имя процесса, например, com.google.Chrome.

На Mac вы можете найти bundle ID или имя процесса интересующего вас приложения в деталях соответствующих запросов в Журнале фильтрации.

Примеры

• ||baddomain.com^$app=org.example.app — правило для блокировки запросов, которые соответствуют указанной маске и отправлены Android-приложением org.example.app.
• ||baddomain.com^$app=org.example.app1|org.example.app2 — аналогичное правило, но оно работает как для приложения org.example.app1, так и для org.example.app2.

Если вы хотите, чтобы правило не применялось к определённым приложениям, начните название приложения с символа ~.

• ||baddomain.com^$app=~org.example.app — правило для блокировки запросов, соответствующих указанной маске и отправленных из любого приложения, кроме org.example.app.
• ||baddomain.com^$app=~org.example.app1|~org.example.app2 — аналогично, но в исключениях два приложения: org.example.app1 и org.example.app2.

Ограничения

В модификаторе правила к приложениям нельзя добавлять подстановочный знак (), например `$app=com..music`. Правила с таким модификатором считаются недействительными.

Совместимость

• Только AdGuard для Windows, Mac и Android имеют технические возможности для поддержки правил с модификатором $app.
• На Windows имя процесса нечувствительно к регистру, начиная с версий AdGuard для Windows c CoreLibs 1.12 или более поздней версии.

$denyallow

Модификатор $denyallow позволяет избежать создания дополнительных правил, когда требуется отключить то или иное правило для определённых доменов. Модификатор $denyallow соответствует только целевым доменам, но не доменам реферера.

Добавление этого модификатора в правило равносильно исключению доменов при помощи паттерна правила либо при помощи добавления дополнительных правил-исключений. Чтобы добавить несколько доменов в одно правило, используйте символ | в качестве разделителя.

Примеры

Это правило:

*$script,domain=a.com|b.com,denyallow=x.com|y.com

эквивалентно этому правилу:

/^(?!.*(x.com|y.com)).*$/$script,domain=a.com|b.com

или комбинации этих трёх:

*$script,domain=a.com|b.com
@@||x.com$script,domain=a.com|b.com
@@||y.com$script,domain=a.com|b.com

Ограничения

• Паттерн правила не может указывать на конкретные домены, например, не может начинаться с ||.
• Домены в значении модификатора не могут быть отменены, например $denyallow=~x.com, или иметь подстановочный домен TLD, например $denyallow=x.*, или быть регулярным выражением, например $denyallow=/\.(com\|org)/.
• $denyallow не может использоваться вместе с $to. Его можно выразить инвертированным $to: $denyallow=a.com|b.com эквивалентно $to=~a.com|~b.com.

Правила, нарушающие эти ограничения, считаются недействительными.

Совместимость

Правила с модификатором $denyallow не поддерживаются в AdGuard для iOS, Safari и AdGuard Content Blocker.

$domain

$domain ограничивает область действия правила запросами, сделанными с указанных доменов и их поддоменов (как указано в HTTP-заголовке Referer).

Синтаксис

Модификатор представляет собой список из одного или нескольких выражений, разделённых символом |, каждое из которых сопоставляется с доменом определённым образом в зависимости от его типа (см. ниже).

domains = ["~"] entry_0 ["|" ["~"] entry_1 ["|" ["~"]entry_2 ["|" ... ["|" ["~"]entry_N]]]]
entry_i = ( regular_domain / any_tld_domain / regexp )

• Regular_domain — обычное доменное имя (domain.com). Соответствует указанному домену и его поддоменам. Сопоставляется лексикографически.
• any_tld_domain — доменное имя, оканчивающееся подстановочным знаком в качестве публичного суффикса, например, для example.* это co.uk в example.co.uk. Соответствует указанному домену и его поддоменам с любым публичным суффиксом. Сопоставляется лексикографически.
• regexp — регулярное выражение, начинается и заканчивается символом /. Паттерн работает так же, как и в основных правилах URL, но символы /, $, , и | должны быть экранированы с помощью \.

информация

Правила с модификатором $domain в виде regular_domain поддерживаются всеми продуктами AdGuard.

Примеры

Просто $domain:

• ||baddomain.com^$domain=example.org блокирует запросы, которые соответствуют указанной маске и отправлены с домена example.org или его поддоменов.
• ||baddomain.com^$domain=example.org|example.com — такое же правило, но срабатывать оно будет как для домена example.org, так и для example.com.

Если вы хотите, чтобы правило не применялось к определённым доменам, начните доменное имя со знака ~.

$domain и инверсия ~:

• ||baddomain.com^$domain=example.org блокирует запросы, которые соответствуют указанной маске и отправлены с домена example.org или его поддоменов.
• ||baddomain.com^$domain=example.org|example.com — такое же правило, но срабатывать оно будет как для домена example.org, так и для example.com.
• ||baddomain.com^$domain=~example.org блокирует запросы, которые соответствуют указанной маске и отправлены с любого домена, кроме example.org и его поддоменов.
• ||baddomain.com^$domain=example.org|~foo.example.org блокирует запросы, отправленные с домена example.org и всех его поддоменов, кроме foo.example.org.
• ||baddomain.com^$domain=/(^\|.+\.)example\.(com\|org)\$/ блокирует запросы, отправляемые с доменов example.org и example.com и всех их поддоменов.
• ||baddomain.com^$domain=~a.com|~b.*|~/(^\|.+\.)c\.(com\|org)\$/ блокирует запросы, отправленные с любых доменов, кроме a.com, b с любым публичным суффиксом (b.com, b.co.uk, и т.д.), c.com, c.org и их поддоменов.

Модификатор $domain, соответствующий целевому домену:

В некоторых случаях модификатор $domain может соответствовать не только домену-рефереру, но и целевому домену. Это происходит при соблюдении всех условий:

1. Тип контента запроса — document
2. Шаблон правила не соответствует ни одному конкретному домену
3. Шаблон правила не содержит регулярных выражений
4. Модификатор $domain содержит только исключённые домены, например, $domain=~example.org|~example.com

Для сопоставления целевого домена должен выполняться следующий предикат:

1 И ((2 И 3) ИЛИ 4)

То есть, если модификатор $domain содержит только исключённые домены, то правилу не нужно выполнять второе и третье условия, чтобы соответствовать целевому домену $domain.

Если какие-либо из условий выше не выполнены, но правило содержит модификатор $cookie или $csp, модификатор всё равно будет соответствовать целевому домену.

Если реферер соответствует правилу с $domain, которое явно исключает домен реферера, то правило не сработает, даже если целевой домен тоже ему соответствует. Это также касается правил с модификаторами $cookie и $csp.

Примеры

• *$cookie,domain=example.org|example.com заблокирует cookies для всех запросов от и к example.org и example.com.
• *$document,domain=example.org|example.com заблокирует все запросы от и к example.org и example.com.

В следующих примерах предполагается, что запросы отправляются от http://example.org/page (реферер), а целевой URL — http://targetdomain.com/page.

• page$domain=example.org сработает, так как соответствует рефереру.
• page$domain=targetdomain.com сработает, так как соответствует целевому домену и удовлетворяет всем требованиям, перечисленным выше.
• ||*page$domain=targetdomain.com не сработает, так как шаблон ||*page может указывать на конкретные домены, например, example.page.
• ||*page$domain=targetdomain.com,cookie сработает, потому что правило содержит модификатор $cookie, несмотря на то, что шаблон ||*page может соответствовать конкретным доменам.
• /banner\d+/$domain=targetdomain.com не сработает, поскольку правило содержит регулярное выражение.
• page$domain=targetdomain.com|~example.org не сработает, так как домен реферера явно исключён.

Ограничения модификатора $domain

Ограничения

В AdGuard для Chrome MV3 записи regexp и any_tld_domain не поддерживаются.

Ограничения

Safari не поддерживает одновременно разрешённые и запрещённые домены, поэтому правила вида ||baddomain.com^$domain=example.org|~foo.example.org не работают в AdGuard для iOS и AdGuard для Safari.

Совместимость

Правила с регулярными выражениями в модификаторе $domain поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.11 или выше и в Браузерном расширении AdGuard с TSUrlFilter версии 3.0.0 или выше.

В AdGuard для Windows, Mac и Android с CoreLibs 1.12 или более поздней версии вместо модификатора $domain можно также использовать $from.

$header

Модификатор $header позволяет сопоставлять HTTP-ответ, имеющий определённый заголовок, с определённым значением (опционально).

Синтаксис

$header "=" h_name [":" h_value]
h_value = string / regexp

где:

• h_name (обязательно) — имя HTTP-заголовка. Сопоставляется без учёта регистра символов.
• h_value (опционально) — выражение для сопоставления значения HTTP-заголовка, может быть одним из:
  • string — последовательность символов. Лексикографически сопоставляется со значением заголовка;
  • regexp — регулярное выражение, начинается и заканчивается символом /. Паттерн работает так же, как и в основных URL-правилах, но символы /, $ и , должны быть экранированы с помощью \.

Часть модификатора со значением заголовка ":" h_value может быть опущена. В этом случае модификатор сопоставляет только имя заголовка.

Примеры

• ||example.com^$header=set-cookie:foo — блокирует запрос, ответ которого содержит заголовок Set-Cookie со значением foo.
• ||example.com^$header=set-cookie блокирует запрос, ответ которого содержит заголовок Set-Cookie с любым значением.
• @@||example.com^$header=set-cookie:/foo\, bar\$/ разблокирует запросы, ответы которых содержат заголовок Set-Cookie со значением foo, bar$.
• @@||example.com^$header=set-cookie разблокирует запрос, ответ которого содержит заголовок Set-Cookie с любым значением.

Ограничения модификатора $header

Ограничения

1. Модификатор $header может быть сопоставлен, только когда заголовки получены. Если запрос блокируется или перенаправляется на более ранней стадии, модификатор не может быть применён.
2. In AdGuard Browser Extension, the $header modifier is only compatible with $csp, $removeheader, $important, and $badfilter.

Совместимость

Правила с модификатором $header поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.11 или выше и в Браузерном расширении AdGuard с TSUrlFilter версии 3.0.0 или выше.

$important

Модификатор $important, применённый к правилу, повышает его приоритет по сравнению с правилами без такого модификатора. Даже относительно базовых правил-исключений.

Перейдите к приоритетам правил для более подробной информации.

Примеры

! блокирующее правило заблокирует все запросы, несмотря на правило-исключение
||example.org^$important
@@||example.org^

! если правило-исключение тоже содержит модификатор `$important`, его приоритет будет выше, и запросы не будут заблокированы
||example.org^$important
@@||example.org^$important

$match-case

Этот модификатор определяет правило, которое применяется только к адресам с совпадением регистра символов. По умолчанию регистр символов не учитывается.

Примеры

• */BannerAd.gif$match-case — такое правило будет блокировать http://example.com/BannerAd.gif, но не http://example.com/bannerad.gif.

Совместимость

Правила с $match-case поддерживаются в AdGuard для iOS и AdGuard для Safari с SafariConverterLib версии 2.0.43 или выше.

Все остальные продукты уже поддерживают этот модификатор.

$method

Этот модификатор ограничивает область действия правила запросами, использующими указанный набор методов HTTP. Допускается инверсия (~). Методы должны быть указаны строчными буквами, но сопоставляются они без учёта регистра. Чтобы добавить несколько методов в одно правило, используйте в качестве разделителя вертикальную черту |.

Примеры

• ||evil.com^$method=get|head блокирует только запросы GET и HEAD к evil.com.
• ||evil.com^$method=~post|~put блокирует любые запросы к evil.com, кроме POST или PUT.
• @@||evil.com$method=get разблокирует только GET-запросы к evil.com.
• @@||evil.com$method=~post разблокирует любые запросы к evil.com, кроме POST.

Ограничения

Правила, где к одному методу применяется инверсия (~), а к другому нет, считаются недействительными. Так, например, правило ||evil.com^$method=get|~head будет проигнорировано.

Совместимость

Правила с модификатором $method поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs 1.12 или более поздней версии, а также в Браузерном расширении AdGuard для Chrome, Firefox и Edge с TSUrlFilter 2.1.1 или более поздней версии.

$popup

AdGuard будет пытаться закрыть браузерную вкладку с любым адресом, подходящим под правило с этим модификатором. Обратите внимание, что закрыть можно не любую вкладку.

Примеры

• ||domain.com^$popup — при попытке перехода на сайт http://domain.com с любой страницы в браузере, новая вкладка, в которой должен открыться указанный сайт, будет закрыта.

Ограничения модификатора $popup

Ограничения

1. Модификатор $popup лучше всего работает в расширении AdGuard для браузеров на базе Chromium и Firefox.
2. В AdGuard для Chrome MV3 правила с модификатором $popup не будут работать, поэтому мы отключаем их преобразование в декларативные правила. Мы попытаемся использовать их только в нашем движке TSUrlFilter и закрывать новые вкладки программно.
3. В AdGuard для iOS и AdGuard для Safari $popup-правила просто заблокируют страницу.
4. В AdGuard для Windows, AdGuard для Mac и AdGuard для Android модификатор $popup в некоторых случаях может не обнаружить всплывающее окно, и оно не будет заблокировано. Модификатор $popup применяет тип контента document со специальным флагом, который передаётся блокирующей странице. Блокирующая страница сама может провести некоторые проверки и закрыть окно, если это действительно всплывающее окно. В противном случае страница должна быть загружена. Его можно комбинировать с другими модификаторами типа запроса, такими как $third-party, $strict-third-party, $strict-first-party и $important.

Совместимость

Правила с модификатором $popup не поддерживаются в AdGuard Content Blocker.

$strict-first-party

Работает так же, как модификатор $~third-party, но обрабатывает запрос как запрос первой стороны только в том случае, если реферер и источник имеют одинаковое имя хоста.

Примеры

• domain.com$strict-first-party — это правило применяется только к domain.com. Например, запрос с домена domain.com к домену http://domain.com/icon.ico — это запрос первой стороны. Запрос от sub.domain.com к http://domain.com/icon.ico рассматривается как сторонний (в отличие от модификатора $~third-party).

комментарий

Вы можете использовать более короткое название (псевдоним) вместо полного названия модификатора: $strict1p.

Совместимость

Правила с модификатором $strict-first-party поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.16 или выше.

$strict-third-party

Работает так же, как модификатор $third-party, но также обрабатывает запросы от домена к его поддоменам и наоборот как сторонние запросы.

Примеры

• ||domain.com^$strict-third-party — правило применяется на всех доменах, кроме domain.com. Пример стороннего запроса: http://sub.domain.com/banner.jpg (в отличие от модификатора $third-party).

комментарий

Вы можете использовать более короткое название (псевдоним) вместо полного названия модификатора: $strict3p.

Совместимость

Правила с модификатором $strict-third-party поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.16 или выше.

$third-party

Ограничение на сторонние или пользовательские запросы. Сторонним является запрос, отправленный с внешнего домена. Например, запрос к домену example.org, отправленный с домена domain.com, является сторонним.

комментарий

Чтобы считаться таковым, сторонний запрос должен соответствовать одному из следующих условий:

1. Его реферер — это не поддомен целевого домена, или наоборот. Например, запрос к subdomain.example.org, отправленный с домена example.org, не является сторонним
2. Значение его заголовка Sec-Fetch-Site — cross-site

Примеры

$third-party:

• ||domain.com^$third-party — правило применяется на всех сайтах, кроме domain.com и его поддоменов. Пример стороннего запроса: http://example.org/banner.jpg.

Если указан модификатор $~third-party, то правило применяется только к запросам, которые не являются сторонними. То есть эти запросы отправлены с того же домена.

$~third-party:

• ||domain.com$~third-party — это правило применяется исключительно к domain.com. Пример запроса, который не является сторонним: http://domain.com/icon.ico.

комментарий

Вы можете использовать более короткое название (псевдоним) вместо полного названия модификатора: $3p.

$to

$to ограничивает область действия правила запросами, сделанными на указанные домены и их поддомены. Чтобы добавить несколько доменов в одно правило, используйте символ | в качестве разделителя.

Примеры

• /ads$to=evil.com|evil.org блокирует любые запросы к evil.com или evil.org и их поддоменам с путём, соответствующим /ads.
• /ads$to=~not.evil.com|evil.com блокирует любые запросы к evil.com и его поддоменам с путём, совпадающим с /ads, за исключением запросов к not.evil.com и его поддоменам.
• /ads$to=~good.com|~good.org блокирует любые запросы с путём, соответствующим /ads, за исключением запросов к good.com или good.org и их поддоменам.

Ограничения

$denyallow не может использоваться вместе с $to. Его можно выразить инвертированным $to: $denyallow=a.com|b.com эквивалентно $to=~a.com|~b.com.

Совместимость

Правила с модификатором $to поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.12 или выше и в Браузерном расширении AdGuard с TSUrlFilter версии 2.1.3 или выше.

Модификаторы типа контента

Существует целый набор модификаторов, которые ограничивают область применения правила только определённым типом контента. Эти модификаторы можно комбинировать, чтобы, например, распространить правило одновременно и на картинки, и на скрипты.

Совместимость

Существует большая разница в том, как AdGuard определяет тип контента на разных платформах. В случае Браузерного расширения AdGuard, тип контента для каждого запроса предоставляется самим браузером. В случае AdGuard для Windows, Mac и Android для определения используется следующая методика: сначала мы пытаемся определить тип запроса по заголовку запроса Sec-Fetch-Dest или по расширению имени файла. Если запрос не заблокирован на этом этапе, то тип запроса уточняется с использованием заголовка Content-Type в начале ответа, полученного от сервера.

Примеры модификаторов типа контента

• ||example.org^$image — соответствует всем картинкам с домена example.org.
• ||example.org^$script,stylesheet — соответствует всем скриптам и стилям с домена example.org.
• ||example.org^$~image,~script,~stylesheet — соответствует всем запросам к домену example.org, кроме картинок, скриптов и стилей.

Модификатор \ Продукты	Приложения CoreLibs	AdGuard для Chromium	AdGuard для Chrome MV3	AdGuard для Firefox	AdGuard для iOS	AdGuard для Safari	AdGuard Content Blocker
$document	✅	✅	✅	✅	✅	✅	❌
$font	✅	✅	✅	✅	✅	✅	✅
$image	✅	✅	✅	✅	✅	✅	✅
$media	✅	✅	✅	✅	✅	✅	✅
$object	✅	✅	✅	✅	❌	❌	✅
$other	✅	✅	✅	✅	✅	✅	❌
$ping	✅ *[1]	✅	✅	✅	❌	❌	✅
$script	✅	✅	✅	✅	✅	✅	✅
$stylesheet	✅	✅	✅	✅	✅	✅	✅
$subdocument	✅ *[2]	✅	✅	✅	✅	✅	❌
$websocket	✅	✅	✅	✅	✅ *[3]	✅ *[3]	❌
$xmlhttprequest	✅	✅	✅	✅	✅	✅	✅
$webrtc 🚫	❌	❌	❌	❌	❌	❌	❌
$object-subrequest 🚫	❌	❌	❌	❌	❌	❌	❌

комментарий

• ✅ — полностью поддерживается
• ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
• ❌ — не поддерживается
• 🚫 — удалён и больше не поддерживается

$document

Правило соответствует запросам основного документа страницы, т.е. HTML-документа, который загружается во вкладке браузера. Оно не подходит для iframe, для них существует модификатор $subdocument.

По умолчанию AdGuard не блокирует запросы, которые загружаются во вкладке браузера (например, «обход основного фрейма»). Идея заключается в том, чтобы не препятствовать загрузке страниц, поскольку пользователь явно указал, что он хочет, чтобы эта страница была загружена. Однако, если использовать модификатор $document, то AdGuard не будет использовать эту логику и предотвратит загрузку страницы. Другими словами, заблокирует её.

Если этот модификатор используется в правиле-исключении (@@), то оно полностью отключает блокировку на соответствующих страницах. Это равносильно одновременному использованию модификаторов $elemhide, $content, $urlblock, $jsinject и $extension.

Примеры

• @@||example.com^$document полностью отключает фильтрацию на всех страницах сайта example.com и всех его поддоменах.

• ||example.com^$document блокирует запрос HTML-документа на example.com с помощью блокирующей страницы.

• ||example.com^$document,redirect=noopframe перенаправляет запрос HTML-документа сайта example.com на пустой HTML-документ.

• ||example.com^$document,removeparam=test удаляет параметр test из запроса HTML-документа к example.com.

• ||example.com^$document,replace=/test1/test2/ заменяет test1 на test2 в запросе HTML-документа к example.com.

комментарий

Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $doc.

$font

Правило соответствует запросам к файлам шрифтов (например, файлам с расширением .woff).

$image

Правило соответствует запросам к изображениям.

$media

Правило соответствует запросам к медиафайлам — музыке и видео, например файлам .mp4.

$object

Правило соответствует ресурсам плагинов браузера, например, Java или Flash.

Совместимость

Правила с модификатором $object не поддерживаются в AdGuard для Safari и AdGuard для iOS.

$other

Правило применяется к запросам, тип которых не был определён или не соответствует перечисленным выше типам.

$ping

Правило соответствует запросам, вызванным атрибутом navigator.sendBeacon() или ping в ссылках.

Ограничения модификатора $ping

Ограничения

AdGuard для Windows, Mac и Android часто не может точно определить navigator.sendBeacon(). Не рекомендуется использовать $ping в фильтрах, которые должны использоваться продуктами AdGuard на базе CoreLibs.

Совместимость

Правила с модификатором $ping не поддерживаются в AdGuard для Safari и AdGuard для iOS.

$script

The rule corresponds to script requests, e.g. JavaScript, VBScript.

$stylesheet

Правило соответствует запросам к файлам CSS-стилей.

комментарий

Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $css.

$subdocument

Правило соответствует запросам к встроенным страницам — HTML-теги frame и iframe.

Примеры

• ||example.com^$subdocument блокирует запросы встроенных страниц (frame и iframe) к example.com и всем его поддоменам.
• ||example.com^$subdocument,domain=domain.com блокирует запросы встроенных страниц (frame и iframe) к example.com и его поддоменам с domain.com и всех его поддоменов.

комментарий

Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $frame.

$subdocument modifier limitations

Ограничения

В AdGuard для Windows, Mac и Android поддокументы определяются по заголовку Sec-Fetch-Dest, если он присутствует. В противном случае некоторые основные страницы могут рассматриваться как поддокументы.

Совместимость

Правила с модификатором $subdocument не поддерживаются в AdGuard Content Blocker.

$websocket

Правило применяется только к соединениям WebSocket.

Ограничения модификатора $websocket

Ограничения

Что касается AdGuard для Safari и AdGuard для iOS, то они поддерживаются на устройствах с macOS Monterey (версия 12) и iOS 16 и выше соответственно.

Совместимость

Модификатор $websocket поддерживается во всех продуктах AdGuard, кроме AdGuard Content Blocker.

$xmlhttprequest

The rule applies only to ajax requests (requests sent via the JavaScript object XMLHttpRequest).

комментарий

Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $xhr.

Совместимость

AdGuard для Windows, Mac и Android часто не может точно определить этот тип модификатора и иногда определяет его как $other или $script. Они могут надёжно обнаружить этот тип контента только при фильтрации современных браузеров, поддерживающих Fetch metadata request headers.

$object-subrequest (удалён)

Уведомление об удалении

Модификатор $object-subrequest удалён и больше не поддерживается. Правила с ним не работают. Правило соответствует запросам плагинов браузера (обычно это Flash).

$webrtc (удалён)

Уведомление об удалении

Этот модификатор удалён и больше не поддерживается. Правила с ним не работают. Если вы хотите блокировать WebRTC, рассмотрите возможность использования скриптлета nowebrtc.

Правило применяется только к WebRTC-соединениям.

Примеры

• ||example.com^$webrtc,domain=example.org — это правило блокирует WebRTC-соединения c example.com от example.org.
• @@*$webrtc,domain=example.org — это правило отключает оболочку RTC для example.org.

Модификаторы правил исключений

Правила исключений отключают действие других базовых правил для адресов, которым они соответствуют. Они начинаются с маркера @@. Для таких правил работают все базовые модификаторы, перечисленные выше. Также добавляется несколько специальных модификаторов, которые будут описаны ниже.

Визуальное представление

Рекомендуем также прочитать шпаргалку по фильтрам от Adblock Plus, чтобы лучше понять, как строятся правила исключений.

Модификатор \ Продукты	Приложения CoreLibs	AdGuard для Chromium	AdGuard для Chrome MV3	AdGuard для Firefox	AdGuard для iOS	AdGuard для Safari	AdGuard Content Blocker
$content	✅	❌	❌	✅	❌	❌	❌
$elemhide	✅	✅	✅	✅	✅	✅	✅
$extension	✅	❌	❌	❌	❌	❌	❌
$jsinject	✅	✅	✅ *[1]	✅	✅	✅	❌
$stealth	✅	✅	❌	✅	❌	❌	❌
$urlblock	✅	✅	❌	✅	✅ *[2]	✅ *[2]	❌
$genericblock	✅	✅	✅	✅	✅ *[3]	✅ *[3]	❌
$generichide	✅	✅	✅	✅	✅	✅	✅
$specifichide	✅	✅	✅	✅	❌	❌	❌

комментарий

• ✅ — полностью поддерживается
• ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
• ❌ — не поддерживается

информация

By default, without specifying additional content type modifiers, exception rule modifiers override other basic rules only for main frame document requests (see $document for more information about main frame document).

Например:

• The website example.com contains an iframe pointing to example1.com.
• The rule #%#//console.log('test') is applied.

In this case, the log will appear twice in the console: once for the main frame document and once for iframe.

If you add the @@||example.com^$jsinject rule, the log will appear only once for iframe.

$content

Отключает HTML-фильтрацию, правила $hls, $replaceи $jsonprune на страницах, соответствующих правилу.

Примеры

• @@||example.com^$content отключает все правила модификации контента на страницах example.com и всех его поддоменах.

$elemhide

Отключает любые косметические правила на страницах, подходящих под правило.

Примеры

• @@||example.com^$elemhide отменяет все косметические правила для страниц на сайте example.com и на всех его поддоменах.

комментарий

Вы можете использовать более короткое название (псевдоним) вместо полного названия модификатора: $ehide.

$extension

Отключает пользовательские скрипты — определённые или все для данного домена.

Синтаксис

$extension[="userscript_name1"[|"userscript_name2"[|"userscript_name3"[...]]]]

userscript_name(i) обозначает конкретное имя пользовательского скрипта, которое должно быть отключено модификатором. Модификатор может содержать любое количество имён пользовательских скриптов или не содержать их вовсе. В последнем случае модификатор отключает все пользовательские скрипты.

Имена пользовательских скриптов обычно содержат пробелы или другие специальные символы, поэтому необходимо заключать их в кавычки. Поддерживаются как одинарные ('), так и двойные (") ASCII-кавычки. Несколько имён пользовательских скриптов должны быть разделены вертикальной чертой (|). Однако если имя пользовательского скрипта представляет собой одно слово без специальных символов, то его можно использовать без кавычек.

Вы также можете исключить пользовательский скрипт из фильтрации, добавив перед ним символ ~. В этом случае пользовательский скрипт не будет отключён модификатором.

$extension=~"userscript name"

комментарий

Исключая пользовательский скрипт из фильтрации, обязательно выносите символ ~ за кавычки.

Если имя пользовательского скрипта содержит кавычки ("), запятые (,) или вертикальную черту (|), они должны быть экранированы обратной косой чертой (\).

$extension="userscript name\, with \"quote\""

Примеры

• @@||example.com^$extension="AdGuard Assistant" отключает пользовательский скрипт Помощник AdGuard на сайте example.com.
• @@||example.com^$extension=MyUserscript отключает пользовательский скрипт MyUserscript на сайте example.com.
• @@||example.com^$extension='AdGuard Assistant'|'AdGuard Popup Blocker' отключает оба пользовательских скрипта Помощник AdGuard и Блокировщик всплывающей рекламы от AdGuard на сайте example.com.
• @@||example.com^$extension=~"AdGuard Assistant" отключает все пользовательские скрипты на сайте example.com, кроме Помощника AdGuard.
• @@||example.com^$extension=~"AdGuard Assistant"|~"AdGuard Popup Blocker" отключает все пользовательские скрипты на сайте example.com, кроме Помощника AdGuard и Блокировщика всплывающей рекламы от AdGuard.
• @@||example.com^$extension — пользовательские скрипты не будут работать на страницах сайта example.com.
• @@||example.com^$extension="AdGuard \"Assistant\"" отключает пользовательский скрипт AdGuard "Assistant" на сайте example.com.

Совместимость

• Только AdGuard для Windows, Mac и Android имеют технические возможности для поддержки правил с модификатором $extension.
• Правила с модификатором $extension поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.13 или выше.

$jsinject

Запрещает добавлять JavaScript-код на страницу. О скриптлетах и javascript-правилах речь пойдёт ниже.

Примеры

• @@||example.com^$jsinject отменяет все javascript-правила для страниц на сайте example.com и на всех его поддоменах.

Ограничения модификатора $jsinject

Ограничения

Правила с модификатором $jsinject не могут быть преобразованы в DNR в AdGuard для Chrome MV3. Мы используем их только в движке TSUrlFilter для отключения некоторых косметических правил.

Совместимость

Модификатор $jsinject не поддерживается AdGuard для Chrome MV3 (пока) и AdGuard Content Blocker.

$stealth

Отключает Защиту от трекинга для всех страниц и запросов, подходящих под это правило.

Синтаксис

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

Здесь opt(i) — опции Защиты от трекинга‎, отключённые модификатором. Модификатор может содержать любое количество опций (см. ниже) или не содержать их вовсе. В последнем случае модификатор отключает Защиту от трекинга полностью.

Список доступных опций модификатора:

• searchqueries отключает опцию Скрывать поисковые запросы
• donottrack отключает опцию Просить сайты не отслеживать вас
• 3p-cookie отключает Самоуничтожение сторонних куки
• 1p-cookie отключает Самоуничтожение куки сайта
• 3p-cache отключает опцию Блокировать заголовки ETag и If-None-Match
• 3p-auth отключает опцию Блокировать сторонний заголовок авторизации
• webrtc отключает опцию Блокировать WebRTC
• push отключает опцию Блокировать Push API
• location отключает опцию Блокировать Location API
• flash отключает опцию Блокировать Flash
• java отключает опцию Блокировать Java
• referrer отключает опцию Скрывать Referer от третьих лиц
• useragent отключает опцию Скрывать User-Agent
• ip отключает опцию Скрывать IP-адрес
• xclientdata отключает опцию Удалять заголовок X-Client-Data
• dpi отключает опцию Защищать от DPI

Примеры

• @@||example.com^$stealth полностью отключает Защиту от трекинга для запросов к example.com и поддоменам, кроме блокировки куки и скрытия параметров отслеживания (см. ниже).
• @@||domain.com^$script,stealth,domain=example.com отключает Защиту от трекинга только для script-запросов к domain.com и поддоменам на example.com и всех его поддоменах.
• @@||example.com^$stealth=3p-cookie|dpi отключает блокировку сторонних куки-файлов и меры защиты от DPI для запросов к example.com.

комментарий

Блокировка куки и удаление параметров отслеживания достигается с помощью правил с модификаторами $cookie, $urltransform и $removeparam. Правила-исключения, которые содержат только модификатор $stealth, не будут выполнять эти действия. Если вы хотите полностью отключить все функции Защиты от трекинга для определённого домена, нужно включить в правило все три модификатора: @@||example.org^$stealth,removeparam,cookie.

Ограничения

• Параметры модификатора должны быть написаны строчными буквами, т. е. $stealth=DPI будет отклонено.
• Параметры модификатора не могут отрицаться, т.е. $stealth=~3p-cookie будет отклонён.
• Браузерное расширение AdGuard поддерживает только опции searchqueries, donottrack, referrer, xclientdata, 1p-cookie и 3p-cookie.

Совместимость

• Защита от трекинга доступна в AdGuard для Windows, AdGuard для Mac, AdGuard для Android и расширении AdGuard для Firefox и браузеров на базе Chromium, за исключением AdGuard для Chrome MV3. Все остальные продукты будут игнорировать правила с модификатором $stealth.
• Правила с модификатором $stealth поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.10 или выше и в Браузерном расширении AdGuard с TSUrlFilter версии 3.0.0 или выше.

$urlblock

Отключает все правила $cookie и блокировку всех запросов со страниц, соответствующих правилу.

Примеры

• @@||example.com^$urlblock — любые запросы, отправленные со страниц сайта example.com и всех его поддоменов, не будут блокироваться.

Ограничения модификатора $urlblock

Ограничения

В AdGuard для iOS и AdGuard для Safari правила $urlblock работают как исключение $document — они разблокируют всё.

Совместимость

Правила с модификатором $urlblock не поддерживаются в AdGuard Content Blocker и AdGuard для Chrome MV3.

Generic-правила

Перед тем, как перейти к описанию следующих модификаторов, необходимо ввести определение generic-правил. Правило относится к generic-правилам, если его действие не ограничено конкретными доменами. Также поддерживается wildcard-символ *.

Например, это generic-правила:

###banner
*###banner
#@#.adsblock
*#@#.adsblock
~domain.com###banner
||domain.com^
||domain.com^$domain=~example.com

А это уже не generic-правила:

domain.com###banner
||domain.com^$domain=example.com

$genericblock

Отключает все базовые правила generic на страницах, подходящих под правило-исключение.

Примеры

• @@||example.com^$genericblock отключает базовые правила generic на любых страницах example.com и всех поддоменах.

Ограничения модификатора $genericblock

Ограничения

В AdGuard для iOS и AdGuard для Safari правила $genericblock работают как исключение $document — они разблокируют всё.

Совместимость

Правила с модификатором $genericblock не поддерживаются в AdGuard Content Blocker и AdGuard для Chrome MV3.

$generichide

Отключает все косметические правила generic на страницах, соответствующих правилу-исключению.

Примеры

• @@||example.com^$generichide отключает косметические правила generic на страницах сайта example.com и всех его поддоменах.

комментарий

Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $ghide.

specifichide

Отключает все specific-правила скрытия элементов и CSS-правила, но не отключает general-правила. Имеет эффект, противоположный $generichide.

Примеры

• @@||example.org^$specifichide отключает example.org##.banner, но не ##.banner.

комментарий

Вы можете использовать более короткое имя (псевдоним) вместо полного имени модификатора: $shide.

комментарий

Все косметические правила, а не только specific, можно отключить модификатором $elemhide.

Совместимость

Правила с модификатором $specifichide не поддерживаются в AdGuard для iOS, AdGuard для Safari и AdGuard Content Blocker.

Расширенные возможности

Модификаторы, описанные в этом разделе, полностью меняют поведение базовых правил.

Модификатор \ Продукты	Приложения CoreLibs	AdGuard для Chromium	AdGuard для Chrome MV3	AdGuard для Firefox	AdGuard для iOS	AdGuard для Safari	AdGuard Content Blocker
$all	✅	✅	✅ *[1]	✅	✅	✅	❌
$badfilter	✅	✅	✅ *[2]	✅	✅	✅	❌
$cookie	✅	✅	✅ *[3]	✅	❌	❌	❌
$csp	✅	✅	✅	✅	❌	❌	❌
$hls	✅	❌	❌	❌	❌	❌	❌
$inline-font	✅	✅	✅	✅	❌	❌	❌
$inline-script	✅	✅	✅	✅	❌	❌	❌
$jsonprune	✅	❌	❌	❌	❌	❌	❌
$xmlprune	✅	❌	❌	❌	❌	❌	❌
$network	✅	❌	❌	❌	❌	❌	❌
$permissions	✅ *[4]	✅	✅	✅ *[4]	❌	❌	❌
$redirect	✅	✅	✅ *[5]	✅	❌	❌	❌
$redirect-rule	✅	✅	❌	✅	❌	❌	❌
$referrerpolicy	✅	❌	⏳	❌	❌	❌	❌
$removeheader	✅	✅	❌	✅	❌	❌	❌
$removeparam	✅	✅	✅ *[6]	✅	❌	❌	❌
$replace	✅	❌	❌	✅	❌	❌	❌
$urltransform	✅	❌	❌	❌	❌	❌	❌
noop	✅	✅	✅	✅	✅	✅	❌
$empty 👎	✅	✅	✅	✅	❌	❌	❌
$mp4 👎	✅	✅	✅	✅	❌	❌	❌

комментарий

• ✅ — полностью поддерживается
• ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
• ⏳ — планируется к реализации, но пока недоступен ни в одном продукте
• ❌ — не поддерживается
• 👎 — устарел; всё ещё поддерживается, но в будущем будет удалён

$all

Модификатор $all состоит из всех модификаторов content-type и $popup. Например, правило ||example.org^$all конвертируется в правило:

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

Ограничения

Этот модификатор нельзя использовать как исключение с маркером @@.

Ограничения модификатора $all

Ограничения

Так как $popup является частью $all, модификатор $all не поддерживается в AdGuard для Chrome MV3 из-за ограничений модификатора $popup.

Совместимость

Правила с модификатором $all не поддерживаются в AdGuard Content Blocker.

$badfilter

Правила, содержащие модификатор $badfilter, отключают другие базовые правила, на которые они ссылаются. Это означает, что текст отключённого правила должен соответствовать тексту $badfilter-правила (за исключением самого модификатора $badfilter).

Примеры

• ||example.com$badfilter отключает ||example.com
• ||example.com$image,badfilter отключает ||example.com$image
• @@||example.com$badfilter отключает @@||example.com
• ||example.com$domain=domain.com,badfilter отключает ||example.com$domain=domain.com

Правила с модификатором $badfilter могут отключать другие базовые правила для определённых доменов, если они соответствуют следующим условиям:

1. В правиле есть модификатор $domain
2. В модификаторе $domain нет отрицания домена ~

В этом случае, правило с $badfilter отключит соответствующее базовое правило для доменов, указанных как в правиле с $badfilter, так и в базовом правиле. Обратите внимание, что логика wildcard для доменов верхнего уровня (TLD) здесь также применима.

Примеры

• /some$domain=example.com|example.org|example.io отключено для example.com правилом /some$domain=example.com,badfilter
• /some$domain=example.com|example.org|example.io отключено для example.com и example.org правилом /some$domain=example.com|example.org,badfilter
• /some$domain=example.com|example.org и /some$domain=example.io полностью отключены правилом /some$domain=example.com|example.org|example.io,badfilter
• /some$domain=example.com|example.org|example.io полностью отключено правилом /some$domain=example.*,badfilter
• /some$domain=example.* отключено для example.com и example.org правилом /some$domain=example.com|example.org,badfilter
• /some$domain=example.com|example.org|example.io НЕ отключено для example.com правилом /some$domain=example.com|~example.org,badfilter, поскольку значение модификатора $domain содержит отрицание домена

Ограничения модификатора $badfilter

Ограничения

В AdGuard для Chrome MV3 правило с модификатором $badfilter применяется в DNR только в том случае, если оно полностью отменяет исходное правило. Мы не можем рассчитать его, если он отменён лишь частично. Примеры

Совместимость

Правила с модификатором $badfilter не поддерживаются в AdGuard Content Blocker.

$cookie

Модификатор $cookie полностью меняет поведение правила. Вместо того, чтобы блокировать запрос, этот модификатор позволяет AdGuard блокировать или изменять заголовки Cookie или Set-Cookie.

Несколько правил, соответствующих одному запросу

В случае, когда несколько правил $cookie соответствуют одному запросу, мы применим каждое из них по очереди.

Синтаксис

$cookie [= name[; maxAge = seconds [; sameSite = strategy ]]]

где:

• name — опционально, строка или регулярное выражение для сопоставления с именем куки.
• seconds — количество секунд, на которое сместится истечение срока действия куки.
• strategy — строка для стратегии Same-Site, которая будет применена к куки.

Например,

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

каждый раз, когда AdGuard встречает куки с именем NAME в запросе к example.org, он будет делать следующее:

• Установит дату истечения срока хранения на текущее время плюс 3600 секунд
• Позволяет куки использовать стратегию Same-Site.

Экранирование специальных символов

Если для сопоставления используется регулярное выражение name, необходимо экранировать два символа: запятую , и знак доллара $. Используйте для этого обратный слеш \. Например, экранированная запятая будет выглядеть так: \,.

Примеры

• ||example.org^$cookie блокирует все куки, установленные example.org; это эквивалентно установке maxAge=0
• $cookie=__cfduid блокирует куки CloudFlare везде
• $cookie=/__utm[a-z]/ блокирует куки Google Analytics везде
• ||facebook.com^$third-party,cookie=c_user не позволяет Facebook отслеживать вас, даже если вы вошли в систему

Существует два способа деактивации правил $cookie: основной предполагает использование исключения с @@ — @@||example.org^$cookie. Альтернативный метод использует исключение $urlblock (также входящее в псевдоним исключения $document — $elemhide,jsinject,content,urlblock,extension). Вот как это работает:

• @@||example.org^$cookie разблокирует все куки-файлы, установленные example.org
• @@||example.org^$urlblock разблокирует все файлы куки, установленные example.org, и отключает блокировку всех запросов, отправленных с example.org
• @@||example.org^$cookie=concept разблокирует один куки-файл с именем concept
• @@||example.org^$cookie=/^_ga_/ разблокирует все куки, соответствующие регулярному выражению

Ограничения модификатора $cookie

Ограничения

В AdGuard for Chrome MV3 мы удаляем куки двумя способами: из content-script, к которому у нас есть доступ, и из слушателя событий onBeforeSendHeaders. Поскольку onBeforeSendHeaders и другие слушатели больше не блокируют выполнение запроса, мы не можем удалить их во всех случаях. Вы можете проверить, работает ли правило, с помощью этого теста.

Ограничения

Правила $cookie поддерживают эти типы модификаторов: $domain, $~domain, $important, $third-party, $~third-party, strict-third-party и strict-first-party.

Совместимость

Правила с модификатором $cookie не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.

$csp

Этот модификатор полностью меняет поведение правила. Когда он применяется, правило не блокирует запрос. Вместо этого будут изменены заголовки ответа.

информация

Чтобы использовать правила этого типа, необходимо базовое понимание слоя безопасности Content Security Policy.

Для запросов, подходящих под $csp-правило, мы усилим политику безопасности ответа, добавив дополнительную политику, равнозначную содержимому модификатора $csp. Правила $csp применяются независимо от правил любого другого типа. На него могут повлиять только исключения на уровне документа (см. раздел с примерами), но никак не другие базовые правила.

Несколько правил, соответствующих одному запросу

В случае, когда несколько правил $csp соответствуют одному запросу, мы применим каждое из них.

Синтаксис

Синтаксис значений $csp похож на синтаксис заголовков Политики Безопасности Контента.

Значение $csp может быть пустым в случае правил-исключений. См. примеры ниже.

Примеры

• ||example.org^$csp=frame-src 'none' запрещает все фреймы на example.org и его поддоменах.
• @@||example.org/page/*$csp=frame-src 'none' отключает все правила с модификатором $csp, в точности соответствующим frame-src 'none' на всех страницах, подходящих под паттерн правила. Например, правило выше.
• @@||example.org/page/*$csp отключает все $csp-правила на всех страницах, подходящих под паттерн правила.
• ||example.org^$csp=script-src 'self' 'unsafe-eval' http: https: отключает инлайн-скрипты на всех страницах, подходящих под паттерн правила.
• @@||example.org^$document или @@||example.org^$urlblock отключает все $csp-правила на всех страницах, подходящих под паттерн правила.

Ограничения

• Некоторые символы запрещены в значении $csp: ,, $.
• Правила $csp поддерживают три типа модификаторов: $domain, $important и $subdocument.
• Правила с директивами report-* считаются некорректными.

Совместимость

Правила с модификатором $csp не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.

$hls

Правила $hls модифицируют ответ на соответствующий правилу запрос. Они предназначены для удаления сегментов из HLS-плейлистов (RFC 8216).

комментарий

Слово segment в документации означает Media Segment или playlist (как часть Master Playlist): с точки зрения правил $hls, Master Playlist и Media Playlist неразличимы.

Синтаксис

• ||example.org^$hls=urlpattern удаляет сегменты, URL которых соответствует паттерну urlpattern. Паттерн работает так же, как в базовых URL-правилах, однако символы /, $ и , в составе urlpattern необходимо экранировать с помощью \.
• ||example.org^$hls=/regexp/options удаляет сегменты, в которых URL-адрес или один из тегов (для определённых параметров, если они есть) соответствуют регулярному выражению regexp. Доступные значения options:
  • t — вместо URL-адреса сегмента проверять каждый тег сегмента на соответствие регулярному выражению. Сегмент с соответствующим тегом будет удалён;
  • i — сделать регулярное выражение нечувствительным к регистру символов.

Символы /, $ и , должны быть экранированы символом \ внутри regexp.

Исключения

Basic URL exceptions shall not disable rules with the $hls modifier. Отключить их можно следующим образом:

• @@||example.org^$hls отключает все правила $hls для ответов от URL-адресов, соответствующих ||example.org^ URL.
• @@||example.org^$hls=text отключает все правила $hls, у которых значение модификатора $hls равно text, для ответов с URL-адресов, соответствующих ||example.org^ URL.

подсказка

$hls также можно отключить с помощью правил-исключений с модификаторами $document, $content и $urlblock.

комментарий

Если несколько правил $hls соответствуют одному и тому же запросу, их эффект суммируется.

Примеры

• ||example.org^$hls=\/videoplayback^?*&source=dclk_video_ads удаляет все сегменты с соответствующим URL.
• ||example.org^$hls=/\/videoplayback\/?\?.*\&source=dclk_video_ads/i делает почти то же самое, но с помощью регулярного выражения вместо URL-паттерна.
• ||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t удаляет все сегменты с соответствующим тегом.

О формате HLS-плейлистов

Краткое описание спецификации:

1. HLS-плейлист — это набор текстовых строк
2. Можно использовать пустую строку, комментарий (начинается с #), тег (тоже начинается с #, распознаётся по содержанию) или URL
3. Строка с URL называется сегментом
4. Тег может относиться к одному сегменту, т.е. к первой строке с URL, следующей после данного тега, ко всем последующим сегментам (пока не встретится тег с тем же названием) или ко всему плейлисту

Замечания, касающиеся правил $hls:

1. Когда сегмент удаляется, все теги, относящиеся только к нему, тоже удаляются
2. Теги, относящиеся к нескольким сегментам, удаляются, если все эти сегменты были удалены
3. Поскольку различные типы тегов невозможно распознать по синтаксису, мы распознаем все теги, указанные в RFC, плюс некоторые нестандартные теги, которые встречались нам в полевых условиях. Любые строки, начинающиеся с # и не распознанные как тег, пропускаются без модификации и не сопоставляются с правилами
4. Теги не будут сопоставлены, если они применяются ко всему списку воспроизведения, а правила $hls нельзя использовать для их удаления, поскольку эти типы правил предназначены для удаления сегментов. Если вы знаете, что делаете, вы можете использовать правила $replace для удаления или перезаписи только одного тега из плейлиста

Пример работы правил:

Исходный ответ

#EXTM3U
#EXT-X-TARGETDURATION:10
#EXTINF,5
preroll.ts
#UPLYNK-SEGMENT:abc123,ad
#UPLYNK-KEY:aabb1122
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#UPLYNK-SEGMENT:abc123,segment
#UPLYNK-KEY:ccdd2233
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#EXT-X-ENDLIST

Применённые правила

||example.org^$hls=preroll
||example.org^$hls=/#UPLYNK-SEGMENT:.*\,ad/t

Модифицированный ответ

#EXTM3U
#EXT-X-TARGETDURATION:10
#UPLYNK-SEGMENT:abc123,segment
#UPLYNK-KEY:ccdd2233
#EXT-X-DISCONTINUITY
#EXTINF,10
01.ts
#EXTINF,10
02.ts
#EXT-X-ENDLIST

Ограничения

• Правила с модификатором $hls могут быть использованы только в доверенных фильтрах.
• Правила $hls совместимы только с модификаторами $domain, $third-party, $strict-third-party, $strict-first-party, $app, $important, $match-case и $xmlhttprequest.
• Правила $hls применимы только к HLS-плейлистам, т. е. к тексту в кодировке UTF-8, начинающемуся со строки #EXTM3U. Никакие другие ответы не будут модифицированы этими правилами.
• Правила с $hls не применяются к ответам размером больше 10 МБ.

Совместимость

Правила с модификатором $hls поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 10 или выше.

$inline-script

Модификатор $inline-script предназначен для блокировки встроенного в страницу кода JavaScript с использованием политики безопасности контента (CSP). Он повышает безопасность, не позволяя загружать встроенную рекламу или потенциально вредоносные скрипты. Правило ||example.org^$inline-script конвертируется в правило синтаксиса CSP:

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

$inline-font

Модификатор $inline-font предназначен для блокировки встроенных в страницу шрифтов с использованием политики безопасности контента (CSP). Он повышает безопасность, не позволяя загружать встроенные шрифты, которые могут использоваться для сбора данных и фингерпринтинга. Правило ||example.org^$inline-font конвертируется в правило синтаксиса CSP:

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

$jsonprune

Правила $jsonprune модифицируют ответ на соответствующий запрос, удаляя JSON-элементы, которые соответствуют модифицированному выражению JSONPath. Эти правила не изменяют ответы, которые не являются действительными JSON-документами.

В AdGuard для Windows, Mac и Android с CoreLibs версии 1.11 или выше $jsonprune также поддерживает модификацию документов JSONP (padded JSON).

Синтаксис

• ||example.org^$jsonprune=expression удаляет из ответа элементы, соответствующие изменённому JSONPath-выражению expression.

Из-за особенностей работы парсинга правил символы $ и , внутри expression должны экранироваться символом \.

Модифицированный синтаксис JSONPath имеет следующие отличия от оригинального:

1. Выражения на сценарном языке (script expressions) не поддерживаются
2. Поддерживаемые предикаты (filter expressions):
   • ?(has <key>) — верно, если текущий объект содержит указанный ключ
   • ?(key-eq <key> <value>) — верно, если текущий объект содержит указанный ключ и его значение равно указанному
   • ?(key-substr <key> <value>) — верно, если указанное значение является подстрокой значения ключа текущего объекта
3. Пробелы вне двойных или одинарных кавычек игнорируются
4. Можно использовать строки как с двойными, так и с одинарными кавычками
5. Выражения, оканчивающиеся на .., не поддерживаются
6. Разрешено указывать несколько срезов массива (array slices) в квадратных скобках

Существуют различные онлайн-инструменты, которые делают работу с выражениями JSONPath удобнее:

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

Обратите внимание, что различные имплементации JSONPath обладают уникальными особенностями и могут быть несовместимы друг с другом.

Исключения

Базовые URL-исключения не должны отключать правила с модификатором $jsonprune. Отключить их можно следующим образом:

• @@||example.org^$jsonprune отключает все правила $jsonprune для ответов от URL-адресов, соответствующих ||example.org^.
• @@||example.org^$jsonprune=text отключает все правила $jsonprune, у которых значение модификатора $jsonprune равно text, для ответов с URL-адресов, соответствующих ||example.org^ URL.

$jsonprune также можно отключить с помощью правил-исключений с модификаторами $document, $content и $urlblock.

комментарий

Когда одному и тому же запросу соответствует несколько правил с модификатором $jsonprune, они сортируются в лексикографическом порядке: первое правило применяется к исходному ответу, а каждое из оставшихся правил применяется к результату применения предыдущего.

Примеры

• ||example.org^$jsonprune=\$..[one\, "two three"] удаляет все вхождения ключей one и two three в любом месте JSON-документа.

До

{
    "one": 1,
    "two": {
        "two three": 23,
        "four five": 45
    }
}

После

{
    "two": {
        "four five": 45
    }
}

• ||example.org^$jsonprune=\$.a[?(has ad_origin)] удаляет всех прямых потомков a, которые обладают свойством ad_origin.

До

{
    "a": [
        {
            "ad_origin": "https://example.org",
            "b": 42
        },
        {
            "b": 1234
        }
    ]
}

После

{
    "a": [
        {
            "b": 1234
        }
    ]
}

• ||example.org^$jsonprune=\$.*.*[?(key-eq 'Some key' 'Some value')] удаляет все элементы на уровне вложенности 3, обладающие свойством Some key, равным Some value.

До

{
    "a": {"b": {"c": {"Some key": "Some value"}, "d": {"Some key": "Other value"}}},
    "e": {"f": [{"Some key": "Some value"}, {"Some key": "Other value"}]}
}

После

{
    "a": {"b": {"d": {"Some key": "Other value"}}},
    "e": {"f": [{"Some key": "Other value"}]}
}

Вложенные выражения JSONPath

В AdGuard для Windows, Mac и Android с CoreLibs версии 1.11 или выше выражения JSONPath могут быть использованы как ключи в выражениях фильтра.

• ||example.org^$jsonprune=\$.elems[?(has "\$.a.b.c")] удаляет всех прямых потомков elems, которые обладают свойством, выбираемым JSONPath-выражением $.a.b.c.

До

{
    "elems": [
        {
            "a": {"b": {"c": 123}},
            "k": "v"
        },
        {
            "d": {"e": {"f": 123}},
            "k1": "v1"
        }
    ]
}

После

{
    "elems": [
        {
            "d": {"e": {"f": 123}},
            "k1": "v1"
        }
    ]
}

• ||example.org^$jsonprune=\$.elems[?(key-eq "\$.a.b.c" "abc")] удаляет всех прямых потомков elems, которые обладают свойством, выбираемым выражением JSONPath $.a.b.c со значением, равным "abc".

До

{
    "elems": [
        {
            "a": {"b": {"c": 123}},
        },
        {
            "a": {"b": {"c": "abc"}}
        }
    ]
}

После

{
    "elems": [
        {
            "a": {"b": {"c": 123}}
        }
    ]
}

Ограничения

• Правила $jsonprune совместимы только с этими модификаторами: $domain, $third-party, $strict-third-party, $strict-first-party, $app, $important, $match-case и $xmlhttprequest.
• Правила с $jsonprune не применяются к ответам размером больше 10 МБ.

Совместимость

Правила с модификатором $jsonprune поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 10 или выше.

$xmlprune

Правила $xmlprune модифицируют ответ на соответствующий запрос, удаляя XML-элементы, которые соответствуют модифицированному выражению XPath 1.0. Выражение должно возвращать набор узлов. Правила $xmlprune не изменяют ответы, которые не являются правильно сформированными XML-документами.

Синтаксис

• ||example.org^$xmlprune=expression удаляет из ответа элементы, соответствующие XPath-выражению expression.

Из-за особенностей работы парсинга правил символы $ и , внутри expression должны экранироваться символом \.

Исключения

Базовые URL-исключения не должны отключать правила с модификатором $xmlprune. Отключить их можно следующим образом:

• @@||example.org^$xmlprune отключает все правила $xmlprune для ответов от URL-адресов, соответствующих ||example.org^.
• @@||example.org^$xmlprune=text отключает все правила $xmlprune, у которых значение модификатора $xmlprune равно text, для ответов с URL-адресов, соответствующих ||example.org^ URL.

$xmlprune также можно отключить с помощью правил-исключений с модификаторами $document, $content и $urlblock.

комментарий

Если одному и тому же запросу соответствует несколько правил $xmlprune, они применяются в лексикографическом порядке.

Примеры

• ||example.org^$xmlprune=/bookstore/book[position() mod 2 = 1] удаляет книги с нечётными номерами из книжного магазина.

До

<?xml version="1.0" encoding="UTF-8"?>

<bookstore>

  <book category="cooking">
    <title lang="en">Everyday Italian</title>
    <author>Giada De Laurentiis</author>
    <year>2005</year>
    <price>30.00</price>
  </book>

  <book category="children">
    <title lang="en">Harry Potter</title>
    <author>J K. Rowling</author>
    <year>2005</year>
    <price>29.99</price>
  </book>

  <book category="web">
    <title lang="en">XQuery Kick Start</title>
    <author>James McGovern</author>
    <author>Per Bothner</author>
    <author>Kurt Cagle</author>
    <author>James Linn</author>
    <author>Vaidyanathan Nagarajan</author>
    <year>2003</year>
    <price>49.99</price>
  </book>

  <book category="web">
    <title lang="en">Learning XML</title>
    <author>Erik T. Ray</author>
    <year>2003</year>
    <price>39.95</price>
  </book>

</bookstore>

После

<?xml version="1.0" encoding="UTF-8"?>

<bookstore>



<book category="children">
  <title lang="en">Harry Potter</title>
  <author>J K. Rowling</author>
  <year>2005</year>
  <price>29.99</price>
</book>



<book category="web">
  <title lang="en">Learning XML</title>
  <author>Erik T. Ray</author>
  <year>2003</year>
  <price>39.95</price>
</book>

</bookstore>

• ||example.org^$xmlprune=/bookstore/book[year = 2003] удаляет книги за 2003 год из книжного магазина.

До

<?xml version="1.0" encoding="UTF-8"?>

<bookstore>

  <book category="cooking">
    <title lang="en">Everyday Italian</title>
    <author>Giada De Laurentiis</author>
    <year>2005</year>
    <price>30.00</price>
  </book>

  <book category="children">
    <title lang="en">Harry Potter</title>
    <author>J K. Rowling</author>
    <year>2005</year>
    <price>29.99</price>
  </book>

  <book category="web">
    <title lang="en">XQuery Kick Start</title>
    <author>James McGovern</author>
    <author>Per Bothner</author>
    <author>Kurt Cagle</author>
    <author>James Linn</author>
    <author>Vaidyanathan Nagarajan</author>
    <year>2003</year>
    <price>49.99</price>
  </book>

  <book category="web">
    <title lang="en">Learning XML</title>
    <author>Erik T. Ray</author>
    <year>2003</year>
    <price>39.95</price>
  </book>

</bookstore>

После

<?xml version="1.0" encoding="UTF-8"?>

<bookstore>

<book category="cooking">
  <title lang="en">Everyday Italian</title>
  <author>Giada De Laurentiis</author>
  <year>2005</year>
  <price>30.00</price>
</book>

<book category="children">
  <title lang="en">Harry Potter</title>
  <author>J K. Rowling</author>
  <year>2005</year>
  <price>29.99</price>
</book>





</bookstore>

• ||example.org^$xmlprune=//*/@* удаляет все атрибуты из всех элементов.

До

<?xml version="1.0" encoding="UTF-8"?>

<bookstore location="cy">

  <book category="cooking">
    <title lang="en">Everyday Italian</title>
    <author>Giada De Laurentiis</author>
    <year>2005</year>
    <price>30.00</price>
  </book>

</bookstore>

После

<?xml version="1.0" encoding="UTF-8"?>

<bookstore>

  <book>
    <title>Everyday Italian</title>
    <author>Giada De Laurentiis</author>
    <year>2005</year>
    <price>30.00</price>
  </book>

</bookstore>

Ограничения

• Правила $xmlprune совместимы только с этими модификаторами: $domain, $third-party, $strict-third-party, $strict-first-party, $app, $important, $match-case и $xmlhttprequest.
• Правила с $xmlprune не применяются к ответам размером больше 10 МБ.

Совместимость

Правила с модификатором $xmlprune поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 15 или выше.

$network

По сути, это правила типа Firewall, позволяющие полностью блокировать или разблокировать доступ к указанному удалённому адресу.

1. Правила $network соответствуют только IP-адресам! Вы не можете использовать их, чтобы блокировать или разблокировать доступ к домену.
2. Чтобы сопоставить адрес IPv6, вы должны использовать сжатый синтаксис, например, использовать [2001:4860:4860::8888]$network вместо [2001:4860:4860:0:0:0:0:8888]$network.
3. Правило белого списка $network заставляет AdGuard обходить данные до соответствующей конечной точки, поэтому никакой дальнейшей фильтрации не будет.
4. Если часть IP начинается и заканчивается символом /, она рассматривается как регулярное выражение.

Рекомендуем ознакомиться с этой статьёй для лучшего понимания регулярных выражений.

Ограничения

Модификатор $network можно использовать в правилах только вместе с модификаторами $app и $important, но не с какими-либо другими модификаторами.

Примеры

• 174.129.166.49:3478^$network блокирует доступ к 174.129.166.49:3478 (но не к 174.129.166.49:34788).
• [2001:4860:4860::8888]:443^$network блокирует доступ к [2001:4860:4860::8888]:443.
• 174.129.166.49$network блокирует доступ к 174.129.166.49:*.
• @@174.129.166.49$network заставляет AdGuard направлять трафик в конечную точку. Никакие другие правила применяться не будут.
• /.+:3[0-9]{4}/$network блокирует доступ к диапазанону портов 30000–39999.
• /8.8.8.(:?8|4)/$network блокирует доступ к 8.8.8.8 и к 8.8.8.4.

Совместимость

Только в AdGuard для Windows, Mac и Android есть технические возможности для поддержки правил с модификатором $network.

$permissions

Этот модификатор полностью меняет поведение правила. Когда он применяется, правило не блокирует запрос. Вместо этого будут изменены заголовки ответа.

информация

Чтобы использовать правила этого типа, необходимо базовое понимание слоя безопасности Feature Policy.

Для запросов, соответствующих правилу $permissions, AdGuard усиливает «политику функций» ответа, добавляя дополнительную политику, равную содержимому модификатора $permissions. Правила $permissions применяются независимо от правил любого другого типа. На него могут повлиять только исключения на уровне документа (см. раздел с примерами), но никак не другие базовые правила.

Синтаксис

Синтаксис значений $permissions идентичен синтаксису заголовка Permissions-Policy со следующими исключениями:

1. Запятая, разделяющая несколько функций, должна быть экранирована — см. примеры ниже.
2. Вместо запятой для разделения функций можно использовать символ вертикальной черты (|).

Список доступных директив

Значение $permissions может быть пустым в случае правил исключений — смотрите примеры ниже.

Примеры

• ||example.org^$permissions=autoplay=() запрещает автовоспроизведение медиафайлов, запрашиваемых через интерфейс HTMLMediaElement на сайте example.org.
• @@||example.org/page/*$permissions=autoplay=() отключает все правила с модификатором $permissions, в точности соответствующим autoplay=() на всех страницах, подходящих под паттерн правила. Например, правило выше. Важно отметить, что правило исключения действует только в случае точного совпадения значений. Например, если вы хотите отключить правило $permissions=a=()\,b=(), вам нужно правило исключения @@$permissions=a=()\,b=(), а не @@$permissions=b=()\,a=() или @@$permissions=b=(), потому что b=()\,a=() или b=() не совпадает с a=()\,b=().
• @@||example.org/page/*$permissions отключает все $permissions-правила на всех страницах, подходящих под паттерн правила.
• $domain=example.org|example.com,permissions=storage-access=()\, camera=() запрещает использование Storage Access API для запроса доступа к неразмеченным куки, а также использование устройств видеоввода на сайтах example.org и example.com.
• $domain=example.org|example.com,permissions=storage-access=()|camera=() делает то же самое — вместо экранированной запятой для разделения функций можно использовать |.
• @@||example.org^$document или @@||example.org^$urlblock отключает все $permission-правила на всех страницах, подходящих под паттерн правила.

комментарий

Правила $permissions действуют только для запросов основного фрейма и подфреймов. Это означает, что они применяются при загрузке страницы или при загрузке iframe.

комментарий

Если имеется несколько правил $permissions, соответствующих одному и тому же запросу, к ответу для каждого правила будут добавлены несколько заголовков Permissions-Policy со своими значениями $permissions. Итак, если у вас есть два правила: ||example.org^$permissions=autoplay=() и ||example.org^$permissions=geolocation=()\,camera=(), которые соответствуют одному и тому же запросу, ответ будет содержать два заголовка Permissions-Policy: autoplay=() и geolocation=()\,camera=().

Ограничения модификатора $permissions

Ограничения

Firefox игнорирует заголовок Permissions-Policy. Подробнее см. на сайте Bugzilla.

Ограничения

1. В модификаторе $permissions запрещён символ $.
2. $permissions совместим с ограниченным набором модификаторов: $domain, $important, $subdocument и модификаторами типа контента.
3. Правила с модификатором $permissions, не содержащие модификаторов типа контента, будут применяться только к тем запросам, которые имеют тип контента document.

Совместимость

• Правила с модификатором $permissions поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.11 или выше и в Браузерном расширении AdGuard с TSUrlFilter версии 3.0.0 или выше.
• Разделитель | вместо запятой поддерживается в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.14 или выше и в Браузерном расширении AdGuard с TSUrlFilter версии 3.0.0 или выше.

$redirect

AdGuard способен перенаправлять веб-запросы на локальный «ресурс».

Синтаксис

AdGuard использует тот же синтаксис правил фильтрации, что и uBlock Origin. Также он совместим с модификатором ABP $rewrite=abp-resource.

$redirect — это модификатор для базовых правил фильтрации, поэтому правила с этим модификатором поддерживают остальные базовые модификаторы, такие как $domain, $third-party, $script и т. д.

Значение модификатора $redirect должно быть именем ресурса, который будет использован для переадресации.

Отключение правил $redirect

• ||example.org/script.js$script,redirect=noopjs — это правило перенаправляет все запросы к example.org/script.js на ресурс с именем noopjs.
• ||example.org/test.mp4$media,redirect=noopmp4-1s — это правило перенаправляет все запросы к example.org/script.js на ресурс с именем noopmp4-1s.
• @@||example.org^$redirect отключит все правила $redirect для URL-адресов, соответствующих ||example.org^.
• @@||example.org^$redirect=nooptext отключит все правила с $redirect=nooptext для любого запроса, который соответствует ||example.org^.

Больше информации о редиректах и их использовании доступно на GitHub.

Приоритеты правил $redirect

У правил с $redirect более высокий приоритет, чем у обычных базовых правил блокировки. Это означает, что если существует базовое правило блокировки, то правило $redirect будет его отменять. У правил белого списка с пометкой @@ более высокий приоритет, чем у правил $redirect. Если базовое правило с модификатором $important и правило $redirect соответствуют одному и тому же URL-адресу, последнее переопределяется, если оно также не помечено как $important.

$important > @@ > $redirect > базовые правила.

Перейдите к приоритетам правил для более подробной информации.

Ограничения модификатора $redirect

Ограничения

В AdGuard для Chrome MV3 правила белого списка с $redirect не поддерживаются.

Совместимость

• Правила с модификатором $redirect не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari .
• $redirect в uBlock Origin поддерживает указание приоритета, например, $redirect=noopjs:42. AdGuard не поддерживает его и вместо этого просто отбрасывает приоритетный постфикс.

$redirect-rule

По сути это другое имя $redirect, поскольку он имеет те же значения «перенаправления» и почти аналогичную логику. Разница в том, что $redirect-rule применяется только в том случае, если целевой запрос заблокирован другим базовым правилом.

Перейдите к приоритетам правил для более подробной информации.

Отключение $redirect-rule работает точно так же, как для обычных правил $redirect. Даже более того, @@||example.org^$redirect будет отключать как правило $redirect, так и $redirect-rule.

Примеры

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

В этом случае только запросы к example.org/script.js будут перенаправлены на noopjs. Все остальные запросы к example.org останутся без изменений.

Совместимость

Правила с модификатором $redirect-rule не поддерживаются в AdGuard Content Blocker, AdGuard для iOS, AdGuard для Safari и AdGuard для Chrome MV3. Обсуждение о том, чтобы добавить поддержку правил $redirect-rule в расширения Chrome MV3, сейчас открыто.

$referrerpolicy

Эти правила позволяют переопределять политику реферера страницы. В ответах на соответствующие запросы все заголовки Referrer-Policy заменит один заголовок со значением, равным значению модификатора правила сопоставления. Если ответ содержит HTML-документ с тегом <meta name="referrer"..., то атрибут content этого тега также будет заменён на значение модификатора.

Правило исключения со значением модификатора отключает правило блокировки с тем же значением. Правило исключения без значения модификатора отключает все совпадающие правила referrer-policy.

Если запрос соответствует нескольким правилам $referrerpolicy, не отключённым исключениями, то применяется только одно из них (какое именно — не уточняется). Правила $referrerpolicy без указанных модификаторов типа контента применяются к типам контента $document и $subdocument.

Примеры

• ||example.com^$referrerpolicy=unsafe-url переопределяет политику referrer для example.com с unsafe-url.
• @@||example.com^$referrerpolicy=unsafe-url отключает предыдущее правило.
• @@||example.com/abcd.html^$referrerpolicy отключает все правила $referrerpolicy на example.com/abcd.html.

Совместимость

Правила с модификатором $referrerpolicy поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.12 или выше.

$removeheader

Правила с модификатором $removeheader предназначены для того, чтобы убирать заголовки HTTP-запросов и ответов. Изначальная мотивация для создания этого типа правил заключалась в том, чтобы иметь возможность избавиться от заголовка Refresh, который часто используется для перенаправления пользователей на нежелательную страницу. Однако применение данного модификатора не ограничивается этим случаем.

Как и в случае с $csp, $redirect, $removeparam и $cookie, этот модификатор существует независимо, правила с ним не зависят от обычных базовых правил, то есть регулярные выражения или блокирующие правила никак на них не повлияют. По умолчанию они работают только применительно к заголовкам ответов. Но вы также можете изменить его, чтобы удалить заголовки из HTTP-запросов.

Синтаксис

Базовый синтаксис

• ||example.org^$removeheader=header-name убирает заголовок ответа с названием header-name
• ||example.org^$removeheader=request:header-name убирает заголовок запроса с названием header-name

$removeheader нечувствителен к регистру, но мы настоятельно рекомендуем всегда использовать нижний регистр.

Отрицание $removeheader

Этот тип правил работает почти так же, как и с модификаторами $csp и $redirect.

Используйте @@, чтобы отменить $removeheader:

• @@||example.org^$removeheader отменяет все правила $removeheader для URL-адресов, соответствующих ||example.org^.
• @@||example.org^$removeheader=header отменяет все правила с $removeheader=header для любого запроса, соответствующего ||example.org^.

Правила с $removeheader также можно отключить, используя правила-исключения $document и $urlblock. Но базовые правила-исключения без модификаторов не смогут этого сделать. Например, @@||example.com^ не отключит $removeheader=p для запросов к example.com, а @@||example.com^$urlblock отключит.

комментарий

В случае, когда несколько правил с $removeheader соответствуют одному запросу, мы будем применять их все по очереди.

Примеры

• ||example.org^$removeheader=refresh убирает заголовок Refresh из всех HTTP-ответов, возвращённых example.org и его поддоменами.

• ||example.org^$removeheader=request:x-client-data убирает заголовок X-Client-Data из всех HTTP-запросов.

• Данный блок правил убирает заголовки Refresh и Location из всех HTTP-ответов, возвращённых example.org, кроме запросов к example.org/path/*, для которого заголовки не будут убраны:

  ||example.org^$removeheader=refresh
  ||example.org^$removeheader=location
  @@||example.org/path/$removeheader

Ограничения

Этот тип правил может использоваться только в доверенных фильтрах.

1. Чтобы избежать потенциальных проблем с безопасностью, $removeheader не может убрать следующие заголовки:

   • access-control-allow-origin
   • access-control-allow-credentials
   • access-control-allow-headers
   • access-control-allow-methods
   • access-control-expose-headers
   • access-control-max-age
   • access-control-request-headers
   • access-control-request-method
   • origin
   • timing-allow-origin
   • allow
   • cross-origin-embedder-policy
   • cross-origin-opener-policy
   • cross-origin-resource-policy
   • content-security-policy
   • content-security-policy-report-only
   • expect-ct
   • feature-policy
   • origin-isolation
   • strict-transport-security
   • upgrade-insecure-requests
   • x-content-type-options
   • x-download-options
   • x-frame-options
   • x-permitted-cross-domain-policies
   • x-powered-by
   • x-xss-protection
   • public-key-pins
   • public-key-pins-report-only
   • sec-websocket-key
   • sec-websocket-extensions
   • sec-websocket-accept
   • sec-websocket-protocol
   • sec-websocket-version
   • p3p
   • sec-fetch-mode
   • sec-fetch-dest
   • sec-fetch-site
   • sec-fetch-user
   • referrer-policy
   • content-type
   • content-length
   • accept
   • accept-encoding
   • host
   • connection
   • transfer-encoding
   • upgrade

2. $removeheader rules are only compatible with $domain, $third-party, $strict-third-party, $strict-first-party, $app, $important, $match-case, and content-type modifiers such as $script and $stylesheet. Правила с другими модификаторами считаются некорректными и не будут применены.

Совместимость

Правила с модификатором $removeheader поддерживаются в AdGuard для Windows, AdGuard для Mac, AdGuard для Android, а также в Браузерном расширении AdGuard для Chrome, Firefox и Edge.

$removeparam

комментарий

Модификатор $removeparam — это полный аналог модификатора $queryprune. Поскольку модификатор $queryprune считается устаревшим, рекомендуем везде использовать только модификатор $removeparam.

Правила с модификатором $removeparam предназначены для того, чтобы убирать параметры запроса из URL-адресов. Обратите внимание, что такие правила применяются только к запросам GET, HEAD, OPTIONS и иногда к POST.

Синтаксис

Базовый синтаксис

• $removeparam=param убирает параметр запроса с именем param из URL любого запроса. Например, запрос к http://example.com/page?param=1&&another=2 будет преобразован в http://example.com/page?another=2.

Регулярные выражения

Вы также можете использовать регулярные выражения, чтобы выбрать нужные параметры запроса или их значения:

• $removeparam=/regexp/[options] убирает из URL-адреса любого запроса все параметры, соответствующие заданному регулярному выражению regexp. В отличие от базового синтаксиса, это означает «‎убрать параметры запроса, нормализованные к строке name=value, которая соответствует регулярному выражению». [options] — это список опций регулярного выражения. На данный момент единственная поддерживаемая опция — это i, делающая соответствие нечувствительным к регистру.

Экранирование специальных символов

Специальные символы должны быть закодированы в правиле URL, чтобы правильно соответствовать тексту URL.

Например, чтобы удалить ?$param=true, вы должны использовать правило $removeparam=%24param.

комментарий

Пробелы и запятые также должны быть закодированы в URL, в противном случае правило не будет соответствовать URL. Однако ., -, _ и ~ следует использовать как есть, поскольку они не помечены как зарезервированные символы в кодировке URL.

Не забывайте экранировать специальные символы, такие как . в регулярных выражениях. Используйте для этого символ \. Например, экранированная точка должна выглядеть так: \..

комментарий

Правила с регулярными выражениями применяются как к названию, так и к значению параметра. Чтобы свести к минимуму ошибки, рекомендуется начинать каждое регулярное выражение с /^, если только вы не хотите специально работать со значениями параметров.

Удалите все параметры запроса

Укажите «‎голый» $removeparam, чтобы удалить все параметры запроса:

• ||example.org^$removeparam удаляет все параметры запроса из URL-адресов, соответствующих правилу ||example.org^.

Инверсия

Используйте ~, чтобы применить инверсию:

• $removeparam=~param удаляет все параметры запроса, кроме param.
• $removeparam=~/regexp/ удаляет все параметры запроса, которые не совпадают с заданным регулярным выражением regexp.

комментарий

Если ~ не встречается в начале правила, то в тексте оно рассматривается как символ.

Исключение правил с $removeparam

Этот тип правил работает практически так же, как и в случае с модификаторами $csp и $redirect.

Используйте @@, чтобы исключить правило с $removeparam:

• @@||example.org^$removeparam не даёт применять правила с $removeparam для URL, соответствующих example.org.
• @@||example.org^$removeparam=param не даёт применять правила с $removeparam=param для запросов к example.org.
• @@||example.org^$removeparam=/regexp/ не даёт применять правила с $removeparam=/regexp/ для запросов к example.org.

Несколько правил, соответствующих одному запросу

В случае, когда несколько правил с $removeparam соответствуют одному запросу, они все будут применены по очереди.

Примеры

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

С помощью этих правил некоторые UTM-параметры будут удалены из любого запроса, за исключением запросов к example.com, которые не будут удалены вообще. Например, http://google.com/page?utm_source=s&utm_referrer= fb.com&utm_content=img будет преобразован в http://google.com/page, но на http://example.com/page?utm_source=s&utm_referrer=fb.com&utm_content=img правило блокировки не повлияет.

• $removeparam=utm_source удаляет параметр utm_source из всех запросов.

• $removeparam=/utm_.*/ удаляет все параметры utm_* из URL любого запроса. Например, запрос http://example.com/page?utm_source=test будет трансформирован в http://example.com/page.

• $removeparam=/^utm_source=campaign$/ удаляет параметр utm_source со значением campaign. Не затрагивает другие параметры utm_source.

Исключение правила с $removeparam и замена его другим

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

Эти правила удаляют Click ID Google, Яндекса и Facebook. Есть одно исключение: Google Click ID (gclid) не будет удалён из запросов к example.com.

Исключение правила с $removeparam для всех параметров

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

Эти правила удаляют указанные UTM-параметры из всех запросов, кроме запросов к example.org.

Правила с $removeparam также можно отключить с помощью правил исключений с $document и $urlblock. Но базовые правила исключений без модификаторов не могут этого сделать. Например, @@||example.com^ не отключит $removeparam=p для запросов к example.com, а вот @@||example.com^$urlblock — отключит.

Ограничения модификатора $removeparam

Ограничения

AdGuard для Chrome MV3 имеет некоторые ограничения:

• Регулярные выражения, отрицание и правила белого списка не поддерживаются.

• Группа похожих правил $removeparam будет объединена в одно. Пример:

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

  преобразуется в

  [
  {
    "id": 1,
    "action": {
    "type": "redirect",
    "redirect": {
      "transform": {
      "queryTransform": {
        "removeParams": [
        "p1case1",
        "p2case1",
        "P3Case1"
        ]
      }
      }
    }
    },
    "condition": {
    "urlFilter": "||testcases.adguard.com",
    "resourceTypes": [
      "xmlhttprequest"
    ],
    "isUrlFilterCaseSensitive": false
    }
  },
  {
    "id": 4,
    "action": {
    "type": "redirect",
    "redirect": {
      "transform": {
      "queryTransform": {
        "removeParams": [
        "p1case2"
        ]
      }
      }
    }
    },
    "condition": {
    "resourceTypes": [
      "xmlhttprequest"
    ],
    "isUrlFilterCaseSensitive": false
    }
  }
  ]

Ограничения

1. Правила с модификатором $removeparam могут использоваться только в доверенных фильтрах.
2. Правила с $removeparam совместимы с базовыми модификаторами, модификаторами типа контента, а также с модификаторами $important и $app. Правила с любыми другими модификаторами считаются некорректными и не будут применены.
3. Правила $removeparam, не содержащие модификаторов типа контента, будут применяться только к тем запросам, где тип контента document.

Совместимость

• Правила с модификатором $removeparam поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.7 или выше, а также в Браузерном расширении AdGuard версии 3.6 или выше.
• Синтаксис $removeparam для регулярных выражений поддерживается в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.8 или выше, а также в Браузерном расширении AdGuard версии 4.0 или выше.
• Запросы POST поддерживаются только в AdGuard для Windows, Mac и Android с CoreLibs версии 1.10 или выше, и в Браузерном расширении AdGuard с TSWebExtension версии 0.4.6 или выше.

$replace

Этот модификатор полностью меняет поведение правила. Когда он применяется, правило не блокирует запрос. Вместо этого ответ модифицируется.

Вам потребуется знание регулярных выражений, чтобы использовать модификатор $replace.

Функции

• Правила с $replace применяются к любому текстовому ответу, но не применяются к binary (media, image, object и т. д.).
• Правила с $replace не применяются к ответам размером больше 10 МБ.
• Правила с $replace обладают более высоким приоритетом, чем другие базовые правила (включая правила исключений). Если запрос соответствует двум различным правилам, одно из которых имеет модификатор $replace, применится именно это правило.
• Правила исключений уровня document с модификаторами $content или $document отменяют срабатывание правил $replace, даже если запрос им соответствует.
• Прочие правила исключений уровня document (с модификаторами $generichide, $elemhide или $jsinject) применяются вместе с правилами $replace. Это означает, что вы можете изменять содержимое страницы при помощи правила $replace и отключить косметические правила там же.

Значение $replace может быть пустым в случае правил исключений. Более подробную информацию вы найдёте в разделе с примерами.

Несколько правил, соответствующих одному запросу

В случае, когда несколько правил $replace соответствуют одному запросу, мы применим каждое из них. Правила будут применяться в алфавитном порядке.

Синтаксис

В целом синтаксис $replace аналогичен замене регулярными выражениями в Perl.

replace = "/" regexp "/" replacement "/" modifiers

• regexp — регулярное выражение.
• replacement — строка, которая будет использована для замены строки в соответствии с regexp.
• modifiers — флаги регулярных выражений. Например, i — поиск без учёта регистра, s — режим одной строки.

В значении $replace необходимо экранировать два символа: запятую , и знак доллара $. Используйте для этого обратный слеш \. Например, экранированная запятая будет выглядеть так: \,.

Примеры

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

У этого правила три части:

• regexp (регулярное выражение) — (<VAST(.|\s)*?>)(.|\s)*<\/VAST>
• replacement (замена) — \$1<\/VAST> где $ экранируется
• modifiers (флаги регулярных выражений) — i для поиска без учёта регистра

Здесь вы можете увидеть, как работает это правило: http://regexr.com/3cesk

Несколько правил с $replace

1. ||example.org^$replace=/X/Y/
2. ||example.org^$replace=/Z/Y/
3. @@||example.org/page/*$replace=/Z/Y/

• Правила 1 и 2 будут применены ко всем запросам, отправленным к example.org.
• Правило 2 отключено для запросов, соответствующих ||example.org/page/, но правило 1 при этом всё равно работает!

Отключение правил с $replace

• @@||example.org^$replace отключит все правила $replace, соответствующие ||example.org^.
• @@||example.org^$document или @@||example.org^$content отключит все правила $replace, исходящие со страниц домена example.org, включая саму эту страницу.

Ограничения

Правила с модификатором $replace могут использоваться только в доверенных фильтрах.

Совместимость

Правила с модификатором $replace поддерживаются в AdGuard для Windows, AdGuard для Mac, AdGuard для Android, а также в Браузерном расширении AdGuard для Firefox. Другие расширения не могут модифицировать содержимое страниц на сетевом уровне, поэтому там эти правила не работают.

$urltransform

Правила $urltransform позволяют изменять URL-адрес запроса, заменяя текст, соответствующий регулярным выражениям.

Функции

• Правила $urltransform обычно применяются только к частям URL-адреса, относящимся к пути и запросу, одно исключение см. ниже.
• $urltransform не будет применяться, если исходный URL-адрес заблокирован другими правилами.
• $urltransform будет применяться перед правилами $removeparam.

Значение $urltransform может быть пустым для правил исключений.

Несколько правил, соответствующих одному запросу

Если несколько правил $urltransform соответствуют одному запросу, мы применим каждое из них. Правила будут применяться в алфавитном порядке.

Синтаксис

Синтаксис $urltransform аналогичен замене регулярными выражениями в Perl.

urltransform = "/" regexp "/" replacement "/" modifiers

• regexp — регулярное выражение.
• replacement — строка, которая будет использована для замены строки в соответствии с regexp.
• modifiers — флаги регулярных выражений. Например, i — поиск без учёта регистра, s — режим одной строки.

В значении $urltransform необходимо экранировать два символа: запятую , и знак доллара $. Для этого используйте обратный слеш \. Например, экранированная запятая будет выглядеть так: \,.

Изменение происхождения

Совместимость

Этот раздел относится только к AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs 1.17 или более поздней версии.

Как указано выше, обычно правилам $urltransform разрешено изменять только части пути и запроса URL-адреса. Однако, если regexp правила начинается со строки ^http, то полный URL ищется и может быть изменён правилом. Такое правило не будет применяться, если преобразование URL не может быть выполнено с помощью HTTP-перенаправления (например, если метод запроса — POST).

Примеры

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

У этого правила три части:

• regexp — (pref\/).*\/(suf)
• replacement — \$1\$2, где $ экранируется
• modifiers (флаги регулярных выражений) — i для поиска без учёта регистра

Несколько правил с $urltransform

1. ||example.org^$urltransform=/X/Y/
2. ||example.org^$urltransform=/Z/Y/
3. @@||example.org/page/*$urltransform=/Z/Y/

• Правила 1 и 2 будут применены ко всем запросам, отправленным к example.org.
• Правило 2 отключено для запросов, соответствующих ||example.org/page/, но правило 1 при этом всё равно работает!

Повторное сопоставление правил после преобразования URL

После применения всех соответствующих правил $urltransform преобразованный запрос будет сопоставлен со всеми остальными правилами:

Например, при следующих правилах:

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

запрос к https://example.com/firstpath будет заблокирован.

Отключение правил с $urltransform

• @@||example.org^$urltransform отключит все правила с $urltransform, где есть ||example.org^.
• @@||example.org^$urltransform=/Z/Y/ отключит правило с $urltransform=/Z/Y/ для любого запроса, соответствующего ||example.org^.

Правила с $urltransform также можно отключить, используя правила исключений с $document и $urlblock. Но базовые правила исключений без модификаторов не могут этого сделать. Например, @@||example.com^ не отключит $urltransform=/X/Y/ для запросов к example.com, а @@||example.com^$urlblock отключит.

Ограничения

Правила с модификатором $urltransform могут использоваться только в доверенных фильтрах.

Совместимость

Правила с модификатором $urltransform поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.15 или выше.

noop

Модификатор noop не делает ничего и используется только для того, чтобы улучшить читаемость правил. Он состоит из последовательности символов нижнего подчёркивания (_) произвольной длины и может фигурировать в правиле так часто, как это необходимо.

Примеры

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

Совместимость

Правила с модификатором noop не поддерживаются в AdGuard Content Blocker.

$empty (устаревший)

Скоро устареет

Этот модификатор считается устаревшим. Вместо него теперь используется модификатор $redirect. Правила с $empty всё ещё поддерживаются и преобразуются в $redirect=nooptext, но в будущем перестанут поддерживаться.

Обычно заблокированный запрос выглядит для браузера как ошибка сервера. В случае применения модификатора $empty AdGuard эмулирует пустой ответ сервера со статусом 200 OK.

Примеры

• ||example.org^$empty возвращает пустой ответ для всех запросов к домену example.org и всех его поддоменов.

Совместимость

Правила с модификатором $empty не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.

$mp4 (устаревший)

Скоро устареет

Этот модификатор считается устаревшим. Вместо него теперь используется модификатор $redirect. Правила с $mp4 всё ещё поддерживаются и преобразуются в $redirect=noopmp4-1s,media, но в будущем перестанут поддерживаться.

В качестве ответа на заблокированный запрос AdGuard возвращает короткую видео-заглушку.

Примеры

• ||example.com/videos/$mp4 блокирует загрузку видео с адресов ||example.com/videos/* и заменяет ответ на видео-заглушку.

Совместимость

Правила с модификатором $mp4 не поддерживаются в AdGuard Content Blocker, AdGuard для iOS и AdGuard для Safari.

Приоритеты правил

Каждое правило имеет свой приоритет, что необходимо, когда запросу соответствует несколько правил и фильтрующий механизм должен выбрать одно из них. Приоритет измеряется целым положительным числом.

Конфликты

Когда два правила с одинаковым приоритетом соответствуют одному и тому же запросу, реализация механизма фильтрации определяет, какое из них будет выбрано.

информация

Концепция приоритетов правил становится всё более важной в свете Manifest V3, поскольку существующие правила должны быть преобразованы в правила declarativeNetRequest.

Расчёт приоритетов

Для расчёта приоритета мы разделили модификаторы на разные группы. Эти группы ранжируются по степени приоритетности, от низшей к высшей. Модификатор, существенно сужающий область действия правила, увеличивает вес его общего приоритета. И наоборот, если правило применяется к более широкому кругу запросов, то его приоритет снижается.

Следует отметить, что существуют случаи, когда модификатор с одним параметром имеет более высокий приоритет, чем тот, у которого много параметров. Например, в случае $domain=example.com|example.orgправило, включающее два домена, имеет несколько более широкую область действия, чем правило с одним указанным доменом, поэтому его приоритет ниже.

Базовый приоритет любого правила равен 1. Если вычисленный приоритет — число с плавающей точкой, то оно будет округлено в большую сторону до наименьшего целого числа, большего или равного вычисленному приоритету.

Совместимость

• Понятие приоритета было введено в tsurlfilter 2.1.0 и CoreLibs 1.13. До этого в AdGuard не было специального алгоритма вычисления приоритетов, и обработка конфликтов могла отличаться в зависимости от продукта и версии AdGuard.
• AdGuard для iOS, Safari и AdGuard Content Blocker зависят от реализации браузера и не могут следовать указанным здесь правилам.

комментарий

Псевдонимы-модификаторы (1p, 3p и т. д.) не входят в эти категории, однако они используются в движке для вычисления приоритета правила.

Базовые модификаторы, наличие каждого добавляет 1 к приоритету

• $app с исключаемыми приложениями с использованием ~,
• $denyallow,
• $domain с исключаемыми доменами с использованием ~,
• $match-case,
• $method с исключаемыми методами с использованием ~,
• $strict-first-party,
• $strict-third-party,
• $third-party,
• $to,
• ограниченные модификаторы сontent-type с ~.

При работе с исключаемым доменом, приложением, методом или типом содержимого мы добавляем 1 балл за существование самого модификатора, независимо от количества исключаемых доменов или типов содержимого. Это связано с тем, что область действия правила и так бесконечно широка. Проще говоря, запрещая несколько доменов, модификаторов content-type, методов или приложений, мы лишь немного сужаем область действия правила.

Определённые модификаторы content-type, методы, заголовки, $all, $popup, специальные исключения

Все правильные типы контента:

• $document,
• $font,
• $image,
• $media,
• $object,
• $other,
• $ping,
• $script,
• $stylesheet,
• $subdocument,
• $websocket,
• $xmlhttprequest;

Сюда также входят правила, которые неявно добавляют все типы контента:

• $all;

Или правила, которые неявно добавляют модификатор $document:

• $popup;

Или некоторые специальные исключения, которые неявно добавляют $document,subdocument:

• $content,
• $elemhide,
• $extension,
• $genericblock,
• $generichide,
• $jsinject,
• $specifichide,
• $urlblock;

Или методы, разрешённые модификатором $method.

Или правила с $header.

Наличие любых модификаторов content-type добавляет (50 + 50 / N), где N — количество модификаторов, например: ||example.com^$image,script добавит 50 + 50 / 2 = 50 + 25 = 75 к общему весу правила.

The $all also belongs to this category, because it implicitly adds all content-type modifiers, e.g., $document,subdocument,image,script,media,<etc> + $popup.

К этой категории относится и $popup, так как в нём неявно добавляется модификатор $document. Аналогично, конкретные исключения добавляют $document,subdocument.

Если в правиле есть модификатор $method с разрешёнными методами, то он добавляет (50 + 50 / N), где N — количество разрешённых методов, например: ||example.com^$method=GET|POST|PUT добавит 50 + 50 / 3 = 50 + 16,6 = 67 к общему весу правила.

Если в правиле есть модификатор $header, то он добавляет 50.

$domain или $app с разрешёнными доменами или приложениями

Домены или приложения, указанные с помощью $domain и $app соответственно, добавят 100 + 100 / N, где N — количество значений модификатора, например: ||example.com^$domain=example.com|example.org|example.net добавит 100 + 100 / 3 = 135 или ||example.com^$app=org.example.app1|org.example.app2 добавит 100 + 100 / 2 = 100 + 51 = 151 или ||example.com^$domain=example.com,app=org.example.app1|org.example.app2 добавит 100 + 100/1 (часть $domain) и 100 + 100/2 (часть $app) — в сумме 350.

Значения модификаторов regexps или tld будут интерпретироваться как обычные записи вида example.com и считаться по одному, например: ||example.com^$domain=example.* будет добавлено 100 + 100 / 1 = 200 или ||example.com^$domain=example.*|adguard.* будет добавлено 100 + 100 / 2 = 150.

Правила $redirect

• $redirect,
• $redirect-rule.

Каждое из них добавляет 10^3 к приоритету правила.

Особые исключения

• $content,
• $elemhide,
• $extension,
• $genericblock,
• $generichide,
• $jsinject,
• $specifichide,
• $urlblock;

Каждое из них добавляет 10^4 к приоритету.

Исключение с модификатором $document в том числе: это псевдоним для $elemhide, content,jsinject,urlblock,extension. Оно добавит 10^4 для каждого модификатора из верхнего списка, 10^4 * 5 в сумме.

Кроме того, каждое из этих исключений неявно добавляет два разрешённых модификатора типа контента: $document,subdocument.

Правила белого списка

Модификатор @@ добавляет 10^5 к приоритету правила.

Правила $important

Модификатор $important добавляет 10^6 к приоритету правила.

Правила, для которых нет веса приоритета

Other modifiers, which are supposed to perform additional post- or pre-processing of requests, do not add anything to the rule priority.

комментарий

The $replace modifier takes precedence over all blocking rules of categories 1–3, as well as exception rules from categories 3–5, except $content, because an exception with the $content modifier overrides all $replace rules.

Примеры

1. ||example.com^

   Вес правила без модификаторов: 1.

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

   Вес правила: базовый вес + вес модификатора из категории 1: 1 + 1 = 2.

3. ||example.org^$removeparam=p

   Вес правила: базовый вес + 0, так как $removeparam не участвует в расчёте приоритета: 1 + 0 = 1.

4. ||example.org^$document,redirect=nooptext

   Вес правила: базовый вес + допустимый тип содержимого, категория 3 + $redirect из категория 6: 1 + (100 + 100 / 1) + 1000 = 1201.

5. @@||example.org^$removeparam=p,document

   Вес правила: базовый вес + правило белого списка, категория 5 + 0, потому что $removeparam не участвует в расчёте приоритета + разрешённый тип контента, категория 2: 1 + 10000 + 0 + (50 + 50 / 1) = 10101.

6. @@||example.com/ad/*$domain=example.org|example.net,important

   Вес правила: базовый вес + правило белого списка, категория 5 + важное правило, категория 7 + разрешённые домены, категория 3: 1 + 10000 + 1000000 + (100 + 100 / 2) = 1010152.

7. @@||example.org^$document без дополнительных модификаторов — это псевдоним для @@|||example.com^$elemhide,content,jsinject,urlblock,extension

   Вес правила: базовый вес + специфические исключения, категория 4 + два разрешённых типа контента (document и subdocument), категория 2: 1 + 10000 * 4 + (50 + 50 / 2) = 40076.

8. *$script,domain=a.com,denyallow=x.com|y.com

   Вес правила: базовый вес + разрешённый тип контента, категория 2 + разрешённый домен, категория 3 + отказ, категория 1: 1 + (50 + 50/1) + (100 + 100 / 1) + 1 = 303.

9. ||example.com^$all — псевдоним для ||example.com^$document,subdocument,image,script,media и т. д. + $popup

   Вес правила: базовый вес + всплывающее окно (категория 1) + разрешённые типы контента (категория 2): 1 + 1 + (50 + 50/12) = 55.

Другие правила

Базовых правил может быть недостаточно для блокировки рекламы. Иногда для этого требуется скрыть какой-нибудь элемент или изменить часть HTML-кода страницы, при этом ничего не сломав. Для этого предназначены правила, описанные в данном разделе.

Категории \ Продукты	Приложения CoreLibs	AdGuard для Chromium	AdGuard для Chrome MV3	AdGuard для Firefox	AdGuard для iOS	AdGuard для Safari	AdGuard Content Blocker
Скрытие элементов	✅	✅	✅	✅	✅	✅	✅
CSS-правила	✅	✅	✅	✅	✅	✅	❌
Расширенный CSS	✅	✅	✅	✅	✅	✅	❌
Фильтрация HTML	✅	❌	❌	✅	❌	❌	❌
JavaScript	✅	✅	✅	✅	✅	✅	❌
Скриптлеты	✅	✅	✅	✅	✅	✅	❌

комментарий

• ✅ — полностью поддерживается
• ❌ — не поддерживается

Косметические правила

информация

Для работы с косметическими правилами необходимы знания HTML и CSS. Итак, если вы хотите научиться создавать такие правила, рекомендуем ознакомиться с этой документацией.

Правила скрытия элементов

Правила скрытия элементов предназначены, как это следует из их названия, для скрытия элементов веб-страниц. По сути это аналогично применению стиля { display: none; } к выбранному элементу.

Правила скрытия элементов работают по-разному, и их приоритет меняется в зависимости от платформы.

Синтаксис

   rule = [domains] "##" selector
domains = [domain0, domain1[, ...[, domainN]]]

• selector — CSS селектор, определяет элементы, которые нужно скрыть.
• domains — доменное ограничение для правила.

Если вы хотите ограничить область действия одним или более доменами, просто перечислите их через запятую. Например: example.org,example.com##selector.

Это правило будет работать также на всех поддоменах example.org и example.com.

Если вы хотите, чтобы правило не применялось к определённым доменам, начните доменное имя со знака ~. Например: ~example.org##selector.

Вы можете использовать оба подхода в одном правиле. Например, правило example.org,~subdomain.example.org##domain будет работать для домена example.org и всех его поддоменов, кроме subdomain.example.org.

комментарий

Правила скрытия не зависят друг от друга. Если в фильтре есть правило example.org##selector и вы добавляете правило ~example.org##selector, то оба этих правила будут применены независимо друг от друга.

Примеры

• example.com##div.textad скроет элемент 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

В некоторых случаях может потребоваться отключение всех запрещающих правил. Например, на время тестирования. Для этого воспользуйтесь правилом исключения без указания домена. Это полностью отключит соответствующее правило CSS elemhide для ВСЕХ доменов:

#@#.textad

Правило такого вида даст аналогичный результат:

*#@#.textad

Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия невозможно. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.

CSS-правила

Иногда недостаточно просто скрыть какой-либо элемент, чтобы заблокировать рекламу. Например, блокировка рекламного элемента может просто сломать вёрстку сайта. Для таких случаев AdGuard позволяет использовать гораздо более гибкие правила, чем обычные правила скрытия. С помощью таких правил вы можете добавить на страницу практически любой CSS-стиль.

Синтаксис

   rule = [domains] "#$#" selector "{" style "}"
domains = [domain0, domain1[, ...[, domainN]]]

• selector — CSS-селектор, определяющий элементы, к которым мы хотим применить стиль.
• domains — ограничение на домены, на страницах которых будет применено правило. Строится по тем же правилам, что и в случае правил скрытия элементов.
• style — CSS-стиль, который мы хотим применить к выбранным элементам.

Примеры

example.com#$#body { background-color: #333!important; }

Это правило применит стиль background-color: #333!important; к элементу body для домена example.com и всех его поддоменов.

Исключения

По аналогии с правилами скрытия существует специальный тип правил, отключающий действие выбранного правила CSS-стилей для определённых доменов. Синтаксис правил-исключений практически такой же, только маркер #$# заменяется на #@$#.

Например, в фильтре есть правило:

#$#.textad { visibility: hidden; }

Если вы хотите отключить его для домена example.com, вы можете создать правило исключения:

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

Применять такие исключения рекомендуется только в случае, когда невозможно изменить само CSS-правило. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.

Ограничения

Запрещено использование стилей, которые могут приводить к загрузке каких-либо ресурсов. Это означает, что нельзя использовать атрибуты типа <url>.

Совместимость

CSS-правила не поддерживаются в AdGuard Content Blocker.

CSS-правила работают по-разному, и их приоритет меняется в зависимости от платформы.

Расширенные CSS-селекторы

• Ограничения
• Псевдокласс :has()
• Псевдокласс :contains()
• Псевдокласс :matches-css()
• Псевдокласс :matches-attr()
• Псевдокласс :matches-property()
• Псевдокласс :xpath()
• Псевдокласс :nth-ancestor()
• Псевдокласс :upward()
• Псевдокласс :remove() и псевдосвойство remove
• Псевдокласс :is()
• Псевдокласс :not()
• Псевдокласс :if-not() (удалён)

Возможностей CSS 3.0 не всегда хватает для блокировки рекламы. Чтобы решить эту проблему, AdGuard расширяет возможности CSS, добавляя поддержку новых псевдоэлементов. Мы разработали отдельную библиотеку с открытым исходным кодом для выбора нестандартных элементов и применения CSS-стилей с расширенными свойствами.

Идея расширенных возможностей заключается в возможности сопоставлять элементы DOM с селекторами на основе их собственного представления (стиль, текстовое содержимое и т. д.) или отношений с другими элементами. Также есть возможность применить стили с нестандартными свойствами CSS.

Область применения

Расширенные селекторы можно применять в любом косметическом правиле, будь то правила скрытия элементов или CSS-правила.

Совместимость

Правила с расширенными CSS-селекторами не поддерживаются в Блокировщике контента AdGuard.

Синтаксис

Независимо от того, какие CSS-псевдоклассы вы используете в правиле, вы можете использовать специальные маркеры для принудительного применения этих правил с помощью ExtendedCss. Рекомендуется использовать эти маркеры для всех косметических расширенных CSS-правил, чтобы их было легче отличить.

Синтаксис расширенных CSS-правил:

• #?# — для скрытия элемента, #@?# — для исключений
• #$?# — для CSS правил, #@$?# — для исключений

Мы настоятельно рекомендуем использовать эти маркеры каждый раз, когда вы используете расширенный CSS-селектор.

Примеры

• example.org#?#div:has(> a[target="_blank"][rel="nofollow"]) — это правило блокирует все элементы div, которые содержат дочерний элемент со ссылкой с атрибутами [target="_blank"][rel="nofollow"]. При этом правило будет работать только для домена example.org и всех его поддоменов.
• example.com#$?#h3:contains(cookies) { display: none!important; } — это правило устанавливает стиль display: none!important для всех элементов h3, которые содержат слово cookies. При этом правило будет работать только для домена example.com и всех его поддоменов.
• example.net#?#.banner:matches-css(width: 360px) — это правило блокирует все элементы .banner, которые содержат стиль width: 360px. При этом правило будет работать только для домена example.net и всех его поддоменов.
• example.net#@?#.banner:matches-css(width: 360px) — это правило отключает действие предыдущего правила.

Вы можете применять стандартные CSS-селекторы с помощью библиотеки ExtendedCss, используя маркер правила #?#. Например, #?#div.banner.

Подробнее об отладке расширенных селекторов.

комментарий

Некоторые псевдоклассы не требуют селектора перед ними. Несмотря на это, добавление Универсального селектора * облегчает чтение расширенного селектора, хотя и не влияет на поведение при подборе. Поэтому селектор #block :has(> .inner) работает точно так же, как #block *:has(> .inner), но второй более понятен.

Названия псевдоклассов не чувствительны к регистру, например, :HAS() работает как :has(). Несмотря на это, в основном используются названия в нижнем регистре.

Ограничения ExtendedCss

1. CSS комментарии и правила не поддерживаются.

2. Специфичные псевдоклассы могут иметь свои ограничения: :has(), :xpath(), :nth-ancestor(), :upward(), :is(), :not(), и :remove().

Псевдокласс :has()

Проект спецификации CSS 4.0 описывает псевдокласс :has(). К сожалению, популярные браузеры пока не поддерживают этот псевдокласс.

комментарий

Правила с псевдоклассом :has() должны использовать нативную реализацию :has(), если они содержат маркер ## и если это возможно, то есть без других расширенных селекторов внутри. Чтобы принудительно применить правила ExtendedCss с :has(), используйте маркер #?#/#$?# явно.

Совместимость с другими псевдоклассами

Синонимы :-abp-has() поддерживаются ExtendedCss для лучшей совместимости.

Уведомление об удалении

:if() больше не поддерживается как синоним для :has().

Синтаксис

[target]:has(selector)

• target — необязательный, стандартный или расширенный CSS-селектор, может быть пропущен для проверки любых элементов
• subject — обязателен. Стандартный или расширенный CSS-селектор

Псевдокласс :has() выбирает target-элементы, которые подходят под selector. Также селектор может начинаться с комбинатора.

Список селекторов можно задать и в selector. В этом случае все селекторы в списке будут сопоставляться. В будущем это будет исправлено для <forgiving-relative-selector-list> в качестве аргумента.

Ограничения :has()

Использование псевдокласса :has() ограничено для некоторых случаев (2, 3):

• запретить :has() внутри псевдоселекторов, принимающих только составные селекторы;
• запретить :has() после обычных псевдоэлементов.

Родной псевдокласс :has() не позволяет использовать :has(), :is() и :where() внутри :has()-аргумента, чтобы избежать увеличения сложности недействительности аргумента :has() (случай 1). Но ранее ExtendedCss не имел такого ограничения, а списки фильтров уже содержат такие правила, поэтому мы не стали добавлять это ограничение в ExtendedCss и разрешили использовать :has() внутри :has(), как это было возможно ранее. Чтобы использовать его, просто принудительно используйте ExtendedCss, установив маркер #?#/#$?#.

Нативная реализация не позволяет использовать :scope внутри аргумента :has() ([1], [2]). Тем не менее, в списках фильтров есть правила div:has(:scope a), которые мы продолжаем поддерживать, просто преобразуя их в div:has(> a), как это делалось ранее.

Примеры

div:has(.banner) выбирает все div-элементы, которые включают элемент с классом banner:

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

div:has(> .banner) выбирает все div-элементы, которые включают элемент класса banner в качестве прямого дочернего элемента div:

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

div:has(+ .banner) выбирает все div-элементы, предшествующие элементу класса banner, который непосредственно следует за div, и оба являются детьми одного родителя:

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

div:has(~ .banner) выбирает все div-элементы, предшествующие элементу класса banner, который следует за div, но не обязательно сразу, и оба являются детьми одного родителя:

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

div:has(span, .banner) выбирает все элементы div, которые включают в себя как элемент span, так и элемент класса banner:

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

Старый синтаксис

Синтаксис обратной совместимости для :has() поддерживается, но не рекомендуется.

Псевдокласс :contains()

Принцип действия псевдокласса :contains() очень прост: он позволяет выбрать элементы, которые содержат заданный текст или содержимое которых соответствует указанному регулярному выражению. Поддерживаются флаги регулярных выражений.

комментарий

Псевдокласс :contains() использует для сопоставления свойство элемента textContent, а не innerHTML.

Совместимость с другими псевдоклассами

Синонимы :-abp-contains() и :has-text() поддерживаются для лучшей совместимости.

Синтаксис

[target]:contains(match)

• target — необязательный, стандартный или расширенный CSS-селектор, может быть пропущен для проверки любых элементов
• match — требуется, строка или регулярное выражение для соответствия элементу textContent. Также поддерживаются флаги регулярных выражений.

Примеры

Для таких DOM:

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

элемент div#match может быть выбран любым из этих расширенных селекторов:

! plain text
div:contains(banner)

! регулярное выражение
div:contains(/as .*banner/)

! регулярное выражение с флагами
div:contains(/it .*banner/gi)

комментарий

Выбран только div с id=match, так как следующий элемент не содержит текст, а banner — это часть кода, а не текст.

Старый синтаксис

Синтаксис обратной совместимости для :contains() поддерживается, но не рекомендуется.

Псевдокласс :matches-css()

Псевдокласс :matches-css() позволяет сопоставить элемент по свойствам его текущего стиля. Работа псевдокласса основана на использовании метода Window.getComputedStyle().

Синтаксис

[target]:matches-css([pseudo-element, ] property: pattern)

• target — необязательный, стандартный или расширенный CSS-селектор, может быть пропущен для проверки любых элементов
• pseudo-element — необязательный, допустимый стандартный псевдоэлемент, например, before, after, first-line и т. д.
• property — требуется, название CSS-свойства, которое будет проверено у элемента
• pattern — требуется, шаблон значений, который использует то же простое сопоставление с подстановочными знаками, что и в основных правилах фильтрации URL-адресов, или регулярное выражение. Для этого типа соответствия AdGuard не обращает внимание на регистр. В случае с регулярными выражениями шаблон будет выглядеть так: /regexp/.

Экранирование и снятие специальных символов

Для нерегулярных выражений паттерны (,),[,] должны быть без экранирования, например, :matches-css(background-image:url(data:*)).

Для регулярных выражений паттерны \ должны быть экранированы, например, :matches-css(background-image: /^url\\("data:image\\/gif;base64.+/).

Примеры

Для таких DOM:

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

div-элементы с псевдоэлементом ::before и с указанным свойством content могут быть выбраны любым из этих расширенных селекторов:

! паттерн строки
div:matches-css(before, content: block me)

! паттерн строки с подстановочным знаком
div:matches-css(before, content: block*)

! паттерн регулярного выражения
div:matches-css(before, content: /block me/)

Ограничения

Паттерны регулярных выражений не поддерживают флаги.

Совместимость

Устаревшие псевдоклассы :matches-css-before() и :matches-css-after() больше не рекомендуются, но по-прежнему поддерживаются для лучшей совместимости.

Старый синтаксис

Синтаксис обратной совместимости для :matches-css() поддерживается, но не рекомендуется.

Псевдокласс :matches-attr()

Псевдокласс :matches-attr() позволяет выбрать элемент по его атрибутам, особенно если они рандомизированы.

Синтаксис

[target]:matches-attr("name"[="value"])

• target — необязательный, стандартный или расширенный CSS-селектор, может быть пропущен для проверки любых элементов
• name — требуется, простая строка, или строка с подстановочным знаком, или регулярное выражение для сопоставления имени атрибута
• value — необязательный, простая строка, или строка с подстановочным знаком, или регулярное выражение для сопоставления значения атрибута

Экранирование специальных символов

Для паттернов регулярных выражений " и \ должны быть экранированы, например, div:matches-attr(class=/[\\w]{5}/).

Примеры

div:matches-attr("ad-link") выбирает элемент div#target1:

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

div:matches-attr("data-*"="adBanner") выбирает элемент div#target2:

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

div:matches-attr(*unit*=/^click$/) выбирает элемент div#target3:

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

*:matches-attr("/.{5,}delay$/"="/^[0-9]*$/") выбирает элемент #target4:

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

Ограничения

Паттерны регулярных выражений не поддерживают флаги.

Псевдокласс :matches-property()

Псевдокласс :matches-property() позволяет выбирать элемент, сопоставляя его свойства.

Синтаксис

[target]:matches-property("name"[="value"])

• target — необязательный, стандартный или расширенный CSS-селектор, может быть пропущен для проверки любых элементов
• name — требуется, простая строка, или строка с подстановочным знаком, или регулярное выражение для сопоставления имени свойства элемента
• value — необязательный, простая строка, или строка с подстановочным знаком, или регулярное выражение для сопоставления значения свойства элемента

Экранирование специальных символов

Для паттернов регулярных выражений " и \ должны быть экранированы, например, div:matches-property(prop=/[\\w]{4}/).

комментарий

Паттерны регулярных выражений поддерживаются в name для любого свойства в цепочке, например, prop./^unit[\\d]{4}$/.type.

Примеры

Элемент с такими свойствами:

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

может быть выбран любым из этих расширенных селекторов:

div:matches-property(check.track)

div:matches-property("check./^unit_.{4,8}$/")

div:matches-property("check.unit_*"=true)

div:matches-property(memoizedProps.key="null")

div:matches-property(memoizedProps._owner.src=/ad/)

Для разработчиков фильтров

Чтобы проверить свойства конкретного элемента, сделайте следующее:

1. Проверьте элемент страницы или выберите его в Инструментах разработчика браузера во вкладке Элементы
2. Запустите console.dir($0) во вкладке Консоль

Ограничения

Паттерны регулярных выражений не поддерживают флаги.

Псевдокласс :xpath()

Псевдокласс :xpath() позволяет выбирать элементы согласно выражению XPath.

Синтаксис

[target]:xpath(expression)

• target — необязательный, стандартный или расширенный CSS-селектор
• expression — требуется, допустимое XPath выражение

Ограничения :xpath()

target можно опустить, поэтому использовать его необязательно. Для любого другого псевдокласса это будет означать «применить ко всем узлам DOM», но в случае :xpath() это просто означает «применить к целым документам», и такое применение значительно замедляет выбор элементов. Вот почему такие правила, как #?#:xpath(expression), ограничены поиском внутри тега body. Например, правило #?#:xpath(//div[@data-st-area=\'Advert\']) парсится как #?#body:xpath(//div[@data-st- area=\'Advert\']).

Расширенные селекторы с target, определённым как любой селектор, — *:xpath(expression) — всё ещё можно использовать, но не рекомендуется. Поэтому следует уточнить target.

Корректно работает только в конце селектора, за исключением псевдокласса :remove().

Примеры

:xpath(//*[@class="banner"]) выбирает элемент div#target1:

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

:xpath(//*[@class="inner"]/..) выбирает элемент div#target2:

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

Псевдокласс :nth-ancestor()

Псевдокласс :nth-ancestor() позволяет искать n-ного предка по отношению к ранее выбранному элементу.

subject:nth-ancestor(n)

• subject — обязателен. Стандартный или расширенный CSS-селектор
• n — обязателен. Число >= 1 и < 256, расстояние до нужного родителя от элемента, выбранного subject

Синтаксис

subject:nth-ancestor(n)

• subject — обязателен. Стандартный или расширенный CSS-селектор
• n — обязателен. Число >= 1 и < 256, расстояние до нужного родителя от элемента, выбранного subject

Ограничения :nth-ancestor()

Псевдокласс :nth-ancestor() не поддерживается внутри аргумента псевдокласса :not().

Примеры

Для таких DOM:

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

  <div id="target2">
    <div>
      <div>
        <div class="inner"></div>
      </div>
    </div>
  </div>
</div>

.child:nth-ancestor(1) выбирает элемент div#target1, div[class="inner"]:nth-ancestor(3) выбирает элемент div#target2.

Псевдокласс :upward()

Псевдокласс :upward() позволяет искать предка по отношению к ранее выбранному элементу.

Синтаксис

subject:upward(ancestor)

• subject — обязателен. Стандартный или расширенный CSS-селектор
• ancestor — требуется, спецификация для предка элемента, выбранного subject, может быть задана как:
  • число >= 1 и < 256 для указания расстояния до нужного предка, то же, что и :nth-ancestor()
  • стандартный CSS-селектор для поиска ближайшего предка

Ограничения :upward()

Псевдокласс :upward() не поддерживается внутри аргумента псевдокласса :not().

Примеры

Для таких DOM:

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

  <div id="target2">
    <div>
      <div>
        <div class="inner"></div>
      </div>
    </div>
  </div>
</div>

.inner:upward(div[data]) выбирает элемент div#target1, .inner:upward(div[id]) выбирает элемент div#target2, .child:upward(1) выбирает элемент div#target1, .inner:upward(3) выбирает элемент div#target2.

Псевдокласс :remove() и псевдосвойство remove

Иногда необходимо удалить определённый элемент, а не просто скрыть его или применить какие-либо правила стиля. Для этого можно использовать псевдокласс :remove(), а также псевдосвойство remove.

Псевдокласс :remove() может быть только в конце селектора.

Синтаксис

! pseudo-class
selector:remove()

! псевдосвойство
selector { remove: true; }

• subject — обязателен. Стандартный или расширенный CSS-селектор

Ограничения :remove() и remove

Псевдокласс :remove() может корректно работать только в конце селектора.

Для применения псевдокласса :remove() к любому элементу следует использовать универсальный селектор *. В противном случае такой расширенный селектор может считаться некорректным. Например, .banner > :remove() недействителен для удаления любого дочернего элемента класса banner, поэтому он должен выглядеть как .banner > *:remove().

Если используется псевдокласс :remove() или псевдосвойство remove, все свойства стиля игнорируются, кроме псевдосвойства debug.

Примеры

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

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

комментарий

Правила с псевдосвойством remove должны использовать маркер #$?#: $ для синтаксиса правил CSS-стиля, ? для синтаксиса ExtendedCss.

Псевдокласс :is()

Псевдокласс :is() позволяет сопоставить любой элемент, который может быть выбран любым из переданных ему селекторов. Некорректные селекторы пропускаются, и псевдокласс работает с допустимыми селекторами без каких-либо ошибок. Наша реализация нативного:is() псевдокласса.

Синтаксис

[target]:is(selectors)

• target — необязательный, стандартный или расширенный CSS-селектор, может быть пропущен для проверки любых элементов
• selectors — щадящий список стандартных и расширенных селекторов. Для расширенных селекторов поддерживаются только составные селекторы, а не сложные.

Ограничения :is()

Правила с псевдоклассом :is() должны использовать нативную реализацию :is(), если они используют маркер ## и если это возможно, то есть без других расширенных селекторов внутри. Чтобы принудительно применить правила ExtendedCss с :is(), используйте маркер #?#/#$?# явно.

Если selectors аргумент псевдокласса :is() — расширенный селектор, то из-за того, как псевдокласс :is() реализован в ExtendedCss 2.0, его невозможно применить к верхнему узлу DOM, который является html, т.е. #?#html:is(<extended-selectors>) не работает. Таким образом, если target не определён или определён как универсальный селектор *, применение расширенного псевдокласса ограничено htmlдочерними элементами, например, правила #?#:is(...) и #?#*:is(...) парсятся как #?#html *:is(...). Обратите внимание, что для стандартного аргумента селектора такого ограничения нет, т.е. #?#html:is(.locked) работает нормально.

Сложные селекторы с расширенными псевдоклассами не поддерживаются в качестве аргумента selectors для псевдокласса :is() — разрешены только составные. Ознакомьтесь с примерами, чтобы разобраться в деталях.

Примеры

#container *:is(.inner, .footer) выбирает только элемент div#target1:

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

Из-за ограничений :is(*:not([class]) > .banner)' не работает, но :is(*:not([class]):has(> .banner)) можно использовать вместо него для выбора элемента div#target2:

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

Псевдокласс :not()

Псевдокласс :not() позволяет выбрать элементы, которые не соответствуют селекторам, переданным в качестве аргумента. Неправильные селекторы аргументов не допускаются, и будет выдана ошибка. Наша реализация псевдокласса:not().

Синтаксис

[target]:not(selectors)

• target — необязательный, стандартный или расширенный CSS-селектор, может быть пропущен для проверки любых элементов
• selectors — список стандартных или расширенных селекторов

Ограничения :not()

Правила с псевдоклассом :not() должны использовать нативную реализацию :not(), если они используют маркер ## и если это возможно, то есть без других расширенных селекторов внутри. Чтобы принудительно применить правила ExtendedCss с :not(), используйте маркер #?#/#$?# явно.

Если selectors аргумент псевдокласса :not() — расширенный селектор, то из-за того, как псевдокласс :not() реализован в ExtendedCss 2.0, его невозможно применить к верхнему узлу DOM, который является html, т.е. #?#html:not(<extended-selectors>) не работает. Таким образом, если target не определён или определён как универсальный селектор *, применение расширенного псевдокласса ограничено дочерними html-элементами, например, правила #?#:not(...) и #?#*:not(...) парсятся как #?#html *:not(...). Обратите внимание, что для стандартного аргумента селектора такого ограничения нет, т.е. #?#html:not(.locked) работает нормально.

Псевдокласс :not() рассматривается как стандартный псевдокласс CSS внутри аргумента псевдокласса :upward(), поскольку :upward() поддерживает только стандартные селекторы.

«Восходящие» псевдоклассы :nth-ancestor() и :upward() не поддерживаются внутри аргумента selectors для псевдокласса :not().

Примеры

#container > *:not(h2, .text) выбирает только элемент div#target1:

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

Псевдокласс :if-not() (удалён)

Уведомление об удалении

Псевдокласс :if-not() удалён и больше не поддерживается. Правила с ним не работают.

Этот псевдокласс изначально был сокращением для :not(:has()). Он поддерживался ExtendedCss для лучшей совместимости с подписками на некоторые фильтры.

Приоритет косметических правил

То, как применяются правила скрытия элементов и CSS-правила, зависит от платформы.

В AdGuard для Windows, Mac и Android мы используем таблицу стилей, встроенную в страницу. Приоритет у косметических правил такой же, как и у любых других таблиц стилей CSS на сайтах. Но есть ограничение: правила скрытия элементов и CSS-правила не могут обходить встроенные стили. В таких случаях рекомендуется использовать расширенные селекторы или HTML-фильтрацию.

In AdGuard Browser Extension, the so-called "user stylesheets" are used. Их приоритет выше, даже чем у встроенных стилей.

Расширенные CSS-селекторы используют для работы JavaScript и добавляют встроенные стили сами, поэтому могут игнорировать любой стиль.

Правила фильтрации HTML

В большинстве случаев для фильтрации рекламы достаточно базовых и косметических правил. Но иногда необходимо изменить HTML-код самой страницы перед её загрузкой. Для этого применяются правила фильтрации HTML-контента. Они позволяют указать, какие HTML-элементы необходимо вырезать из страницы перед тем, как страница попадёт в браузер.

Совместимость

Правила HTML-фильтрации поддерживаются в AdGuard для Windows, AdGuard для Mac, AdGuard для Android, а также в Браузерном расширении AdGuard для Firefox. Такие правила не работают в расширениях для других браузеров, потому что они не могут модифицировать содержимое страниц на сетевом уровне.

Синтаксис

     selector = [tagName] [attributes] [pseudoClasses]
   combinator = ">"
         rule = [domains] "$$" selector *(combinator selector)
      domains = [domain0, domain1[, ...[, domainN]]]
   attributes = "[" name0 = value0 "]" "[" name1 = value2 "]" ... "[" nameN = valueN "]"
pseudoClasses = pseudoClass *pseudoClass
  pseudoClass = ":" pseudoName [ "(" pseudoArgs ")" ]

• tagName — имя элемента в нижнем регистре, например, div или script.
• domains — ограничение на домены, на страницах которых будет применено правило. Те же принципы, что и в синтаксисе правил скрытия элементов.
• attributes — список атрибутов, ограничивающих выбор элементов. name — имя атрибута, value — подстрока, которая содержится в значении атрибута.
• pseudoName — имя псевдокласса.
• pseudoArgs — аргументы псевдокласса, записанного в виде функции.
• combinator — оператор, который работает аналогично CSS-комбинатору дочерних элементов: то есть selector справа от combinator будет относиться только к элементу, прямой родительский элемент которого соответствует selector слева от combinator.

Примеры

HTML-код:

<script data-src="/banner.js"></script>

Правило:

example.org$$script[data-src="banner"]

Это правило удалит из кода страниц все элементы script со значением data-src, содержащим подстроку banner. Правило применяется только к example.org и всем его поддоменам.

Специальные атрибуты

Помимо обычных атрибутов, значение которых проверяется у каждого элемента, существует набор специальных атрибутов, которые изменяют принцип работы правила. Ниже приведен список этих атрибутов:

tag-content

Скоро устареет

В будущем этот специальный атрибут может перестать поддерживаться. Предпочтительнее использовать псевдокласс :contains() там, где это возможно.

Это наиболее часто используемый специальный атрибут. Он ограничивает выбор теми элементами, внутренний HTML-код которых содержит указанную подстроку.

Вы должны использовать "", чтобы избежать ", например: $$script[tag-content="alert(""this is ad"")"]

Например, рассмотрим такой HTML-код:

<script type="text/javascript">
    document.write('<div>banner text</div>" />');
</script>

Следующее правило удалит все script элементы с подстрокой banner в их коде:

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

Ограничения

Специальный атрибут tag-content не должен появляться в селекторе слева от комбинатора >.

wildcard

Скоро устареет

В будущем этот специальный атрибут может перестать поддерживаться. Предпочтительнее использовать псевдокласс :contains() там, где это возможно.

Этот специальный атрибут работает почти как tag-content и позволяет проверить внутренний HTML-код документа. Rule will check if HTML code of the element fits the search pattern.

Вы должны использовать "", чтобы избежать ", например: $$script[wildcard=""banner""]

Например: $$script[wildcard="*banner*text*"]

Оно проверяет, что код элемента содержит две последовательные подстроки banner и text.

Ограничения

Специальный атрибут wildcard не должен появляться в селекторе слева от комбинатора >.

max-length

Скоро устареет

В будущем этот специальный атрибут может перестать поддерживаться. Предпочитайте использовать псевдокласс :contains() с регулярным выражением, где это возможно.

Задает максимальную длину содержимого HTML-элемента. Если этот параметр задан и длина содержимого превышает заданное значение, правило не применяется к элементу.

Значение по умолчанию

Если этот параметр не указан, то максимальная длина `` считается равной 8192.

Например:

$$div[tag-content="banner"][max-length="400"]

Это правило удалит все элементы div, код которых содержит подстроку banner и длина которых не превышает 400 символов.

Ограничения

Специальный атрибут max-length не должен появляться в селекторе слева от комбинатора >.

min-length

Скоро устареет

В будущем этот специальный атрибут может перестать поддерживаться. Предпочитайте использовать псевдокласс :contains() с регулярным выражением, где это возможно.

Задаёт минимальную длину содержимого HTML-элемента. Если этот параметр задан и длина содержимого меньше заданного значения, правило не применяется к элементу.

Например:

$$div[tag-content="banner"][min-length="400"]

Это правило удалит все элементы div, код которых содержит подстроку banner и длина которых превышает 400 символов.

Ограничения

Специальный атрибут min-length не должен появляться в селекторе слева от комбинатора >.

Псевдоклассы

:contains()

Синтаксис

:contains(текст без кавычек)

или

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

Совместимость

:-abp-contains() и :has-text() являются синонимами для :contains().

Совместимость

Псевдокласс :contains() поддерживается AdGuard для Windows, Mac и Android с CoreLibs 1.13 или более поздней версией.

Требует, чтобы внутренний HTML-код элемента содержал указанный текст или соответствовал указанному регулярному выражению.

Ограничения

Псевдокласс :contains() не должен появляться в селекторе слева от комбинатора >.

Исключения

По аналогии с правилами скрытия, существует специальный тип правил, отключающий действие выбранного правила HTML-фильтрации для определённых доменов. Синтаксис правил-исключений такой же, только маркер $$ заменяется на $@$.

Например, в фильтре есть правило:

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

Если вы хотите отключить его для домена example.com, вы можете создать правило исключения:

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

В некоторых случаях может потребоваться отключение всех запрещающих правил. Например, на время тестирования. Для этого воспользуйтесь правилом исключения без указания домена.

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

Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия невозможно. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.

Правила JavaScript

AdGuard поддерживает особый тип правил, который позволяет внедрять любой код JavaScript на страницы сайтов.

Мы настоятельно рекомендуем использовать скриптлеты вместо JavaScript-правил везде, где это возможно. JS-правила должны помочь в процессе отладки, но в качестве долгосрочного решения следует использовать скриптлеты.

Синтаксис

rule = [domains] "#%#" script

• domains — доменное ограничение для правила. Строится по тем же правилам, что и в случае правил скрытия элементов.
• script — произвольный JavaScript-код в одну строку.

Примеры

• example.org#%#window.__gaq = undefined; выполняет код window.__gaq = undefined; на всех страницах сайта example.org и всех его поддоменах.

Исключения

Similar to hiding rules, there is a special type of rules that disable the selected JavaScript rule for particular domains. Синтаксис правил-исключений такой же, только маркер #%# заменяется на #@%#.

Например, в фильтре есть правило:

#%#window.__gaq = undefined;

Если вы хотите отключить его для домена example.com, вы можете создать правило исключения:

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

В некоторых случаях может потребоваться отключение всех запрещающих правил. Например, на время тестирования. Для этого воспользуйтесь правилом исключения без указания домена.

#@%#window.__gaq = undefined;

Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия невозможно. Во всех остальных случаях лучше изменить исходное правило, используя ограничение на домены.

Ограничения

Правила JavaScript можно использовать только в доверенных фильтрах.

Совместимость

Правила JavaScript не поддерживаются блокировщиком контента AdGuard.

Правила скриптлета

Скриптлет — это функция JavaScript с расширенными возможностями для блокировки контента. Такие функции могут использоваться в декларативной манере в правилах фильтрации AdGuard.

комментарий

AdGuard поддерживает множество различных скриптлетов. Чтобы добиться совместимости между различными блокировщиками, мы также поддерживаем синтаксис uBO и ABP.

Синтаксис правил блокировки

[domains]#%#//scriptlet(name[, arguments])

• domains — опционально, список доменов, к которым должно применяться правило;
• name — required, a name of the scriptlet from the AdGuard Scriptlets library;
• arguments — опционально, список аргументов в формате string (другие типы аргументов не поддерживаются).

Примеры

1. Примените скриптлет abort-on-property-read на всех страницах сайта example.org и его поддоменах, и передайте ему аргумент alert:

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

2. Удалить класс branding из всех элементов div[class^="inner"] на всех страницах сайта example.org и его поддоменах:

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

Синтаксис правил исключений

Правила исключений могут отключать некоторые скриптлеты на определённых доменах. Синтаксис правил исключений скриптлетов аналогичен обычным правилам скриптлетов, но использует #@%# вместо #%#:

[domains]#@%#//scriptlet([name[, arguments]])

• domains — опционально, список доменов, к которым должно применяться правило;
• имя — опционально, имя скриптлета, который следует исключить; если не задано, все скриптлеты не будут применены;
• arguments — опционально, список аргументов string для соответствия одному и тому же правилу блокировки и его отключения.

Примеры

1. Отключите определённое правило скриптов, чтобы применялось только abort-on-property-read только на example.org и его поддоменах:

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

2. Отключите все скриптлеты abort-on-property-read для example.com и его поддоменов:

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

3. Отключите все скриптлеты для example.com и его поддоменов:

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

4. Примените set-constant и set-cookie к любой веб-странице, но из-за специального правила исключения скриптов только скрипт set-constant будет применен на example.org и его поддоменах:

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

5. Примените adjust-setInterval к любой веб-странице и set-local-storage-item на example.com и его поддоменах, но есть также несколько правил исключения скриптов, поэтому правила скриптлетов не будут применяться на example.com и его поддоменах:

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

Подробнее об отладке скриптлетов.

Более подробную информацию о скриптлетах можно найти на GitHub.

Совместимость

Скриптлеты не поддерживаются в AdGuard Content Blocker.

Полный синтаксис правил исключений скриптлетов поддерживается AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs v1.16 или более поздней версией, а также расширением браузера AdGuard для Chrome, Firefox и Edge с TSUrlFilter v3.0 или более поздней версией. Предыдущие версии поддерживали только правила исключений, которые отключали определённые скриптлеты.

Доверенные скриптлеты

Доверенные скриптлеты — это скриптлеты с расширенной функциональностью. У них тот же синтаксис и ограничения. У имён доверенных скриптлетов есть префикс trust-, например, trust-set-cookie, чтобы их было легко отличить от обычных скриптлетов.

комментарий

Доверенные скриптлеты несовместимы с другими блокировщиками рекламы, кроме AdGuard.

Ограничения

Доверенные скриптлеты правила можно использовать только в доверенных фильтрах.

Совместимость

Доверенные скриптлеты не поддерживаются в AdGuard Content Blocker.

Подробнее об отладке скриптлетов.

Более подробную информацию о доверенных скриптлетах можно найти на GitHub.

Модификаторы для небазовых правил

Поведение любого правила можно изменить, используя модификаторы, описанные ниже.

Синтаксис {#non-basic-rules-modifiers-syntax}

rule = "[$" modifiers "]" [rule text]
modifiers = modifier0[, modifier1[, ...[, modifierN]]]

• modifier — набор модификаторов, описанных ниже.
• rule text — правило, которое нужно модифицировать.

Например: [$domain=example.com,app=test_app]##selector.

В значениях модификаторов следующие символы должны быть экранированы: [, ], , и \ (если он не используется для экранирования). Используйте \, чтобы экранировать их. Например, экранированная скобка выглядит так: \].

Модификатор \ Продукты	Приложения CoreLibs	AdGuard для Chromium	AdGuard для Chrome MV3	AdGuard для Firefox	AdGuard для iOS	AdGuard для Safari	AdGuard Content Blocker
$app	✅	❌	❌	❌	❌	❌	❌
$domain	✅	✅	✅ *[1]	✅	✅	✅	❌
$path	✅	✅	❌	✅	✅	✅	❌
$url	✅	✅ *[2]	✅ *[2]	✅ *[2]	❌	❌	❌

комментарий

• ✅ — полностью поддерживается
• ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
• ❌ — не поддерживается

$app

Модификатор $app ограничивает действие правила до конкретного приложения или списка приложений. Поведение и синтаксис модификатора полностью совпадают с соответствующим модификатором $app для базовых правил.

Примеры

• [$app=org.example.app]example.com##.textad скрывает div с классом textad на example.com и всех поддоменах в запросах, отправленных из приложения Android org.example.app.
• [$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') применяет скриптлет prevent-setInterval только в браузере Safari на Mac.
• [$app=org.example.app]#@#.textad отключает все правила ##.textad для всех доменов при использовании org.example.app.

Совместимость

Такие правила с модификатором $app поддерживаются AdGuard для Windows, AdGuard для Mac и AdGuard для Android.

$domain

Модификатор $domain ограничивает область действия правила списком доменов и их поддоменов. Поведение и синтаксис модификатора полностью совпадают с соответствующим модификатором $domain для базовых правил.

Примеры

• [$domain=example.com]##.textad скроет элемент div с классом textad на домене example.com и всех его поддоменах.
• [$domain=example.com|example.org] скроет элемент с атрибутом id равным adblock на доменах example.com, example.org и всех их поддоменах.
• [$domain=~example.com]##.textad — это правило скроет div элементы с классом textad на всех доменах, кроме example.com и всех его поддоменов.

Существует 2 способа указать ограничения домена для небазовых правил:

1. «классический»: обозначить ограничение на домены перед маской и атрибутами правила: example.com##.textad;
2. с помощью модификаторов: обозначить ограничение на домены через модификатор $domain: [$domain=example.com]##.textad.

Однако правила с ограничением доменов смешанного стиля считаются недействительными. Так, например, правило [$domain=example.org]example.com##.textad будет проигнорировано.

Небазовые ограничения модификатора $domain

Ограничения

Так как небазовый $domain работает так же, как и базовый, он имеет те же ограничения.

Совместимость

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

$path

Модификатор $path ограничивает область применения правила определёнными местами или страницами на сайтах.

Синтаксис

$path ["=" pattern]

pattern — опционально, маска пути, которой ограничивается правило. Его синтаксис и поведение почти такие же, как в шаблоне базовых правил. Вы также можете использовать специальные символы, кроме ||, который в этом случае не имеет смысла (см. примеры ниже).

Если не задан pattern для $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 любого домена (обратите внимание на специальные экранированные символы)

Совместимость

Правила с модификатором $path не поддерживаются AdGuard Content Blocker.

$url

Модификатор $url ограничивает действие правила URL-адресами, соответствующими указанной маске.

Синтаксис

url = pattern

где pattern практически то же самое, что и pattern базовых правил за исключением того, что некоторые символы должны быть экранированы. Специальные символы и регулярные выражения также поддерживаются.

Примеры

• [$url=||example.com/content/*]##div.textad скрывает div с классом textad в запросах, например, к https://example.com/content/article.html и https://subdomain.example.com/content/article.html.
• [$url=||example.org^]###adblock скрывает элемент с атрибутом id равным adblock в запросах к example.org и всем его поддоменам.
• [$url=/\[a-z\]+\\.example\\.com^/]##.textad скрывает div элементы класса textad для всех доменов, соответствующих регулярному выражению [a-z]+\.example\.com^.

Ограничения модификатора $url

Ограничения

В Браузерном расширении AdGuard небазовый модификатор $url несовместим с доменно-специфичными правилами и другими небазовыми модификаторами — $domain и $path. Например, правило [$url=/category/*]example.com###textad не будет применено.

Совместимость

Правила с модификатором $url поддерживаются в AdGuard для Windows, AdGuard для Mac и AdGuard для Android с CoreLibs версии 1.11 или выше, и в Браузерном расширении AdGuard с TSUrlFilter версии 3.0.0 или выше.

Информация для разработчиков фильтров

Если вы разрабатываете сторонний фильтр, известный AdGuard, вам может быть интересна информация, представленная в этом разделе. Имейте в виду, что подсказки будут применяться только к зарегистрированным фильтрам. Фильтр считается зарегистрированным и известным AdGuard, если он присутствует в индексе известных фильтров. Если вы хотите, чтобы ваш фильтр был зарегистрирован, направьте запрос в репозиторий AdguardFilters.

Директивы препроцессора

Мы предоставляем директивы препроцессора, которые могут использоваться разработчиками фильтров для улучшения совместимости с различными блокировщиками рекламы, а также обеспечиваем:

• включение файла
• условное применение правил по типу блокировщика рекламы
• указание блокировщика содержимого для правил, применяемых в Safari

комментарий

Любая ошибка в директиве препроцессора приведёт к тому, что AdGuard не сможет обновить фильтр так же, как если бы 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. Условия поддерживают все основные логические операторы.

Есть два возможных сценария:

1. Если блокировщик рекламы встречает директиву !#if и не встречает директиву !#else, то он компилирует код между директивами !#if и !#endif только в том случае, если указанное условие истинно.

2. Если существует директива !#else, код между !#if и !#else будет скомпилирован, если условие истинно; в противном случае будет скомпилирован код между !#else и !#endif.

комментарий

Пробелы имеют значение. !#if является допустимой директивой, а !# if — нет.

Синтаксис

!#if (conditions)
rules_list
!#endif

или

!#if (условия)
true_conditions_rules_list
!#else
false_conditions_rules_list
!#endif

где:

• !#if (условия) — начало блока при выполнении условий
• conditions — точно так же, как и в случае с некоторыми популярными языками программирования, условия препроцессинга основаны на константах, объявляемых блокировщиками. Разработчики блокировщиков самостоятельно определяют, какие именно константы объявлять. Возможные значения:
  • adguard объявляется всегда; даёт разработчикам фильтров понять, что это один из продуктов AdGuard; должно быть достаточно в 95% случаев
  • специфичные для конкретных продуктов константы, которые нужны в редких случаях, когда правило должно работать (или не работать — тогда перед константой используйте !) только для конкретного продукта:
    • adguard_app_windows — AdGuard для Windows
    • adguard_app_mac — AdGuard для Mac
    • adguard_app_android — AdGuard для Android
    • adguard_app_ios — AdGuard для iOS
    • adguard_ext_safari — AdGuard для Safari
    • adguard_ext_chromium — Браузерное расширение AdGuard для Chrome (и браузеры на основе Chrome, например, новый Microsoft Edge)
    • adguard_ext_chromium_mv3 — AdGuard для Chrome MV3
    • adguard_ext_firefox — Браузерное расширение AdGuard для Firefox
    • adguard_ext_edge — Браузерное расширение AdGuard для Edge Legacy
    • adguard_ext_opera — Браузерное расширение AdGuard для Opera
    • adguard_ext_android_cb — AdGuard Content Blocker для мобильных браузеров Samsung и Яндекс
    • ext_ublock — особый случай; эта константа объявляется, когда версия фильтра для uBlock компилируется при помощи FiltersRegistry
    • cap_html_filtering — продукты, поддерживающие правила HTML-фильтрации: AdGuard для Windows, AdGuard для Mac и AdGuard для Android
• !#else — начало блока, когда условия ложны
• rules_list, true_conditions_rules_list, false_conditions_rules_list — списки правил
• !#endif — конец блока

Примеры

! для всех продуктов AdGuard, кроме AdGuard для Safari
!#if (adguard && !adguard_ext_safari)
||example.org^$third-party
domain.com##div.ad
!#endif

! директивы также можно совмещать
!#if (adguard_app_android)
!#include /androidspecific.txt
!#endif

!#if (adguard && !adguard_ext_safari)
! для всех продуктов AdGuard, кроме AdGuard для Safari
||example.org^$third-party
domain.com##div.ad
!#else
! только для AdGuard для Safari
||subdomain.example.org^$third-party
!#endif

Совместимость

Директива !#else поддерживается FiltersDownloader 1.1.20 или более поздней версии.

Он уже поддерживается для списков фильтров, составленных с помощью FiltersRegistry, но всё ещё может не поддерживаться продуктами AdGuard при добавлении списка фильтров с !#else в качестве пользовательского. Следующие продукты будут поддерживать его в указанных версиях или более поздних версиях:

• AdGuard для Windows, Mac и Android c CoreLibs 1.13;
• Браузерное расширение AdGuard 4.2.208;
• AdGuard 1.11.16 для Safari.

Правила фильтрации в Safari

Лимит каждого блокировщика контента Safari — 150 000 активных правил. Но в AdGuard для Safari и AdGuard для iOS мы разделили правила на 6 блокировщиков контента, тем самым увеличив лимит правил до 900 000.

Какие фильтры содержатся в каждом блокировщике контента:

• AdGuard General — Блокировка рекламы, Языковые
• AdGuard Privacy — Антитрекинг
• AdGuard Social — Виджеты социальных сетей, Раздражители
• AdGuard Security — Безопасность
• AdGuard Other — Другие
• AdGuard Custom — Собственные

Пользовательские правила и белый список добавляются в каждый блокировщик контента.

осторожно

Основной недостаток использования нескольких блокировщиков контента в том, что правила из разных блокировщиков применяются независимо друг от друга. На правила блокировки это не влияет, но с правилами разблокировки могут быть проблемы. Если правило блокировки есть в одном блокировщике контента, а исключение — в другом, то исключение не сработает. Разработчики фильтров используют !#safari_cb_affinity, чтобы указать, к какому блокировщику контента принадлежат правила.

Синтаксис

!#safari_cb_affinity(content_blockers)
rules_list
!#safari_cb_affinity

где:

• !#safari_cb_affinity(content_blockers) — начало блока
• content_blockers — список блокировщиков контента, разделённых запятой. Возможные значения:
  • general — блокировщик контента AdGuard General
  • privacy — блокировщик контента AdGuard Privacy
  • social — блокировщик контента AdGuard Social
  • security — блокировщик контента AdGuard Security
  • other — блокировщик контента AdGuard Other
  • custom — блокировщик контента AdGuard Custom
  • all — специальное ключевое слово, которое означает, что правила должны быть включены во все блокировщики контента
• 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)

Можно применить несколько подсказок.

Подсказка NOT_OPTIMIZED

Для каждого фильтра AdGuard существуют две версии: полная и оптимизированная. Оптимизированная версия намного легче и не содержит правил, которые не используются вообще или используются редко.

Частота использования правил определяется собранной статистикой по рекламным фильтрам. Но оптимизация основана также на исходной конфигурации для каждого фильтра. Например, вот так это выглядит для Базового фильтра:

"filter": Базовый фильтр AdGuard,
"percent": 30,
"minPercent": 20,
"maxPercent": 40,
"strict": true

где:

• filter — идентификатор фильтра
• percent — ожидаемый процент оптимизации ~= (количество правил в оптимизированном фильтре) / (количество правил в исходном фильтре) * 100
• minPercent — нижняя граница значения percent
• maxPercent — верхняя граница значения percent
• strict — если включены percent < minPercent или percent > maxPercent и строгий режим, то компиляция фильтра должна завершиться неудачно, в противном случае должны использоваться оригинальные правила

Другими словами, percent — это «уровень сжатия». Например, для Базового фильтра он настроен на 40%. Это означает, что алгоритм оптимизации должен убрать 60% правил.

В итоге, вот так выглядят версии Базового фильтра для Браузерного расширения AdGuard для Chrome:

• полная: https://filters.adtidy.org/extension/chromium/filters/2.txt
• оптимизированная: https://filters.adtidy.org/extension/chromium/filters/2_optimized.txt

Если вы хотите добавить правило, которое не должно удаляться при оптимизации, используйте подсказку NOT_OPTIMIZED:

!+ NOT_OPTIMIZED
||example.org^

А такое правило не будет оптимизировано только для AdGuard для Android:

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

Подсказки PLATFORM и NOT_PLATFORM

Записи этого типа позволяют указывать платформу, для которой применяется правило. Ниже представлен список используемых платформ и ссылки на Базовый фильтр для каждой из них:

• windows — AdGuard для Windows — https://filters.adtidy.org/windows/filters/2.txt

• mac — AdGuard для Mac — https://filters.adtidy.org/mac_v2/filters/2.txt

• android — AdGuard для Android — https://filters.adtidy.org/android/filters/2.txt

• ios — AdGuard для iOS — https://filters.adtidy.org/ios/filters/2.txt

• ext_chromium — Браузерное расширение AdGuard для Chrome — https://filters.adtidy.org/extension/chromium/filters/2.txt

• ext_chromium — Браузерное расширение AdGuard для Chrome MV3 — https://filters.adtidy.org/extension/chromium-mv3/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_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

• ext_ublock — uBlock Origin — https://filters.adtidy.org/extension/ublock/filters/2.txt

Примеры

Это правило будет действовать только в AdGuard для Windows, Mac и Android:

!+ PLATFORM(windows,mac,android)
||example.org^

За исключением AdGuard для Safari, AdGuard Content Blocker и AdGuard для iOS, это правило доступно на всех платформах:

!+ NOT_PLATFORM(ext_safari, ext_android_cb, ios)
||example.org^

Отладка правил фильтрации

Хоть самые простые правила фильтрации и возможно придумать «в голове», для чего-то чуть более сложного вам потребуются дополнительная помощь в их отладке и повторении. Есть инструменты, которые помогут вам в этом. Вы можете использовать «Инструменты разработчика» в Chrome и их аналоги в других браузерах, но большинство продуктов AdGuard предоставляют и другой инструмент — Журнал фильтрации.

Журнал фильтрации

Журнал фильтрации — продвинутый инструмент, который полезен в основном разработчикам фильтров. В нём отображаются все веб-запросы, проходящие через AdGuard, даётся исчерпывающая информация по каждому из них, предлагаются различные опции сортировки и другие полезные возможности.

В зависимости от того, какой продукт AdGuard вы используете, журнал фильтрации может находиться в разных местах.

• В AdGuard для Windows вы найдёте его во вкладке настроек Антибаннер или через меню трея
• В AdGuard для Mac он располагается в разделе Настройки → Дополнительно → Журнал фильтрации
• В AdGuard для Android его можно найти в разделе Статистика → Недавняя активность. Доступ к недавней активности также можно получить из Помощника
• В Браузерном расширении AdGuard он находится во вкладке настроек Дополнительно, а также доступен по клику правой кнопкой мыши по иконке расширения. Только веб-браузеры на основе Chromium и Firefox отображают применённые правила скрытия элементов (включая CSS, ExtCSS) и JS-правила и скриптлеты в своих Журналах фильтрации

комментарий

В AdGuard для iOS и в AdGuard для Safari Журнал фильтрации отсутствует из-за особенностей реализации блокировщиков контента в Safari. AdGuard сам не видит веб-запросы и поэтому не может отображать их.

Режим отладки селекторов

Иногда может понадобиться проверить производительность того или иного селектора или таблицы стилей. Чтобы сделать это без непосредственного взаимодействия с JavaScript, вы можете использовать свойство стиля debug. Когда ExtendedCss встречает это свойство, он включает режим отладки для конкретного селектора или для всех селекторов, в зависимости от значения debug.

Откройте консоль браузера, находясь на веб-странице, чтобы посмотреть статистику по времени, затраченному на применение селектора(-ов). В режиме отладки следующая статистика отображается в виде объекта, где каждый из отлаживаемых селекторов является ключом, а значение — объектом с такими свойствами:

Всегда выводится:

• selectorParsed — текст разобранного селектора, может отличаться от входного
• timings — список узлов DOM, соответствующих селектору
  • appliesCount — общее количество раз, когда на странице был применён селектор
  • appliesTimings — время, которое ушло на применение селектора на странице, для каждого из случаев применения этого селектора (в миллисекундах)
  • meanTiming — среднее время, ушедшее на применение селектора на странице
  • standardDeviation — стандартное отклонение
  • timingsSum — общее время, ушедшее на все применения селектора на текущей странице

Выводится только для удаления псевдонимов:

• removed — флаг, сигнализирующий об удалении элементов

Выводится, если элементы не удалены:

• matchedElements — список узлов DOM, соответствующих селектору
• styleApplied — объявление обработанного стиля правила, связанного с селектором

Примеры

Отладка конкретного селектора:

Когда значение свойства debug равно true, информация только по этому селектору будет отображена в консоли браузера.

#$?#.banner { display: none; debug: true; }

Включение глобальной отладки:

Когда значение свойства debug равно global, в консоли будет отображаться информация по всем CSS-селекторам, которые были применены на данной странице, для всех правил из любого из включённых фильтров.

#$?#.banner { display: none; debug: global; }

Тестирование расширенных селекторов без AdGuard

ExtendedCss может быть выполнен на любой странице без использования какого-либо продукта AdGuard. Для этого скопируйте и запустите следующий код в консоли браузера:

!function(e,t,d){C=e.createElement(t),C.src=d,C.onload=function(){alert("ExtendedCss loaded successfully")},s=e.getElementsByTagName(t)[0],s?s.parentNode.insertBefore(C,s):(h=e.getElementsByTagName("head")[0],h.appendChild(C))}(document,"script","https://AdguardTeam.github.io/ExtendedCss/extended-css.min.js");

Или установите пользовательский скрипт ExtendedCssDebugger.

Теперь вы можете использовать ExtendedCss глобально и запустить его метод query() как Document.querySelectorAll().

Примеры

const selector = 'div.block:has=(.header:matches-css(after, content: Ads))';

// массив HTMLElements, соответствующих `selector`, должен быть возвращён
ExtendedCss.query(selector);

Отладка скриптлетов

Если вы используете Браузерное расширение AdGuard и хотите отладить правило скриптлета или доверенного скриптлета, то можете получить дополнительную информацию, открыв журнал фильтрации. В этом случае скриптлеты перейдут в режим отладки и будут записывать больше информации в браузерную консоль.

Следующие скриптлеты разработаны специально для отладки:

• debug-current-inline-script
• debug-on-property-read
• debug-on-property-write
• log-addEventListener
• log-on-stack-trace
• log-eval
• log

Следующие скриптлеты тоже могут быть использованы для отладки:

• json-prune
• prevent-fetch
• prevent-requestAnimationFrame
• prevent-setInterval
• prevent-setTimeout
• prevent-window-open с указанным параметром replacement
• prevent-xhr
• trusted-replace-fetch-response
• trusted-replace-xhr-response

Легенда таблиц совместимости

Краткие обозначения продуктов

1. CoreLibs apps — AdGuard для Windows, AdGuard для Mac и AdGuard для Android
2. AdGuard for Chromium — AdGuard Browser Extension for Chrome and other Chromium-based browsers such as Microsoft Edge and Opera
3. AdGuard для Chrome MV3 — Браузерное расширение AdGuard для Chrome MV3
4. AdGuard для Firefox — Браузерное расширение AdGuard для Firefox
5. AdGuard для iOS — AdGuard для iOS и AdGuard Pro для iOS (для мобильного браузера Safari)
6. AdGuard для Safari — AdGuard для десктопного браузера Safari
7. AdGuard Content Blocker — Блокировщик контента для мобильных браузеров Android: Samsung Internet и Яндекс Браузера

Краткие обозначения совместимости

комментарий

• ✅ — полностью поддерживается
• ✅ * — поддерживается, но надёжность может быть разной или могут возникнуть ограничения; ознакомьтесь с описанием модификатора для получения подробной информации
• 🧩 — может быть уже реализован в nightly- или бета-версиях, но пока не поддерживается в релизных версиях
• ⏳ — планируется к реализации, но пока недоступен ни в одном продукте
• ❌ — не поддерживается
• 👎 — устарел; всё ещё поддерживается, но в будущем будет удалён
• 🚫 — удалён и больше не поддерживается