Snippet filters tutorial

This guide is aimed at filter authors and advanced users that want to make the most out of Adblock Plus. It's a companion to the guide on writing filters that covers snippet filters. While it's recommended that you be familiar with writing filters, you should be OK otherwise. You don't need a deep knowledge of JavaScript, but you need to be familiar with it, as well as with web technologies like HTML, CSS, and the DOM. If you really want, Mozilla has a great resource to learn JavaScript, HTML and CSS.

This guide doesn't cover how to write an actual snippet, i.e. the JavaScript code that is loaded by Adblock Plus into the browser when you execute a snippet filter. This requires modifying the extension, and it will be covered in an upcoming developer guide.

Table of contents

• What are snippet filters?
• Syntax
• Arguments
• Examples
• Debugging
• Performance
• Behavioral Snippets
• Conditional Hiding Snippets
• How to access shadow DOM elements
• JSONPath evaluator

What are snippet filters?

Snippet filters are a new type of filter introduced in Adblock Plus 3.3 that allows running specialized code snippets (written in JavaScript) on pages within a list of specified domains. These snippets are selected from an existing library available in Adblock Plus.

The snippet approach allows interfering with ad display code in a more efficient manner, and also allows locating elements to hide in a way that can't be expressed with CSS or the current advanced selectors.

For security reasons, snippet filters can only be added to a user's custom filters list or in the ABP Anti-Circumvention Filter List, the latter being vetted and reviewed.

Syntax

The basic syntax of a snippet filter is as follows:

You can run several snippets in the same filter by separating them with a ;. See example 6.

Arguments

