npm install --save @cliqz/adblocker.
There are multiple ways you can create an instance of the blocking engine to start blocking ads:
If you already have filters locally:
;const engine = FiltersEngine;
Fetching lists from URLs:
;engine = await FiltersEngine;
Use ready-made configs to block ads and optionally trackers:
;engine = await FiltersEngine; // ads onlyengine = await FiltersEngine; // ads and tracking
Once you have your
engine, start matching requests and block ads:
;const match = engine;
To abstract over network requests independently from platforms (Node.js,
WebExtension, etc.), the
Request provides a unified APIs and helpers functions
for initialization on different platforms:
;const request = Request;console; // trueconsole; //console; // sub.example.comconsole; // example.com
Manipulating Individual Filters
Content blockers usually manipulate two kinds of filters: network
and cosmetics. The former allows to specify which network requests
should be blocked (or redirected), usually from the
WebRequest API of
extensions. The later allows to alter the DOM of pages directly, hiding
elements or injecting scripts.
Here is how one can parse and match individual network filters using the NetworkFilter class. It offers multiple accessors and helpers to parse, match and manipulate network filters.
;// Parse filter from stringconst filter = NetworkFilter;// Filter attributesconsole; // trueconsole; // 'domain.com'console; // '/ads.js'// Request optionsconsole; // true = can match 'script' requestsconsole; // false = cannot match 'image' requests
Matching network filter against requests:
;const request = Request;console; // true
Similarly, one can parse cosmetic filters using the CosmeticFilter class.
const CosmeticFilter = ;// Parsing filter from stringconst filter = CosmeticFilter;// Propertiesconsole; // trueconsole; // '#selector'console; // false// Matching a cosmetic filter requires both a hostname and domainfilter; // true
Manipulating filters at a low level is useful to build tooling or debugging, but they are not appropriate for efficient blocking of requests (it would require iterating on all the filters to know if a request needs to be blocked). Instead, we can make use of the FiltersEngine class which can be seen as a "container" for both network and cosmetic filters. The filters are organized in a very compact way which also enables fast matching.
;// Parse multiple filters at oncelet engine = FiltersEngine;
Updating an existing engine with new filters:
// Update with individual filtersengine;
Serializing an engine to
Uint8Array and reloading it to its original form:
// Serialize the full engine to a Uint8Array for cachingconst serialized = engine;engine = FiltersEngine;
// Matching network filtersconstmatch // `true` if there is a matchredirect // data url to redirect to if anyexception // instance of NetworkFilter exception if anyfilter // instance of NetworkFilter which matched} = engine;
Checking for CSP injection rules for a given frame:
// Matching CSP (content security policy) filters.const directives = engine;
Checking for cosmetics injection:
// Matching cosmetic filtersconststyles // stylesheet to inject in the pagescripts // Array of scriptlets to inject in the page} = engine;