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. They can set a number of parameters for 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:

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: ##div.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, ##div#sponsorad zal de tweede reclame verbergen. U hoeft geen elementnaam op te geven, de regel ##*#sponsorad werkt net zo goed. En u kunt ook elementen verbergen aan de hand van alleen hun naam, bijvoorbeeld ##textad 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: ##div.adheader + *. Kijk voor een volledige lijst van CSS op W3C CSS specificatie (let er op dat nog niet alle selectors door Firefox ondersteund worden).

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.

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 ##div.textad kan worden uitgeschakeld op example.com door middel van de uitzonderingsregel example.com#@#div.textad. De combinatie van deze twee regels heeft precies hetzelfde effect als de enkelvoudige regel ~example.com##div.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.

Vereenvoudigde element verbergende syntax

Adblock Plus ondersteunt vereenvoudigde element verbergende syntax (bijvoorbeeld #div(id=foo)) alleen om compatbel te zijn met oudere versies. Het gebruik van deze syntax wordt afgeraden, meestal zijn CSS selectors aanbevolen. Ondersteuning voor deze syntax kan op een bepaald moment worden verwijderd.

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##div.textad is a specific filter, whereas both ##div.textad and ~example.com##div.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).