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:
eyeo uses snippets to fight ad-filtering circumvention. The following is the first snippet ever written for Adblock Plus:
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:
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:
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:
Write a snippet filter.
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:
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)
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?
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.
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?
Other resources
Last updated
Was this helpful?
