Создание фильтров для Adblock Plus
Оригинал статьи находится тут.Введение
Этот документ расскажет о возможностях, которые у вас есть, и о том, как их использовать.Параметров описанных в этом разделе должно быть достаточно для создания пользовательских фильтров в случае такой необходимости.
Внимание: Все примеры фильтров приведённые здесь являются только примерами и не предназначены для непосредственного использования.
Основные правила
Наиболее простой фильтр это адрес баннера, который вы хотите заблокировать. Однако, часто этот адрес изменяется каждый раз при загрузке страницы. Например, он может быть http://example.com/ads/banner123.gif где 123 -случайное число. В этом случае блокирование по адресу вам не поможет, вам нужен более общий фильтр, такой как http://example.com/ads/banner*.gif. Или, может быть, даже http://example.com/ads/*.
Примечание: Убедитесь, что вы не обобщили слишком многое. Фильтр http://example.com/* безусловно, заблокирует все баннеры, но также заблокирует всё остальное с example.com то, что вы можете захотеть увидеть.
Исключающие правила
Иногда вы можете заметить, что один из ваших фильтров обычно работающий нормально, блокирует то, что не должно быть блокировано. Вы не хотите удалять этот фильтр, но вы также не хотите, чтобы это продолжалось.
Для этого случая есть исключающие правила - они позволяют вам определить, в каком случае фильтры не должны применяться. Например, если фильтр adv блокирует http://example.com/advice.html, вы можете установить исключающее правило @@advice. Исключающие правила не отличаются правил фильтров, вы можете использовать символы обобщения или регулярные выражения. Только вы должны начинать их с @@, указывающее на исключающее правило.
Exception rules can do more. If you specify $document option you will get an exception for the entire page. For example, if your exception rule is @@||example.com^$document and you open some page from example.com — Adblock Plus will be entirely disabled on this page and nothing will be blocked.
Соответствие началу/концу адреса
Обычно Adblock Plus обрабатывает каждый фильтр так,как если бы он имел обобщения в начале и в конце. Например, нет разницы между фильтрами ad и *ad*.Обычно это не является проблемой, но иногда вы можете захотеть, чтобы ваш фильтр соответствовал в начале или в конце адресов. Например, вы можете захотеть заблокировать весь Flash, но если вы добавите фильтр swf , адрес http://example.com/swf/index.html также будет заблокирован.
Решение проблемы: добавьте к фильтру символ |, чтобы показать, что конец адреса находится в этой точке. Например, фильтр swf| будет блокировать http://example.com/annoyingflash.swf , но не http://example.com/swf/index.html. А фильтр |http://baddomain.example/ будет блокировать http://baddomain.example/banner.gif , но не http://gooddomain.example/analyze?http://baddomain.example.
Иногда хочется заблокировать http://example.com/banner.gif вместе с https://example.com/banner.gif и http://www.example.com/banner.gif. Этого можно достичь добавлением пары символов | в начало фильтра соответствующего началу доменного имени: ||example.com/banner.gif заблокирует все эти адреса и не тронет http://badexample.com/banner.gif или http://gooddomain.example/analyz...e.com/banner.gif (необходим Adblock Plus 1.1 и выше).
Разделительные символы
Часто вам нужно будет применить в фильтре любой разделительный символ. Например, вы можете написать фильтр, который блокирует http://example.com/ и http://example.com:8000/ , но не http://example.com.ar/. Здесь символ ^ может быть использован как указатель для одного разделительного символа: http://example.com^ (необходим Adblock Plus 1.1 и выше).
Разделителем может быть любой символ кроме буквы, цифры и следующих символов: _ - . %. К концу адреса также применим разделитель. В следующем примере все разделители показаны красным: http://example.com:8000/foo.bar?a=12&b=%D1%82%D0%B5%D1%81%D1%82. Также этот адрес может быть блокирован фильтром ^example.com^ или ^%D1%82%D0%B5%D1%81%D1%82^ или ^foo.bar^.
Комментарии
Любое правило, начинающееся с восклицательного знака содержит комментарий. Оно отображается в списке фильтров серым цветом. Adblock Plus будет игнорировать это правило при блокировании, так что можете спокойно писать там всё, что хотите. Вы можете расположить комментарий выше реального фильтра, чтобы описать для чего он нужен. Или вы можете разместить комментарий с указанием вашего авторства вверху списка фильтров (так делают большинство авторов).
Special comments
Special comments will only have an effect in downloaded filter lists, not in custom filters. Special comments must be given at the top of the filter list right below the header. They can set a number of parameters for the filter list:
! Homepage: http://example.com/
This comment determines which webpage should be linked as filter list homepage.
! Title: FooList
This comment sets a fixed title for the filter list. If this comment is present the user will no longer be able to change the title.
! Expires: 5 days
This comment sets the update interval for the filter list, the value can be given in days (e.g. 5 days) or hours (e.g. 8 hours). Any value between 1 hour and 14 days is possible. Note that the update will not necessarily happen after this time interval. The actual update time is slightly randomized and depends on some additional factors to reduce server load.
! Redirect: http://example.com/list.txt
This comment indicates that the filter list has moved to a new download address. Adblock Plus will ignore any file contents beyond that comment and immediately try downloading from the new address. In case of success the address of the filter list will be updated in the settings. This comment is ignored if the new address is the same as the current address, meaning that it can be used to enforce the "canonical" address of the filter list.
! Version: 1234
This comment defines a numerical version of the filter list. This version number will be displayed in issue reports and can be used to verify that the report refers to the current version of the filter list.
Расширенные возможности
Возможности, описанные в этом разделе, обычно используются опытными пользователями или создателями подписок. Вы можете пропустить его.
Специфические опции фильтра
Adblock Plus позволяет вам определить число параметров, изменяющих поведение фильтра. Список этих параметров располагается в конце фильтра после знака доллара ($) и разделяется запятыми, например:
*/ads/*$script,match-case
Здесь */ads/* текущий фильтр script и match-case его параметры. В настоящее время поддерживаются следующие параметры:
Типы параметров: определяют, какие типы элементов могут быть заблокированы фильтром (или пропущены в случае исключающего правила). Составной тип параметров, может быть определен, чтобы показать, что фильтр может быть применен к нескольким типам элементов. Доступные типы:
script — внешние файлы скриптов загруженные через HTML-тэг SCRIPT
image — обычные изображения, загруженные через HTML-тэг IMG
stylesheet — внешние CSS-файлы стилей
object — содержимое, управляемое плагинами браузера, напр. Flash или Java
xmlhttprequest — requests started using the XMLHttpRequest object or fetch() API
object-subrequest — запросы инициированные плагинами вроде Flash
subdocument — встроенные страницы, обычно при помощи HTML-фреймов
ping — requests started by <a ping> or navigator.sendBeacon() (Adblock Plus 2.7.1 or higher required)
websocket — requests initiated via WebSocket object (Adblock Plus 2.8 or higher required)
webrtc — connections opened via RTCPeerConnection instances to ICE servers (Adblock Plus 1.13.3 for Chrome and Opera, 3.0 for Firefox, or higher required)
document — сама страница (только исключающие правила могут быть применены к этой странице)
elemhide — только для исключающих правил, схоже с document но отключает только правила скрытия элементов, а не все правила фильтрации на странице (требуется Adblock Plus 1.2 и выше)
generichide — for exception rules only, similar to elemhide but only disables generic element hiding rules on the page (Adblock Plus 2.6.12 or higher required)
genericblock — for exception rules only, just like generichide but disables generic blocking rules (Adblock Plus 2.6.12 or higher required)
popup — pages opened in a new tab or window
other — типы запросов не перечисленные выше
The type options background, xbl and dtd are outdated and should no longer be used.
Обратные типы параметров: определяет типы элементов, фильтр к которым применяться не должен. Доступные параметры обратных типов: ~script, ~image, ~stylesheet, ~object, ~xmlhttprequest, ~object-subrequest, ~subdocument, ~document, ~elemhide, ~other
Ограничение на сторонние/собственные запросы: Если указана опция third-party, то фильтр применяется лишь к запросам ресурсов из внешних источников. Аналогично, ~third-party ограничивает фильтр запросами из того-же источника, что и открытая страница.
Ограничители доменов: Параметр domain=example.com означает, что фильтр должен быть применён только на страницах домена "example.com". Множество доменов можно установить, используя "|" как разделитель: с параметром domain=example.com|example.net фильтр будет применён только на страницах доменов "example.com" или "example.net". Если доменное имя начинается с "~", фильтр не должен применяться на страницах этого домена. Например, domain=~example.com показывает, что фильтр должен применяться на страницах любого домена, но "example.com" и domain=example.com|~foo.example.com ограничивает фильтр доменом "example.com" исключая поддомен "foo.example.com".
Sitekey restrictions: The option sitekey=abcdsitekeydcba means that the filter should only be applied on pages that provide a public key and a signature which can be verified by that very same public key that is also contained in the filter (but without the trailing =). Multiple sitekeys can be specified using "|" as separator: with the option sitekey=abcdsitekeydcba|bcdesitekeyedcb the filter will only be applied on pages providing either sitekey "abcdsitekeydcba" or "bcdesitekeyedcb". This is similar to domain restrictions but allows covering scenarios where a single filter should apply to a very large number of domains. Note that sitekey restrictions require modifications on the server-side.
Content Security Policies: The option csp=script-src: 'none' causes a Content Security Policy header of script-src: 'none' to be injected into HTTP responses for requested documents matching the filter — assuming that exception rules with the same option don't also match and that the document isn’t whitelisted. The Content Security Policy script-src: 'none' would in turn block all scripts — including inline — for the document. This filter option should generally be avoided, except as a last resort to counter advanced circumvention. (Adblock Plus 3.1 or higher required.)
match-case — определяет фильтр, который применяется только к адресам с совпадением букв, например фильтр */BannerAd.gif$match-case будет блокировать http://example.com/BannerAd.gif, но не http://example.com/bannerad.gif.
collapse — эта опция принудительно включает скрытие для данного элемента не смотря на значение глобальной настройки «Прятать метки на месте заблокированных элементов». Соответственно опция ~collapse выключает скрытие свободного места от данного элемента.
donottrack — для каждого адреса, который подходит под правило блокирования с этим параметром и не соответствует никаким исключающим правилам с этим параметром, Adblock Plus будет посылать заголовок Do-Not-Track (необходим Adblock Plus 1.3.5 или выше). Для обратной совместимости рекомендуется использовать этот параметр с противоречивыми параметрами типа. Это гарантирует, что в старых версиях Adblock Plus этот фильтр ничего не заблокирует: *$donottrack,image,~image
Rewrite the URL with the option rewrite=. You may want to create a regular expression filter to perform the rewrite operation. In that case, you can use $n in the rewrite argument, with n being a number between 1 and 100, to insert the n-th parenthesis submatch of the filter regular expression. Anything not explicitly matched by it will be added in the rewritten string. For example /(server\.com\/assets\/file.php)\?.*$/$rewrite=$1 will strip everything that comes after ".php" and redirects the request to the resulting URL. If there is no query string (i.e. no '?'), this filter won't match. The rewrite parameter has the same syntax as JavaScript’s String.prototype.replace(). The resulting URL must have the same origin; in case it is rewritten to a relative URL, the origin gets added back. Also, rewrite for scripts, subdocuments, objects, requests from within objects (like Flash) are not possible for security reason; even if explicitly stated by the filter. If both, a filter with/without $rewrite option matches, the behavior is undefined, i.e. the request might either be blocked or redirected. (Adblock Plus 3.2 or higher required.)
Использование регулярных выражений
Если желаете добиться большего контроля над тем, к чему ваши фильтры подходят, а к чему нет, то можете использовать регулярные выражения. Например, фильтр /banner\d+/ подойдёт к banner123 и banner321 , но не banners. Изучите документацию по регулярным выражениям и сможете составлять их сами.
Примечание: Для повышения производительности рекомендуется не использовать регулярные выражения, если этого можно избежать.
Скрытие элементов
Основные правила
Иногда вы будете встречать рекламу, которая не может быть заблокирована потому, что она была внедрена как текст в саму веб-страницу. Если вы посмотрите исходный код такой страницы, то найдёте нечто вроде этого:
<div class="textad">
Cheapest tofu, only here and now!
</div>
<div id="sponsorad">
Really cheap tofu, click here!
</div>
<textad>
Only here you get the best tofu!
</textad>
Для корректного отображения страницу необходимо полностью, а значит и реклама будет скачана и этого нельзя избежать. Всё, что тут можно сделать - скрыть то, что не желаете видеть. Для этого и применяются правила скрытие элементов.
Первый рекламный слоган выше находится внутри элемента DIV с классом «textad». Следующее правило скроет скроет именно такую комбинацию: ##.textad. Тут «##» является признаком правила скрытия, а остальное — селектором, определяющим скрываемый элемент. Скрывать элементы по их атрибуту ID можно аналогичным образом, ###sponsorad скроет второй слоган. Указывать имя самого элемента не обязательно, фильтр ##textad так же будет работать (* тоже не обязательна). Также можно скрывать элементы лишь по их имени. Например, {4} скроет третий рекламный слоган.
Расширение Element Hiding Helper поможет в выборе нужного элемента и написании соответствующего правила без изучения исходного кода страницы. Базовые знания в HTML желательны в любом случае.
Примечание: Правила скрытие кардинально отличается от обычных фильтров. Например, не поддерживаются привычные символы масок — они имеют другое значение и применение.
Ограничение правил определенными доменами
Обычно вы хотите скрыть определенную рекламу на определенном сайте и не хотите, чтобы это правило применялось на других сайтах. Например, правило ##.sponsor может скрыть полезный код на некоторых сайтах. Но если вы напишете его как example.com##.sponsor оно будет применено на http://example.com/ и http://something.example.com/ но не на http://example.org/. Вы также можете определить множество доменов - просто разделите их запятыми: domain1.example,domain2.example,domain3.example##.sponsor.
Если доменному имени предшествует "~", правило не будет применяться на страницах этого домена (требуется Adblock Plus 1.1 и выше). Например, ~example.com##.sponsor будет применяться на страницах с других доменов, "example.com" и example.com,~foo.example.com##.sponsor делает правило применимым к домену "example.com" с исключением поддомена "foo.example.com".
Примечание: Из-за способа, который применяется при скрытии элементов, вы можете использовать только полные доменные имена. Нельзя использовать другие части адресов и нельзя использовать domain как замену domain.example,domain.test.
Примечание: Правила скрытия элементов с ограничением доменов могут использоваться для скрытия элементов интерфейса браузера. Например, правило browser##menuitem#javascriptConsole скроет пункт Консоль JavaScript в меню Инструменты браузера Firefox.
Селекторы атрибутов
С некоторыми рекламными вставками справиться не так просто - их рекламный текст не имеет ни id, ни атрибута class. Вы можете использовать другие атрибуты для их скрытия, например ##table[width="80%"] будет скрывать таблицы атрибут width у которых установлен в 80%. Если вы не хотите определять полное значение атрибута, ##div[title*="adv"] будет скрывать все элементы div с атрибутом заголовка, содержащим строку "adv". Вы также можете проверять начало и конец атрибута, например ##div[title^="adv"][title$="ert"] будет скрывать элементы div начинающиеся с "adv" и заканчивающиеся "ert". Как видите, вы также можете использовать множество состояний — table[width="80%"][bgcolor="white"] будет подходить для таблиц с атрибутом width установленным в 80% и атрибутом bgcolor установленным в white.
Дополнительные селекторы
В принципе любой CSS селектор моно работающий в Firefox можно использовать для скрытия. Например следующее правило скроет всё, что вложено в элемент DIV с классом «adheader»: ##.adheader + *. Полный список CSS селекторов смотрите в спецификации CSS от W3C (учтите: на данный момент Firefox поддерживает ещё не все селекторы). Please keep in mind that browsers are slower to process these selectors than selectors based on class or id attribute only.
Примечание: Эта функция для продвинутых пользователей, необходимо свободное владение CSS селекторами, чтоб их корректно использовать. Adblock Plus не способен проверить синтаксис добавляемого селектора и если использовать неправильный синтаксис, то можно сломать другие (корректные) фильтры. Проверяйте консоль ошибок JavaScript на предмет сообщений об ошибках в CSS.
Extended CSS selectors (Adblock Plus specific)
Sometimes the standard CSS selectors aren't powerful enough to hide an advertisement. For those cases we have added some new selectors, namely :-abp-has(), :-abp-contains() and :-abp-properties() (requires Adblock Plus 1.13.3 or higher for Chrome and Opera).
When writing an element hiding filter that makes use of these extended selectors you must use the #?# syntax, e.g. example.com#?#selector. But it's important to note that doing so carries a performance impact, so do so sparingly and make sure those filters are specific to as few domains and elements as possible.
:-abp-properties()
:-abp-properties(properties) will select elements based upon stylesheet properties. For example :-abp-properties(width:300px;height:250px;) will select elements that have a corresponding CSS rule in a stylesheet which sets the width and height to the values 300px and 250px respectively. Property names are matched case-insensitively. Furthermore, wildcards can be used so that :-abp-properties(width:*px;height:250px;) will match any width specified in pixels and a height of 250 pixels.
You can also use regular expressions by surrounding the properties expression with "/". For example, :-abp-properties(/width:30[2-8]px;height:250px;/) will match widths between 302 and 308 pixels and a height of 250 pixels.
Note: The older syntax for the CSS property filters is deprecated and will be automatically converted to the new format . The syntax to select the style properties remain the same. For example, [-abp-properties='width:300px;height:250px;'] will be converted to :-abp-properties(width:300px;height:250px;).
:-abp-properties() will also select elements using the style properties found in their pseudo-elements, like ::before and ::after. For example, :-abp-properties(content:'Advertisment') will match elements where the string Advertisment is found in either their ::before or ::after pseudo element.
:-abp-has()
:-abp-has(selector) will select elements based on their content. For example :-abp-has(> div > a.advertiser) will select elements that contain as a direct descendant a <div> that contains an <a> with the class advertiser. The inner selector can be relative to the element scope, and can use any of the pseudo-selectors, including :-abp-has() and will determine whether the selection will occur.
:-abp-contains()
:-abp-contains(text) will select elements based on their text content. For example, div.sidebar > span:-abp-contains(Advertisment) will select the <span> elements within a <div>, with a class of sidebar that contains the word "Advertisment". In practice, you'd want to combine this with a :-abp-has() to select the outer container — something like div.sidebar > div:-abp-has(span:-abp-contains(Advertisment)) to select the container that would contain an advertisement label.
Исключения
Правила-исключения «выключают» отдельные правила блокировки и скрытия на определённых доменах. В основном они полезны авторам подписок, дополняющих сторонние подписки, которые они не могут изменить. Например, правило ##.textad можно выключить на example.com добавив исключение example.com#@#.textad. Комбинация этих двух правил идентична по эффекту одному правилу ~example.com##.textad. Применять такие исключения рекомендуется только в случае, когда изменить само правило скрытия не представляется возможным, во всех остальных случаях лучше изменить само правило. These exceptions will be applied to advanced pseudo-selector rules as well.
Generic / Specific filters
With the $generichide and $genericblock filter options the distinction between generic and specific filters becomes important.
We classify a filter to be specific if it matches one or more domains or matches a sitekey. If a filter has no domains specified (or only domain exceptions) and no sitekey then it counts as generic. For example, example.com##.textad is a specific filter, whereas both ##.textad and ~example.com##.textad are generic.
Note that with blocking rules the domain must be specified under the $domain option for them to be considered specific. For example, ||example.com^ is considered generic whereas */ads/*$domain=example.com is site-specific.
Implementing a sitekey on the server
For a sitekey-restricted filter to apply, a webpage needs to return base64-encoded versions of the public key and a signature which Adblock Plus can validate. Currently, this means including them in both the HTTP response header (X-Adblock-Key: abcdpublickeydcba_abcdsignaturedcba) and the root tag of the document (<html data-adblockkey="abcdpublickeydcba_abcdsignaturedcba">).
First you need to create a private RSA key (preferably 512 bit to keep the transfer volume low) and then a DER representation of the public key.
The data used for creating the signature is a concatenated list of request variables (namely URI, host and user agent) separated by the NUL character "\0". For example:
/index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:30.0) Gecko/20100101 Firefox/30.0
Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).