Arguments are strings. They can be surrounded by single quotes (') if they contain spaces. To have a single quote ' as part of the argument, escape it like this: \' ; you can also escape spaces with \ instead of quoting the argument. See examples 3a, 3b and 3c.

You can input Unicode characters by using the syntax \uNNNN, where NNNN is the Unicode codepoint. See example 4.

You can also input carriage return, line feed, and tabs using \r, \n, and \t, respectively. To have a \ in an argument, including a regular expression, it must be escaped with \, i.e. doubled up. See example 5.

Examples

Basic snippet filter syntax

These examples demonstrate the syntax of a snippet filter and how to pass arguments. While we mostly use the log snippet, these examples apply to other snippet functions as well.

Example 1

example.com#$#log Hello

This prints “Hello” in the web console on the domain example.com and its subdomains.

Example 2

anotherexample.com,example.com#$#log Hello

Same as example 1, but “Hello” also appears on the domain anotherexample.com. Like with other filter types, multiple domains should be separated by commas ,.

This filter makes the filter in example 1 obsolete. Having both filters makes the message appear twice on example.com, as both would be run.

Example 3a

example.net,example.com#$#log 'Hello from an example to another example'

This is a different message from example 2. Because it contains spaces, the string must be surrounded with single quotes '.

Example 3b

example.net,example.com#$#log 'Hello it\'s me again'

This shows the escape sequence for having a single quote, using \'.

Example 3c

example.net,example.com#$#log Hello\ no\ quotes

You can also escape spaces instead of quoting the argument, using \.

Example 4

emoji.example.com#$#log \u1F601

On the domain emoji.example.com, the emoji 😀 is printed in the console. The filter will not be run on example.com or www.example.com. This shows how to use escape for Unicode symbols.

Example 5

emoji.example.com#$#log '\u1F601\nand a new line'

This is similar to example 4, except that the filter prints the emoji 😀 and then on a new line, prints and a new line. This shows how to use escape for Unicode symbols, as well as adding a new line.

Example 6

Running two snippets:

debug.example.com#$#debug; log 'This should be prefixed by DEBUG'

First, we see debug. This is the snippet that enables debugging. It's just like any other snippet. Then we see log, whose output is modified when debugging is enabled. See the section on debugging for more details.

example.com#$#log 'Always log'; log 'And better twice than once'

This is another example of logging two lines. Here the snippet command will be called twice.

Debugging

We saw a debug snippet in Example 6. Its use is simple: calling debug before a snippet turns on the debug flag. If the other snippets support it, they'll enable their debug mode. What a snippet does in debug mode is up to the snippet.

debug

Since: Adblock Plus 3.8

Enables the debug mode for all the snippets that come after the debug snippet in the filter's snippets chain.

log

Since: Adblock Plus 3.3

Logs its arguments to the console. This may be used for testing and debugging.

profile

Since: Adblock Plus 4.8

It executes using the Performance API. It marks specific points (the beginning and the end in the main logic of every snippet) and measures the time taken between these points (duration).

The duration is expressed in ms.

It logs an object with the performance data of the monitored snippet.

trace

Since: Adblock Plus 3.3

Similar to log, but does the logging in the context of the document rather than the content script.

This may be used for testing and debugging, especially to verify that the injection of snippets into the document is working without any errors.

Performance

Snippet that aim to reduce the performance overhead caused by using other snippets.

race

“racing” mechanism among snippets that can easily compete against each other:

• snippets based on the same environment (in this case, the isolated world)
• snippets able to signal a winning strategy, but also able to stop executing.

Behavioral Snippets

Snippets that change the normal execution behavior of the page.

abort-current-inline-script

Since: Adblock Plus 3.4.3

Aborts the execution of an inline script when a property is either read or written.

abort-on-property-read

Since: Adblock Plus 3.4.1

Patches a property on the window object to abort execution when the property is read.

No error is printed to the console.

The idea originates from .

abort-on-property-write

Since: Adblock Plus 3.4.3

Patches a property on the window object to abort execution when the property is written.

No error is printed to the console.

The idea originates from .

abort-on-iframe-property-read

Since: Adblock Plus 3.10.1

Patches a list of properties on the iframes' window object to abort execution when the property is read.

No error is printed to the console.

abort-on-iframe-property-write

Since: Adblock Plus 3.10.1

Patches a list of properties on the iframes' window object to abort execution when the property is written.

No error is printed to the console.

array-override

Since: Adblock Plus 4.8

Overrides functions under Array.prototype to change their behaviour according to the given parameters.

blob-override

Since: Adblock Plus 4.22.2

Overrides specific parts of the Blob injected in web-pages. We override the blob constructor in a way we can intercept calls and change the blob content.

cookie-remover

Since: Adblock Plus 3.11.2

A snippet to remove certain cookies.

event-override

Since: Adblock Plus 4.22.2

Proxies events and event handlers to defuse events or change their attributes. It works with the principle of proxying addEventListener function and the original Event class with a CustomEvent class that we control. This way we can defuse/change any arbitrary event or create new ones.

freeze-element

Since: Adblock Plus 3.10

Freezes a DOM element so it prevents adding new nodes inside it.

json-override

Since: Adblock Plus 3.11.2

It's very similar to json-prune, but instead of removing a property, we override it with a value from the same list as for override-property-read.

It wraps both JSON.parse and Response.prototype.json, so a payload read with await response.json() is covered too.

Possible values

The value argument accepts the same list as override-property-read:

json-prune

Since: Adblock Plus 3.9.0

Traps calls to JSON.parse, and if the result of the parsing is an Object, it will remove specified properties from the result before returning to the caller.

It wraps both JSON.parse and Response.prototype.json, so a payload read with await response.json() is covered too.

The idea originates from uBlock Origin.

map-override

Since: Adblock Plus 4.24.0

Overrides functions under Map.prototype to change their behaviour according to the given parameters.

override-property-read

Since: Adblock Plus 3.9.4

Overrides a property's value on the window object with a set of available properties.

The idea originates from .

prevent-listener

Since: Adblock Plus 3.11.2

Prevents adding event listeners.

Wrap EventTarget.prototype.addEventListener and don't allow adding listeners for certain types of events.

replace-fetch-response

Since: Adblock Plus 4.4

Replaces the response of a fetch request if the response text matches a given regular expression pattern.

replace-outbound-value

Since: Adblock Plus 4.26.0

Overrides return values of functions or attributes according to the given parameters.

replace-xhr-response

Since: Adblock Plus 4.4

Replaces the response of a XHR request if the response text matches a given regular expression pattern.

prevent-element-src-loading

Since: Adblock Plus 4.35.1

Prevents targeted elements (script, img, iframe, link) from loading specific resources by intercepting src/href assignments and redirecting them to local mock data. It also neutralizes onerror handlers and error event listeners to ensure the loading fails silently without triggering errors/walls.

timer-override

Since: Adblock Plus 4.36

Changes the behaviour of setTimeout and setInterval calls on a page. It can make timers fire sooner or much later than intended, or disable the callback entirely.

replace-xhr-request

Since: Adblock Plus 4.36

Intercepts and modifies outgoing XHR request bodies before they reach the server.

simulate-mouse-event

Since: Adblock Plus 3.17

Triggers arbitrary mouse events on elements that are matched by a CSS or Xpath selector, by calling dispatchEvent for a selector.

Optional parameters are added to the selectors with a $ sign. Multiple parameters can be combined for a single selector by separating them with a comma. If a parameter is not specified, the default value will be assumed for that selector.

As you can see the you can mix and match the parameters to create the filter that best suits the case. The parameters doesn't have any order $delay=100,trigger is the same as $trigger,delay=100.

skip-video

Since: Adblock Plus 3.21

Makes the video skip to its end or fast forwards it with the given amount. It does it by setting the currentTime attribute of the video object.

strip-fetch-query-parameter

Since: Adblock Plus 3.5.1

Strips a query string parameter from fetch() calls.

prevent-window-open

Since: Adblock Plus 4.43.1

Prevents window.open calls whose arguments match a pattern, optionally returning a decoy pop-up handle so the page cannot detect the block by inspecting the returned window. Non-matching calls pass through to the native window.open. The wrapper preserves the native property descriptor and toString() output.

replace-argument

Since: Adblock Plus 4.42.0

Wraps a native method and rewrites one of its call arguments before the method runs. On each call the first rule that actually changes the argument wins, and the original method is always invoked.

replace-fetch-request

Since: Adblock Plus 4.43.2

Replaces the request body of fetch() calls before they are sent, if the body matches a given string. The fetch counterpart of replace-xhr-request. Only string bodies are rewritten; FormData, Blob, URLSearchParams and ArrayBuffer pass through untouched.

Conditional Hiding Snippets

Snippets that are responsible for hiding page content based on various conditions like matching text, style, machine learning model, etc.

hide-if-canvas-contains

Since: Adblock Plus 4.7

The hide-if-canvas-contains snippet hides a canvas element, or a parent element specified by the selector parameter, if the canvas contains the specified search term in it.

We override the fillText, strokeText, and drawImage canvas methods. When a website uses these functions, it won't use the native functions but instead use our overridden proxies. This allows us to know when a website writes text we are interested in (Sponsored, Advertised etc.) to the <canvas>, or loads an image whose source matches a specified pattern, and hide the ad.

clearRectBehavior

Sites often clear their canvas before drawing new content, using clearRect. This parameter controls whether that resets the text accumulated so far.

When more than one filter targets the same canvas, these values are aggregated rather than applied independently: if any active filter uses always, text is forgotten on every clearRect, and text is only never forgotten when all of them specify never.

hide-if-contains

Since: Adblock Plus 3.3

Hides any HTML element or one of its ancestors matching a CSS selector if the text content of the element contains a given string.

hide-if-contains-image

Since: Adblock Plus 3.4.2

Hides any HTML element or one of its ancestors matching a CSS selector if the background image of the element matches a given pattern.

（本文超出站点单文档体积上限，已截断）