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.
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.
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'
Parts of a snippet
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.The way a snippet works depends on if the snippet is injected or isolated.
- 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 |
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.
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 a snippet requires two steps:
- 1.Write a snippet filter.
- 2.
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.
Adding a filter to the My filter list field
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 ();
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.
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.
No. Snippets are generalized and reusable.
Yes.
A snippet may interpret a string in any way, though. For example, some snippets interpret arguments surrounded by forward slashes (/) as regular expressions.
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.
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.
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.Last modified 1mo ago