Het schrijven van Adblock Plus filters
De huidige Adblock Plus versies laten u filters op veel verschillende manieren verfijnen. Dit document legt de keuzes die u heeft uit en vertelt hoe ze gebruikt kunnen worden.
Disclaimer: Alle filtervoorbeelden die hier gegeven worden zijn alleen maar voorbeelden en zijn niet bedoeld om gebruikt te worden.
Introductie op Adblock Plus filters
De opties die in dit deel beschreven zijn zouden genoeg moeten zijn voor gebruikers die af en toe een filter maken.
Standaard filterregels
De meest triviale filter die u kunt definieren is natuurlijk het adres van een banner die u wilt blokkeren. Dit adres wijzigt echter vaak elke keer als u een pagina opent. Het kan bijvoorbeeld http://example.com/ads/banner123.gif
zijn, waarbij 123 een willekeurig getal is. Hier helpt het u niet om het volledige adres te blokkeren, dus u moet een meer generiek filter maken — zoals http://example.com/ads/banner*.gif
. Of misschien zelfs http://example.com/ads/*
.
N.B.: Let er op dat u niet teveel door wildcards vervangt. Het filter http://example.com/*
zal zeker alle banners blokkeren, maar het blokkeert ook al het andere van example.com wat u misschien toch zou willen zien.
Het definieren van uitzonderingsregels
Soms merkt u dat een van uw filters die meestal eigenlijk behoorlijk goed blokkeert in sommige gevallen iets blokkeert wat niet geblokkeerd moet worden. U wilt dit filter niet verwijderen, maar u wilt dat het toch niet matcht in dit ene geval.
Daarvoor kunt u uitzonderingsregels gebruiken — zij laten u gevallen definieren waarop het filter niet toegepast moet worden. Als u bijvoorbeeld niet wilt dat uw filter adv
de pagina http://example.com/advice.html
blokkeert, kunt u een uitzonderingsregel @@advice
definieren. Uitzonderingsregels zijn niet anders dan filterregels, u kunt wildcards of reguliere expressies gebruiken. U moet ze alleen laten voorafgaan door @@
om aan te geven dat het om een uitzonderingsregel gaat.
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.
Overeenkomen op het begin/aan het eind van een adres
Normaal gesproken behandelt Adblock Plus elk filter alsof er wildcards voor en achter zouden staan, er is bijvoorbeeld geen verschil tussen de filters ad
en *ad*
Hoewel dit meestal geen probleem oplevert, wilt u soms dat het filter dat u definieert alleen overeenkomt met het begin of het eind van een adres. U wilt bijvoorbeeld alle Flash blokkeren, maar als u het filter swf
toevoegt, dan wordt het adres http://example.com/swf/index.html
ook geblokkeerd.
De oplossing van dit probleem is: voeg een pipe symbool aan het filter toe om te laten zien dat er op deze positie echt een eind aan het adres moet zijn. Bijvoorbeeld het filter swf|
blokkeert http://example.com/annoyingflash.swf
maar niet met http://example.com/swf/index.html
. En het filter |http://baddomain.example/
blokkeert http://baddomain.example/banner.gif
maar niet met http://gooddomain.example/analyze?http://baddomain.example
.
Soms wilt u zowel http://example.com/banner.gif
als https://example.com/banner.gif
en http://www.example.com/banner.gif
blokkeren. U kunt dit doen door twee pipe sumbolen voor het filter te zetten, wat er voor zorgt dat het filter het begin van de domeinnaam matcht: ||example.com/banner.gif
zal al deze adressen blokkeren, terwijl het niet http://badexample.com/banner.gif
of http://gooddomain.example/analyze?http://example.com/banner.gif
(is afhankelijk van Adblock Plus 1.1 of hoger).
Het markeren van scheidingstekens
Vaak moet u elk scheidingsteken in een filter toestaan. U schrijft bijvoorbeeld een filter dat http://example.com/
en http://example.com:8000/
maar niet met http://example.com.ar/
. Hier kan het symbool ^ gebruikt worden als aanduiding voor een enkel scheidingsteken: http://example.com^
(is afhankelijk van Adblock Plus 1.1 of hoger).
Een scheidingsteken is alles behalve een letter, cijfer of een van de volgende karakters: _ - . %. Het eind van een adres wordt ook als scheiding geaccepteerd. In het volgende voorbeeld worden alle scheidingstekens in rood getoond: http://example.com:8000/foo.bar?a=12&b=%D1%82%D0%B5%D1%81%D1%82. Dit adres kan dus geblokkeerd worden met het filter ^example.com^
of ^%D1%82%D0%B5%D1%81%D1%82^
of ^foo.bar^
.
Opmerkingen
Elke regel die met een uitroepteken begint wordt als commentaar gezien. Het wordt in de filterlijst getoond, maar grijs in plaats van zwart. Adblock Plus zal deze regel negeren bij het blokkeren, dus u kunt hier veilig schrijven wat u maar wilt. U kunt een commentaarregel boven elk filter zetten om te beschrijven wat het filter doet. Of u zet een commentaar bovenaan de filterlijst waarin u uw auteursrecht vermeldt (de meeste makers van filterlijsten doen dit).
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.
Geavanceerde functies
De functies die in deze sectie beschreven worden, worden normaal gesproken alleen door gevorderde gebruikers en makers van filterlijsten gebruikt. Sla het gerust over.
Het opgeven van filteropties
Adblock Plus maakt het mogelijk om een aantal opties op te geven om het gedrag van een filter te wijzigen. Je geeft deze opties gescheiden met comma's aan achter een dollar teken ($) aan het eind van een filter, bijvoorbeeld:
*/ads/*$script,match-case
Hier is */ads/*
het feitelijke filter en zijn script
en match-case
zijn opties. Op dit moment worden de volgende opties ondersteund:
- Type opties: deze bepalen welke types elementen door een filter geblokkeerd moeren worden (of worden doorgelaten in het geval van een uitzonderingsregel). Meerdere type opties kunnen worden opgegeven om aan te geven dat het filter moet worden toegepast op meerdere types elementen. Mogelijke types zijn:
script
— externe scripts geladen via een HTML script labelimage
— standaard afbeeldingen, doorgaans geladen via een HTML img labelstylesheet
— externe CSS stylesheet bestandenobject
— inhoud die door browser plugins, zoals Flash of Java, wordt afgehandeldxmlhttprequest
— requests started using theXMLHttpRequest
object orfetch()
APIsubdocument
— ingebedde pagina's, meestal opgegeven via 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
— de pagina zelf (alleen uitzonderingsregels kunnen op de pagina worden toegepast)elemhide
— alleen voor uitzonderingsregels, vergelijkbaar metdocument
maar dit schakelt alleen element verbergingsregels op de pagina uit, in plaats van alle filterregels (afhankelijk van Adblock Plus 1.2 of hoger)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
— verzoek types die niet door de bovenstaande lijst worden afgevangen
background
,xbl
anddtd
are outdated and should no longer be used. - Omgekeerde type opties: geef de types elementen op waarop het filter niet moet worden toegepast. Mogelijke omgekeerde types:
~script
,~image
,~stylesheet
,~object
,~xmlhttprequest
,~subdocument
,~document
,~elemhide
,~other
,{10}
- Beperken tot derde-partij/eerste-partij verzoeken: Als de
third-party
optie is opgegeven, wordt het filter alleen toegepast op verzoeken van een andere bron dan de huidige weergegeven pagina. Op dezelfde manier beperkt~third-party
filters tot verzoeken van dezelfde bron als de huidige weergegeven pagina. - Domein restricties: De optie
domain=example.com
betekent dat het filter allen moet worden toegepast op pagina's van het "example.com" domein. Er kunnen meerder domeinen worden opgegeven gescheiden door "|" als scheidingsteken: met de optiedomain=example.com|example.net
wordt het filter alleen toegepast op pagina's van "example.com" en "example.net" domeinen. Als een domeinnaam voorafgegaan wordt door "~" moet het filter niet worden toegepast op pagina's van dit domein. Bijvoorbeelddomain=~example.com
betekent dat het filter op pagina's van alle domeinen op "example.com" na endomain=example.com|~foo.example.com
beperkt het filter tot het "example.com" domein met uitzondering van het "foo.example.com" subdomein. -
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
— zorgt ervoor dat het filter alleen van toepassing is bij dezelfde hoofdlettergevoeligheid, bijvoorbeeld*/BannerAd.gif$match-case
blokkeerthttp://example.com/BannerAd.gif
maar niet methttp://example.com/bannerad.gif
.
Het gebruik van reguliere expressies
Als je nog meer controle wilt hebben over wat er overeenkomt met je filter en wat niet, kan je reguliere expressies gebruiken. Bijvoorbeeld het filter /banner\d+/
zal overeenkomen met banner123
en banner321
maar niet met banners
. U kunt documentatie over reguliere expressies raadplegen om te leren hoe u deze moet schrijven.
N.B.: Om de prestatie te bevorderen is het aanbevolen om geen reguliere expressies te gebruiken als dit voorkomen kan worden.
Het verbergen van elementen
Standaard regels
Soms zal je reclames vinden die niet geblokkeerd kunnen worden omdat ze als tekst in de pagina zelf zijn ingebed. Als je naar de broncode van de webpagina kijkt, kan je iets vinden zoals dit:
<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>
U moet de webpagina downloaden, dus u download de reclame vanzelf ook. Het enige wat u hier kunt doen is de reclame verbergen, zodat u hem niet ziet. Daar is element verbergen voor bedoeld.
De eerste reclame hierboven staat in een div element met class attribuut "textad". De volgende regel zal precies deze combinatie verbergen: ##.textad
. Hier markeert ## een element verbergende regel terwijl de rest het element wat verborgen moet worden aangeeft. U kunt elementen op dezelfde manier aan de hand van hun id attribuut verbergen, ###sponsorad
zal de tweede reclame verbergen. U hoeft geen elementnaam op te geven, de regel ##textad
werkt net zo goed. En u kunt ook elementen verbergen aan de hand van alleen hun naam, bijvoorbeeld {4}
voor de derde reclame.
De Element Hiding Helper extensie helpt om het juiste element te selecteren en om een overeenkomstige regel te schrijven zonder dat je de broncode van de pagina hoeft te bekijken. Standaard HTML kennis is echter toch nuttig.
N.B.Het verbergen van elementen werkt heel anders dan gewone filters. Dit heeft tot gevolg dar er geen wildcards worden ondersteund bij element verbergende regels.
Regels beperken tot bepaalde domeinen
Meestal wil je een bepaalde advertentie op een bepaalde site verbergen, u wilt niet dat de regel op andere sites van toepassing is. Bijvoorbeeld de regel ##.sponsor
zou geldige code op sommige sites kunnen verbergen. Maar als u het schrijft als example.com##.sponsor
wordt het toegepast op http://example.com/
en http://something.example.com/
maar niet op http://example.org/
. U kunt ook meerdere domeinen opgeven — scheidt ze simpelweg met comma's:domain1.example,domain2.example,domain3.example##.sponsor
.
Als een domein wordt voorafgegaan door "~", zal de regel niet worden toegepast op pagina's van dit domein (is afhankelijk van Adblock Plus 1.1 of hoger). Bijvoorbeeld ~example.com##.sponsor
zal worden toegepast op pagina's van elk domein behalve "example.com" en example.com,~foo.example.com##.sponsor
zorgt er voor dat de regel van toepassing is op het "example.com" domein met uitzondering van het "foo.example.com" subdomein.
N.B.: Door de manier waarop element verbergen is geïmplementeerd kunt u het eigenlijk alleen beperken tot volledige domeinnamen. U kunt niet een deel van een adres gebruiken en u kunt niet domain
gebruiken voor het vervangen van domain.example,domain.test
.
N.B.: Element verbergende regels met domein beperking kunnen ook worden gebruikt om elementen van de browser's gebruikersinterface te verbergen. Bijvoorbeeld de filterregelbrowser##menuitem#javascriptConsole
zal de Javascript foutconsole regel in Firefox' extra menu verbergen.
Attribuut selectors
Sommige adverteerders maken het je niet makkelijk p-- hun tekstadvertenties hebben noch een id noch een class attribuut. U kunt andere attributen gebruiken om deze te verbergen, bijvoorbeeld ##table[width="80%"]
zal tabellen verbergen met een width attribuut ingesteld op 80%. Als je geen waarde van het attribuut wilt opgeven, zal ##div[title*="adv"]
alle div elementen met een title attribuut dat de string "adv" bevat verbergen. U kunt ook het begin en het eind van een attribuut controleren, bijvoorbeeld ##div[title^="adv"][title$="ert"]
zal div elementen verbergen met title beginend met "adv" en eindigend op "ert". Zoals je ziet kan je ook meerdere condities gebruiken — table[width="80%"][bgcolor="white"]
zal overeenkomen met tabellen met width attribuut ingesteld op 80% eb bgcolor attribuut ingesteld op white.
Geavanceerde selectors
Normaal gesproken kan elke CSS selector die door Firefox wordt ondersteund gebruikt worden voor het verbergen van elementen. De volgende regel verbergt bijvoorbeeld alles wat op een div element met class "adheader" volgt: ##.adheader + *
. Kijk voor een volledige lijst van CSS op W3C CSS specificatie (let er op dat nog niet alle selectors door Firefox ondersteund worden). Please keep in mind that browsers are slower to process these selectors than selectors based on class
or id
attribute only.
N.B.: Deze functionaliteit is alleen voor gevorderde gebruikers, u moet goed met CSS selectors overweg kunnen om het te gebruiken. Adblock Plus is niet in staat om de syntax van een selector die u toevoegt te controleren, als je ongeldige CSS syntax gebruikt, kunt u andere (geldige) regels die u heeft stuk maken. Controleer de JavaScript console op CSS foutmeldingen.
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.
Uitzonderingsregels
Uitzonderingsregels kunnen bestaande regels uitschakelen op bepaalde domeinen. Deze zijn voornamelijk handig voor auteurs van filterabonnementen die een ander filterabonnement uitbreiden en die ze niet kunnen wijzigen. Bijvoorbeeld, de regel ##.textad
kan worden uitgeschakeld op example.com
door middel van de uitzonderingsregel example.com#@#.textad
. De combinatie van deze twee regels heeft precies hetzelfde effect als de enkelvoudige regel ~example.com##.textad
. Het wordt aanbevolen om alleen uitzonderingsregels te gebruiken als je een te algemene elementverbergende regel
niet kan aanpassen, in alle andere gevallen heeft het de voorkeur om deze regel te beperken tot de benodigde domeinen.
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).