Créer des filtres Adblock Plus
Les versions actuelles d'Adblock Plus vous permettent de fabriquer vos propres filtres de plusieurs manières différentes. Ce document explique les possibilités qui sont à votre disposition et comment les utiliser.
Décharge de responsabilité : tous les exemples de filtres donnés ici ne sont vraiment que des exemples et ne sont pas destinés à être utilisés.
Introduction aux filtres Adblock Plus
Les options décrites dans cette rubrique devraient être suffisantes pour les utilisateurs ayant besoin de créer un filtre occasionnellement.
Règles de filtres basiques
Le filtre le plus trivial que vous puissiez créer est naturellement l'adresse de la publicité que vous souhaitez bloquer. Cependant, souvent cette adresse change lorsque vous affichez votre page. Cela pourrait être par exemple http://example.com/ads/banner123.gif
où 123 est un nombre aléatoire. Dans ce cas, bloquer cette adresse ne sera pas d'une grande utilité, vous devriez donc créer un filtre plus général — tel que http://example.com/ads/banner*.gif
, ou peut-être http://example.com/ads/*
seule.
Remarque : assurez-vous que vous ne remplacez pas trop de choses par des jokers (*). Le filtre http://example.com/*
bloquera toutes les publicités mais bloquera également toutes autres pages provenant de example.com que vous souhaiteriez peut-être tout de même voir.
Définition de règles d'exception
De temps à autres vous constaterez qu'un de vos filtres qui fonctionne habituellement correctement, bloque quelque chose qu'il ne devrait pas bloquer. Vous ne souhaitez pas supprimer ce filtre mais il ne devrait plus bloquer ce qu'il vient de bloquer.
Ce sont les règles d'exception (liste blanche) qui se chargent de cela — Elles vous permettent de définir des situations dans lesquelles les filtres ne devront pas être appliqués. Par exemple, si vous n'êtes pas satisfait de votre filtre adv
qui bloque http://example.com/advice.html
, vous pouvez créer une règle d'exception @@advice
. Les règles d'exception ne sont pas très différentes des filtres de publicités, vous pouvez utiliser des jokers (*) et des expressions régulières. Vous n'avez qu'à les faire débuter par @@
pour indiquer que ce sont des règles d'exception.
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.
Coïncidence avec le début/la fin d'une adresse
Normalement Adblock Plus traite chaque filtre comme s'il possédait un joker (*) au début et à la fin. Exemple : il n'y a aucune différence entre les filtres ad
et *ad*
. Ceci ne pose aucun problème en général, mais quelquefois vous souhaiteriez peut-être que le filtre que vous avez défini ne corresponde qu'au début ou qu'à la fin d'une adresse. Vous souhaitez, par exemple, bloquer toutes les animations Flash, mais si vous ajoutez le filtre swf
(extension des animations Flash) l'adresse http://example.com/swf/index.html
sera également bloquée.
La solution à ce problème : ajouter le symbole trait vertical (|) au filtre pour indiquer que c'est la fin de l'adresse qui devra correspondre au filtre pour être bloquée. Par exemple le filtre swf|
bloquera http://example.com/annoyingflash.swf
mais pas http://example.com/swf/index.html
. Et le filtre |http://mauvaisdomaine.exemple/
bloquera http://mauvaisdomaine.exemple/banner.gif
mais pas http://bondomaine.exemple/analyze?http://mauvaisdomaine.exemple
seule.
De temps à autre vous voudriez bloquer http://example.com/banner.gif
ainsi que https://example.com/banner.gif
et que http://www.example.com/banner.gif
. Cela peut se faire en plaçant deux traits verticaux devant le filtre qui vérifie si le filtre correspond au début du nom de domaine : ||example.com/banner.gif
bloquera toutes ces adresses mais pas celle-là : http://mauvaisexample.com/banniere.gif
ou http://bondomain.example/analyze?http://example.com/banniere.gif
(Adblock Plus 1.1 ou supérieur est nécessaire).
Marquage des caractères séparateurs
Souvent vous devez accepter des caractères séparateurs dans des filtres. Par exemple, vous pouvez créer un filtre qui bloque http://example.com/
et http://example.com:8000/
mais pas http://example.com.ar/
. Dans ce cas, le symbole ^ pourra être utilisé comme un remplaçant d'un caractère séparateur : http://example.com^
(Adblock Plus 1.1 ou supérieur est nécessaire).
Un caractère séparateur est tout sauf une lettre, un nombre ou un des caractères suivants : _ - . %. La fin d'une adresse est également acceptée comme étant un séparateur. Dans l'exemple suivant, tous les caractères séparateurs sont affichés en rouge : http://example.com:8000/foo.bar?a=12&b=%D1%82%D0%B5%D1%81%D1%82. Cette adresse pourra être bloquée par le filtre ^example.com^
ou ^%D1%82%D0%B5%D1%81%D1%82^
ou ^foo.bar^
seule.
Commentaires
Toute règle débutant par un point d'exclamation sera considérée comme étant un commentaire. Elle sera affichée dans la liste de filtres mais grisée au lieu d'être en noir. Adblock Plus ignorera cette règle pour le blocage, elle permet donc d'écrire ce que l'on veut. Vous pouvez ainsi placer un commentaire pour décrire la fonction de tels ou tels filtres. Vous pouvez également indiquer votre nom et la propriété de votre liste en haut de la liste de filtres (beaucoup d'auteurs de listes le font).
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.
Fonctionnalités avancées
Les fonctions décrites dans cette rubrique ne sont utilisées habituellement que par les utilisateurs confirmés et les créateurs de listes de filtres. Vous n'êtes donc pas obligé de lire cette rubrique.
Spécification des options de filtrage
Adblock Plus vous permet de spécifier un certain nombre d'options pour modifier le comportement d'un filtre. Vous devez lister ces options en les séparant par une virgule et en les faisant débuter par un dollar ($) à la fin du filtre. Exemple :
*/ads/*$script,match-case
Ici */ads/*
est le filtre et script
et match-case
sont ses options. Pour le moment, sont disponibles les options suivantes :
- Options de type : détermine quel type d'éléments le filtre peut bloquer (ou autoriser en cas de liste blanche). De nombreux types d'options peuvent être spécifiés pour indiquer que le filtre devra être appliqué à plusieurs types d'éléments. Les types possibles sont :
script
— scripts externes chargés via la balise HTML scriptimage
— images normales, chargées typiquement via la balise HTML imgstylesheet
— fichiers de feuille de style CSS externesobject
— contenu traité par des plugins du navigateur comme par exemple Flash ou Javaxmlhttprequest
— requests started using theXMLHttpRequest
object orfetch()
APIsubdocument
— pages incorporées (embedded), habituellement incluses via la balise HTML framesping
— requests started by<a ping>
ornavigator.sendBeacon()
(Adblock Plus 2.7.1 or higher required)websocket
— requests initiated viaWebSocket
object (Adblock Plus 2.8 or higher required)webrtc
— connections opened viaRTCPeerConnection
instances to ICE servers (Adblock Plus 1.13.3 for Chrome and Opera, 3.0 for Firefox, or higher required)document
— la page elle-même (uniquement les règles d'exception peuvent être appliquées à la page)elemhide
— uniquement pour les règles d'exception, comme pourdocument
mais ne désactive que les règles de masquage d'élément sur la page plutôt que toutes les règles de filtre (Adblock Plus 1.2 et supérieur nécessaire)generichide
— for exception rules only, similar toelemhide
but only disables generic element hiding rules on the page (Adblock Plus 2.6.12 or higher required)genericblock
— for exception rules only, just likegenerichide
but disables generic blocking rules (Adblock Plus 2.6.12 or higher required)popup
— pages opened in a new tab or windowother
— d'autres types de requêtes telles que liaisons XBL, requêtes http XML ou données demandées par des objets. Cela signifie : les types de requêtes non appréhéndées par la liste ci-dessus
background
,xbl
anddtd
are outdated and should no longer be used. - Options de type inverse : spécifie les types d'éléments auxquels le filtre ne doit pas être appliqué. Les options de type inverse possibles sont :
~script
,~image
,~stylesheet
,~object
,~xmlhttprequest
,~subdocument
,~document
,~elemhide
,~other
,{10}
- Restriction aux requêtes third-party/first-party (provenant d'un autre/du même site) : Si l'option
third-party
est spécifiée, le filtre n'est appliqué qu'aux requêtes provenant d'une autre origine que la page actuellement affichée. De manière similaire,~third-party
restreint l'action du filtre aux requêtes provenant de la même origine que la page couramment affichée. - Restrictions de domaines : l'option
domain=example.com
signifie que le filtre ne devra s'appliquer qu'aux pages provenant du domaine "example.com". Plusieurs domaines peuvent être spécifiés en utilisant "|" comme séparateur : avec l'optiondomain=example.com|example.net
le filtre ne s'appliquera qu'aux pages provenant des domaines "example.com" ou "example.net". Si un nom de domaine est précédé par "~", le filtre ne s'appliquera pas aux pages de ce domaine. Par exemple,domain=~example.com
signifie que le filtre devra s'appliquer à toutes les pages sauf celles provenant de "example.com" etdomain=example.com|~foo.example.com
restreint l'action du filtre au domaine "example.com" avec comme exception le sous-domaine "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 optionsitekey=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 ofscript-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 Policyscript-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
— fait en sorte que le filtre ne s'applique qu'aux adresses correspondant à la casse (prise en compte des minuscules et des majuscules), par exemple, le filtre*/BannerAd.gif$match-case
bloquerahttp://example.com/BannerAd.gif
mais pashttp://example.com/bannerad.gif
seule.
Utilisation d'expressions régulières
Si vous souhaitez davantage de précision de filtrage vous pouvez utiliser des expressions régulières. Par exemple, le filtre /banner\d+/
bloquera banner123
et banner321
mais pas banners
. Vous pouvez lire une documentation sur les expressions régulières pour apprendre à en créer.
Remarque : Pour des raisons de performances il est recommandé de ne pas utiliser d'expressions régulières tant que cela peut être évité.
Cacher des éléments
Règles basiques
Parfois vous trouverez des publicités impossible à bloquer car elles sont intégrées en tant que texte dans la page Web. Si vous affichez le code source de cette page, vous trouverez probablement quelque chose de ce style :
<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>
Vous devez charger la page Web, vous téléchargerez donc obligatoirement les publicités. Tout ce que vous pouvez encore faire, c'est de cacher la publicité pour ne pas la voir s'afficher. La fonctionnalité "Cacher les éléments" vous permettra de faire cela.
La première publicité dans l'exemple ci-dessus est contenue dans un élément div avec un attribut de classe "textad". Le filtre suivant cachera exactement cette combinaison : ##.textad
. Ici ## marque une règle de masquage d'élément alors que le reste est un sélecteur identifiant les éléments devant être masqués. Vous pouvez de la même manière cacher des éléments par leur attribut d'id, ###sponsorad
cachera la seconde publicité. Vous n'êtes pas obligé de spécifier le nom d'élément, le filtre ##textad
fonctionnera tout aussi bien. Sur le même principe, vous pouvez cacher des éléments par leur nom, par exemple {4}
pour la troisième publicité.
L'extension Element Hiding Helper extension aide à sélectionner le bon élément et à écrire la règle correspondante sans avoir à afficher le code source de la page. Des connaissances basiques en HTML sont tout de même utiles.
Remarque : cacher les éléments fonctionne totalement différemment par rapport aux filtres normaux. Ce qui implique que les jokers ne peuvent être utilisés dans ce genre de filtres.
Limitation des règles à certains domaines
En général vous souhaitez cacher une publicité spécifique sur un site spécifique, vous ne souhaitez pas appliquer le filtre à d'autres sites. Par exemple le filtre ##.sponsor
pourrait cacher des codes valides sur certains sites. Mais si vous écrivez example.com##.sponsor
il sera appliqué aux sites http://example.com/
et http://something.example.com/
mais pas à http://example.org/
. Vous pouvez également spécifier plusieurs domaines — séparez-les simplement par des virgules : domain1.example,domain2.example,domain3.example##.sponsor
seule.
Si un nom de domaine est précédé par un "~", la règle ne sera pas appliquée pour les pages de ce domaine (Adblock Plus 1.1 ou supérieur est nécessaire). Par exemple, ~example.com##.sponsor
sera appliqué à toutes les pages de tout domaine sauf "example.com" et example.com,~foo.example.com##.sponsor
fera appliquer la règle sur le domaine "example.com" avec comme exception le sous-domaine "foo.example.com".
Remarque : A cause de la manière avec laquelle "cacher les éléments" est implémentée, vous ne pouvez que vous limiter à des noms de domaines complets. Vous ne pouvez utiliser une autre partie de l'adresse et vous ne pouvez pas utiliser domain
afin de remplacer domain.example,domain.test
seule.
Remarque : Les règles pour cacher des éléments en limitant par domaine peuvent également être utilisées pour cacher des éléments de l'interface utilisateur. Exemple : le filtre browser##menuitem#javascriptConsole
cachera l'entrée "Console javascript" dans le menu "Outils" de Firefox.
Sélecteurs d'attribut
Certains publicitaires ne vous facilitent pas la tâche — leur texte publicitaire ne comporte ni un attribut classe, ni un attribut id. Dans ce cas, vous pouvez utiliser d'autres attributs pour cacher les publicités, par exemple ##table[width="80%"]
cachera les tableaux ayant un attribut width (largeur) de 80%. Si vous ne souhaitez pas spécifier la valeur entière de l'attribut, ##div[title*="adv"]
cachera tous les éléments div avec un attribut title (titre) contenant la suite de caractères "adv". Vous pouvez également vérifier le début et la fin d'un attribut, par exemple ##div[title^="adv"][title$="ert"]
cachera les éléments div dont l'attribut title commence par "adv" et se termine par "ert". Comme vous le constatez, vous pouvez également utiliser plusieurs conditions — table[width="80%"][bgcolor="white"]
correspondra aux tableaux dont l'attribut width est fixé à 80% et l'attribut bgcolor défini à white (couleur blanche).
Sélecteurs avancés
En général, tout sélecteur CSS pris en charge par Firefox pourra être utilisé pour le masquage d'élément. Par exemple la règle suivante masquera tout ce qui suit un élément div avec pour classe "adheader": ##.adheader + *
. Pour obtenir une liste complète CSS rendez-vous sur la page de la spécification W3C CSS (veuillez prendre note que tous les sélecteurs ne sont pas encore pris en charge par Firefox). Please keep in mind that browsers are slower to process these selectors than selectors based on class
or id
attribute only.
Remarque: Cette fonctionnalité n'est prévue que pour les utilisateurs chevronnés, il faut que vous soyez à l'aise avec les sélecteurs CSS pour l'utiliser. Adblock Plus ne pourra pas vérifier la syntaxe du sélecteur que vous ajoutez, si vous utilisez une syntaxe CSS invalide vous risquez d'endommager d'autres règles (valides) que vous avez. Vérifiez la console Javascript pour détecter d'éventuelles erreurs 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.
Règles d'exception
Les règles d'exception permettent de désactiver un filtre existant sur certains domaines. Cela est surtout utile pour les gestionnaires de listes complémentaires qui viennent étendre l'action de listes de filtres qu'ils ne peuvent modifier. Par exemple, le filtre ##.textad
peut être désactivé sur example.com
grâce à la règle d'exception example.com#@#.textad
seule. La combinaison de ces deux règles a exactement le même effet que la règle ~example.com##.textad
seule. L'utilisation des règles d'exception est recommandée uniquement lorsque vous ne pouvez pas modifier une règle de masquage d'élément prédominante ; il est sinon préférable de limiter cette règle aux domaines qui le nécessite.
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).