Snippets Overview

Snippets Overview

On this page, you'll learn what snippets are, why they're useful, and ways you can include them in your development workflow.

Snippet basics

A snippet is a small piece of code intended to solve one problem:

function greetings() {
  print("Hello there!");
}

eyeo uses snippets to fight ad-filtering circumvention. The following is the first snippet ever written for Adblock Plus:

function log(...args)
{
  console.log(...args);
}

This snippet prints its arguments to the developer tools console for the tab on which it's executed.

The eyeo snippets library contains dozens of snippets to hide elements, find text, or block malicious code. Each snippet is exposed to the SDK that integrates the snippets library. As a result, you can use filters to execute snippets for a given page.

Snippet filter structure

A snippet filter contains several parts:

• a domain

• the snippet marker

• a function name

• parameters

Consider the following example, which prints Hello, world! to the console:

example.com#$#log Hello ', world' 

In this snippet, example.com is the domain, #$# is the snippet marker, and log is the function. The snippet takes two parameters, Hello and , world, both separated by white space.

Escaping in parameters

Parameters are tokenised before the snippet receives them, and the tokeniser consumes both backslashes and single quotes.

• Backslashes. Only \n, \r, \t and \uXXXX are recognised escapes. For anything else the backslash is dropped and the character is kept, so \s arrives as a literal s. Inside a /regex/ parameter, double every backslash — \\s arrives as \s. Character classes such as [.] and [?] work for punctuation, but cannot express \s, \d or \b. In a literal parameter, write the text plainly: it is escaped for you, so a[.]b would match the characters a[.]b.

• Single quotes. A ' toggles quoting and is always stripped — as in the ', world' parameter above, which reaches the snippet as , world. It is not a delimiter, so a quote that has to survive into the parameter must be written \'.

How snippets work

The way a snippet works depends on if the snippet is injected or isolated.

Injected and isolated snippets

• Injected JavaScript snippets are inserted into a page and interrupt, modify, terminate, or otherwise change the behavior of other JavaScript functions.

• An isolated snippet, on the other hand, has access to, reads, and manipulates the DOM.

Injected snippets are executed as inline scripts, whereas isolated snippets are executed as content scripts.

Types of snippets

• Behavioral Snippets — change a page's normal execution behavior

• Conditional Hiding Snippets — hide page content based on conditions like matching text, style, image hash

• Debugging Snippets — used in debugging tasks

• Performance snippets — reduce the performance overhead caused by other snippets

Working with snippets

Invoking snippets

Invoking a snippet requires two steps:

1. Write a snippet filter.

2. Deploy the filter to the ABP anti-circumvention filter list.

You can test the snippet filter on Adblock Plus or Adblock by adding the filter to the My filter list field on the extension's settings page.

Combining snippets on a single website

Like Unix commands, multiple snippets may be combined in a filter:

example.com#$#abort-on-property-read Object.prototype.loadImage; hide-if-contains-visible-text 'Sponsored'; prevent-listener beforeunload ();

Where you can use snippets

eyeo supports snippets on the following platforms:

• Web Extensions on Manifest V2 (WebRequest and Background Pages)

• Web Extensions on Manifest V3 (Declarative NetRequest and Service Workers)

• Chromium based browsers (on Desktop and Android)

• Apple WebKit (on iOS, but potentially also on Mac OS)

Not all snippets are supported on all platforms. Refer to Snippets Support by Platform for a comprehensive table of supported snippets.

FAQs

Are snippets designed for specific websites?
No. Snippets are generalized and reusable.

Do snippets work with Manifest V3?
Yes.

Can snippets take any type of arguments?
From an interface perspective, any argument to a snippet always is picked as a string. A snippet may interpret a string in any way — some snippets interpret arguments surrounded by forward slashes (/) as regular expressions.

Are snippets injected into frames?
They should be, especially if you're using an eyeo SDK. Injection depends only on the domain of the document.

Where can I find the eyeo snippets library?
eyeo releases the eyeo snippets library as a public npm module named @eyeo/snippets. You can reach the homepage from the eyeo GitLab snippets repository.

Other resources

• Snippet Filters Tutorial