About GitLabAcceptable Ads

Snippets Overview

An introduction to snippets.

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 thew 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 market, and log is the function. The snippet takes two parameters, Hello and , world, both separated by white space.

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. For example, an injected snippet could interrupt the loading of JSON data that contains information about what ads should be shown.

Understanding the difference between injected and isolated scripts especially matters if you work in an isolated environment. For example, in browser extensions, all DOM-related operations can run more securely in a sandboxed extension context where they cannot be accessed by the page itself.

The following table compares injected and isolated snippets:

Behavior
Injected
Isolated

Execution

Inline

Content Script (include links)

DOM interaction

Can modify the DOM but have no access to it

Have access to their own copy of DOM APIs

Types of snippets

In addition to classifying snippets by their functionality, you can also categorize snippets into the following types:

  • Behavioral Snippets, which change a page’s normal execution behavior

  • Conditional Hiding Snippets, which are responsible for hiding page content based on conditions like matching text, style, image hash

  • Debugging Snippets, which you can use in debugging tasks

  • Performance snippets, which reduce the performance overhead caused by other snippets

Refer to Behavioral Snippets, Conditional Hiding Snippets, and Performance Snippets for a comprehensive snippets list.

Working with snippets

When you use a snippet, you can efficiently interfere with ad display code and locate elements you want to hide in ways CSS or advanced selectors don't allow.

Snippets help you solve problems by working directly with the JavaScript environment, giving you a better ad-filtering solution and your users a better experience.

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 to achieve a certain outcome.

The following filter, for example, blocks any inline script containing the string tracker while enabling all style sheets in the document:

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

The small and targeted approach

Snippets need to be as efficient and fast as possible. When you add a snippet to a website, in particular, you only want to inject what's strictly necessary to suppress ads.

Injected scripts race against others already embedded in a site. As a result, you should aim for an unchanged user experience in terms of performance. Choosing a small, targeted snippets lets you maximize performance.

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, though. For example, 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.

Whether or not a snippet is injected into a web document has nothing to do with whether the document is loaded into the top-level frame or lower-level frames. Injection depends only on the domain of the document.

One exception to this is data URI frames, which have a unique origin by design.

Do snippets share any data?

Snippets run through the extension and share the same environment as each page that uses snippets. They share nothing, though, with other snippets injected in the browser.

Injected snippets share the same private scope. As a result, it's possible to declare and reuse variables and helpers that each snippet can access, whether in the browser or extension.

Where can I find the eyeo snippets library?

eyeo release 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

Last updated