eyeo's WebExtension Ad-Filtering Solution

![Contributor
Covenant](./CODE_OF_CONDUCT.md)

This is a library that provides integration of eyeo's Ad Blocking Core
for Chromium and Firefox extensions (like [Adblock Plus][abpui]). The Ad
Blocking Core is in the adblockpluscore directory. See the content of that directory
for further information.

Code of Conduct

All contributors to this project are required to read, and follow, our
code of conduct.

Getting started

The library comes in four parts:

* ewe-api.js to be included in the extension's background page
* ewe-content.js to be loaded as a content script
* ewe-content-api.js to be imported in the extension's various content scripts
* ewe-ui.js to be loaded in the extension's various UI pages

You can get it from [npm][npm-package].

Additionally, the SDK provides standalone utilities that can work in both
browser extension contexts, as well as other Javascript contexts.

With two versions of the API, Manifest V2 and Manifest V3, there are
two different manifest that are needed depending on which API you
target.

$3

The webext-ad-filtering-solution (as a short term we use 'engine') is tested on
the following versions:

Manifest V2:

* Chromium 79 and latest
* Firefox 68 and latest
* Edge latest

Chromium 129 and newer do not support MV2 web extensions, so version "128.0.6613.0"
is used for MV2 testing.

Manifest V3:

* Chromium 124 and latest
* Edge latest
* Safari latest - iOS and macOS (limited support)

List of browsers supported by extension and webext can be found in the [supported-browsers].

$3

For Manifest V2, the extension's manifest.json is required to
include the following configuration:

``{ "manifest_version": 2, "background": { "scripts": [ "ewe-api.js" ] }, "content_scripts": [ { "all_frames": true, "js": [ "ewe-content.js" ], "match_about_blank": true, "matches": [ "http:///", "https:///" ], "run_at": "document_start" } ], "permissions": [ "webNavigation", "webRequest", "webRequestBlocking", "scripting", "storage", "unlimitedStorage", "tabs", "" ] }`

`$3`

For Manifest V3, the extension's manifest.jsonis required to include the following configuration:

`{ "manifest_version": 3, "background": { "service_worker": "background.js" }, "content_scripts": [ { "all_frames": true, "js": [ "ewe-content.js" ], "match_about_blank": true, "matches": [ "http:///", "https:///" ], "run_at": "document_start" } ], "permissions": [ "declarativeNetRequest", "scripting", "storage", "tabs", "webNavigation", "webRequest", "unlimitedStorage" ], "host_permissions": [ "" ], "declarative_net_request": }`

The example above requires a couple of changes and can't be used as-is.

The service_workervalue needs be set to your built file for the background script, that includesewe-api.js.

Please note that for the sample above, you need to make sure to set the value ofdeclarative_net_requestproperly, as shown in the decalrativeNetRequest documentation. This mean you also need to add to your extension build the files that contains the rulesets declared in this section, as well as the text filter lists. Refer to the Manifest V3 documentation for more details.

The permission declarativeNetRequestWithHostAccessrequires thehost_permissions to be . You could use thedeclarativeNetRequestpermission without settinghost_permissions. But it would have the effect of preventing the filtering of content and limiting the blocking to network requests to those specified inhost_permissions. The default configuration provided offers the most functionality.

`$3`

We require several permissions for the WebExt Ad-Filtering Solution to function correctly. The manifest file templates above include the required permissions. Here is why we need each one:

* webNavigation: Gives access to the Web Navigation API, which we use to apply document-level allowing filters and to block popups. *webRequest: Gives access to the Web Request API. Used to apply URL filters in MV2, and to report on URL filters in MV3. Also used to retrieve sitekeys for a site. *webRequestBlocking(MV2 only): Allows blocking request based on URL filters in MV2. *declarativeNetRequest(MV3 only): Gives access to the Declarative Net Request API, which we use to apply URL filters in MV3. *storage: Gives access to storage APIs, which we use to store downloaded subscriptions, user's custom filters, etc. *unlimitedStorage: By default, extensions are only allowed 5MB of storage, which isn't enough for larger subscriptions. This permission removes that limit. *tabs: Gives access to some tab metadata, including the tab's URL, which is used to apply document-level allowing filters to the tab. *scripting: (MV3 and Firefox MV2 only) Used to apply content filters, including element hiding filters and snippet filters. *: Allows the WebExt Ad-Filtering Solution to act on all websites. Note that in MV2 manifests this goes in thepermissions, but in MV3 manifests this goes in the newhost_permissions section.

You can read more about browser extension permissions and their effects in Google's docs for MV2 permissions and MV3 permissions

`$3`

The API will be available in your own background scripts and UI pages through the globalEWE object. In the background scripts, please call EWE.start()to start blocking ads.

Note that in MV3 extensions, EWE.start()must be called in the first turn of the event loop of the service worker, so that it can attach event listeners.

`$3`

ewe-api.js and ewe-ui.jsare built as a UMD module (Universal Module Definition), and so they can also be used with module bundlers.

If using a module bundler for the background script, do not add ewe-api.jsto yourmanifest.json. Similarly, if using a module bundler for scripts on UI pages, do not addewe-ui.jsto your UI pages. Consequently, there won't be a globalEWE object.

#### CommonJS

`const EWE = require("@eyeo/webext-ad-filtering-solution"); EWE.start();`

#### ESM

`import * as EWE from "@eyeo/webext-ad-filtering-solution"; EWE.start();`

You can also import the content script. This should only be included once by an extension, since it starts running the content scripts without the need to call any sort of "start" function.

`import "@eyeo/webext-ad-filtering-solution/content";`

Individual utilities that can be used in any context can also be imported.

`import {Scheduler} from "@eyeo/webext-ad-filtering-solution/all/scheduler.js";`

Functionality that is intended to run in a UI context (popup, options, etc.) will use theewe-ui.jsfile. This can be imported in those pages either by using the mechanism below in a ui page:

`import * as EWE from "@eyeo/webext-ad-filtering-solution/ui";`

or by handling the bundling and importing the generated file directly:

Functionality that is intended to run in a content script context will use theewe-content-api.jsfile. This can be imported by using the mechanism below:

`import * as EWE from "@eyeo/webext-ad-filtering-solution/content-api";`

`$3`

In order to enable support for [snippet filters][snippet-filters] you have to get the [snippets library][snippets-project] separately and make it available toEWE:

`import * as snippets from "@eyeo/snippets"; EWE.snippets.setLibrary({ injectedCode: snippets.main, isolatedCode: snippets.isolated });`

The integration of the machine learning models is expected to be done by clients of the snippet library.

`$3`

There are some shared resources that are used by both webext-ad-filtering-solution & production code:

* browser* Global is set by webextension-polyfill version 0.8.0. *browser.runtime.connect()/browser.runtime.onConnect* Channel name is prefixed with "ewe:". *browser.runtime.sendMessage()/browser.runtime.onMessage* Our messages are objects with a "type" property whose value is prefixed with "ewe:". *indexedDB.open()* Database name is prefixed with "EWE". * Web page links * Links used by module are prefixed with "abp:" or "https://subscribe.adblockplus.org/". *browser.storage.local and browser.storage.session* Storage keys are prefixed with either "ewe:" or "abp:pref:".

During initialization the engine migrates legacy data from local storage to indexedDB. Files migrated have to be prefixed:`file:`. Files prefixed with`file:///` will be ignored.

`$3`

Using the [notifications module][notifications-module] is optional. To start using it, an initialisation is required:

`EWE.notifications.start();`

`$3`

To enable One Click Allowlisting, you need to set the list of authorized public keys that can be used to authenticate allowlisting requests.

`EWE.allowlisting.setAuthorizedKeys(keys);`

See the [allowlisting module][allowlisting-module] docs for more detail.

New keypairs can be created with the correct algorithm and settings by using our keypair creation script.

`npm run -w @eyeo/webext-ad-filtering-solution create-allowlisting-keypair`

See the Development section below for details on running our scripts and other EWE development tasks. Keys can also be generated using other programs like OpenSSL. The keys use the RSASSA-PKCS1-v1_5 algorithm, SHA512 hash and 4096 bit long modulus. Additionally, when passed tosetAuthorizedKeys, the keys should be base64 encoded strings, in SPKI format.

`$3`

Type declarations are currently manually generated and are located in the`/src/types/index.d.ts`file. Please make sure to update this file each time you want to create or update a type.

`Documentation`

For more information, please refer to the [API documention][api-docs].

`Development`

`$3`

* Node >= 18.16 * npm >= 9

`$3`

`npm install`

`$3`

`npm run build -- --scope @eyeo/webext-ad-filtering-solution`

`$3`

`cd core/sdk/ npx webpack --watch`

#### Custom builds

Our build script is a CLI program with a few additional flags that can be passed to it. It can list the options available if you ask for--help.

`npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --help`

There are some specific flags which might be useful to customise the build:

`Build only engine, no test extensions`


npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --config-name engine
Don't generate any sourcemaps

npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --no-devtool


In the background, this script is using Webpack. You can also see the
webpack command line options for
further information on these flags.
##### Managing Bundled Subscriptions in the test build
In MV3 extensions (and the MV3 test extension), subscriptions are
bundled statically at build time. The bundled subscriptions are based
on the custom subscriptions
file. Bundled
subscriptions are updated by the build script if this file changes.

One case to look out for when working with bundled subscriptions in tests is that subscriptions are NOT re-fetched if their filters have changed. If you need to re-fetch new filters and the list of subscriptions hasn't changed, you can use the--force-subscription-update flag to the build script.

`npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --force-subscription-update`

##### Using your own test-server instance

By default, the build script will start up the test server for updating bundled subscriptions. If you prefer to use a test server which is already running, you can use the--use-external-serverflag.

`npm run -w @eyeo/test-utils start-sdk-server & npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --use-external-server`

#### Release builds

By default, debug builds are created. If building the library to be used in another project you would want to create a release build.

`npm run build:release -- --scope @eyeo/webext-ad-filtering-solution`

`$3`

`npm run -w @eyeo/webext-ad-filtering-solution docs`

`$3`

Linting is run from the root of the monorepo.

`npm run lint`

[abpui]:https://gitlab.com/adblockinc/ext/adblockplus/adblockplusui [api-docs]: https://eyeo.gitlab.io/browser-extensions-and-premium/extensions/extensions/sdk/#apis [allowlisting-module]: https://eyeo.gitlab.io/browser-extensions-and-premium/extensions/extensions/sdk/#allowlisting [notifications-module]: https://eyeo.gitlab.io/browser-extensions-and-premium/extensions/extensions/sdk/#notifications [npm-package]: https://www.npmjs.com/package/@eyeo/webext-ad-filtering-solution [snippet-filters]: https://help.eyeo.com/adblockplus/snippet-filters-tutorial [snippets-project]: https://gitlab.com/eyeo/adblockplus/abp-snippets [supported-browsers]: ../../README.md#supported-browsers

`Events`

The library provides the listeners to observe the events:

* EWE.allowlisting.onUnauthorized: Emitted when an allowlisting request is rejected *EWE.filters: *onAdded: Emitted when a new filter is added *onChanged: Emitted when a filter is either enabled or disabled or metadata changed *onRemoved: Emitted when a filter is removed *EWE.subscriptions: *onAdded: Emitted when a new subscription is added *onChanged: Emitted when any property of the subscription has changed *onRemoved: Emitted when a subscription is removed *EWE.debugging.onLogEvent: Emitted when having debug output *EWE.reporting.onBlockableItem: Emitted when any blockable item is matched

Use addListener(...) to subscribe and removeListener(...)` to unsubscribe.

Manifest V3

See the Manifest V3 documentation for further
explanations.

Testing

For full documentation about testing please refer to our testing document.

eyeo's WebExtension Ad-Filtering Solution

![Contributor
Covenant](./CODE_OF_CONDUCT.md)

Code of Conduct

All contributors to this project are required to read, and follow, our
code of conduct.

Getting started

The library comes in four parts:

You can get it from [npm][npm-package].

Additionally, the SDK provides standalone utilities that can work in both
browser extension contexts, as well as other Javascript contexts.

With two versions of the API, Manifest V2 and Manifest V3, there are
two different manifest that are needed depending on which API you
target.

$3

The webext-ad-filtering-solution (as a short term we use 'engine') is tested on
the following versions:

Manifest V2:

* Chromium 79 and latest
* Firefox 68 and latest
* Edge latest

Chromium 129 and newer do not support MV2 web extensions, so version "128.0.6613.0"
is used for MV2 testing.

Manifest V3:

* Chromium 124 and latest
* Edge latest
* Safari latest - iOS and macOS (limited support)

List of browsers supported by extension and webext can be found in the [supported-browsers].

$3

For Manifest V2, the extension's manifest.json is required to
include the following configuration:

`$3`

For Manifest V3, the extension's manifest.jsonis required to include the following configuration:

The example above requires a couple of changes and can't be used as-is.

The service_workervalue needs be set to your built file for the background script, that includesewe-api.js.

`$3`

We require several permissions for the WebExt Ad-Filtering Solution to function correctly. The manifest file templates above include the required permissions. Here is why we need each one:

You can read more about browser extension permissions and their effects in Google's docs for MV2 permissions and MV3 permissions

`$3`

The API will be available in your own background scripts and UI pages through the globalEWE object. In the background scripts, please call EWE.start()to start blocking ads.

Note that in MV3 extensions, EWE.start()must be called in the first turn of the event loop of the service worker, so that it can attach event listeners.

`$3`

ewe-api.js and ewe-ui.jsare built as a UMD module (Universal Module Definition), and so they can also be used with module bundlers.

#### CommonJS

`const EWE = require("@eyeo/webext-ad-filtering-solution"); EWE.start();`

#### ESM

`import * as EWE from "@eyeo/webext-ad-filtering-solution"; EWE.start();`

You can also import the content script. This should only be included once by an extension, since it starts running the content scripts without the need to call any sort of "start" function.

`import "@eyeo/webext-ad-filtering-solution/content";`

Individual utilities that can be used in any context can also be imported.

`import {Scheduler} from "@eyeo/webext-ad-filtering-solution/all/scheduler.js";`

Functionality that is intended to run in a UI context (popup, options, etc.) will use theewe-ui.jsfile. This can be imported in those pages either by using the mechanism below in a ui page:

`import * as EWE from "@eyeo/webext-ad-filtering-solution/ui";`

or by handling the bundling and importing the generated file directly:

Functionality that is intended to run in a content script context will use theewe-content-api.jsfile. This can be imported by using the mechanism below:

`import * as EWE from "@eyeo/webext-ad-filtering-solution/content-api";`

`$3`

In order to enable support for [snippet filters][snippet-filters] you have to get the [snippets library][snippets-project] separately and make it available toEWE:

`import * as snippets from "@eyeo/snippets"; EWE.snippets.setLibrary({ injectedCode: snippets.main, isolatedCode: snippets.isolated });`

The integration of the machine learning models is expected to be done by clients of the snippet library.

`$3`

There are some shared resources that are used by both webext-ad-filtering-solution & production code:

During initialization the engine migrates legacy data from local storage to indexedDB. Files migrated have to be prefixed:`file:`. Files prefixed with`file:///` will be ignored.

`$3`

Using the [notifications module][notifications-module] is optional. To start using it, an initialisation is required:

`EWE.notifications.start();`

`$3`

To enable One Click Allowlisting, you need to set the list of authorized public keys that can be used to authenticate allowlisting requests.

`EWE.allowlisting.setAuthorizedKeys(keys);`

See the [allowlisting module][allowlisting-module] docs for more detail.

New keypairs can be created with the correct algorithm and settings by using our keypair creation script.

`npm run -w @eyeo/webext-ad-filtering-solution create-allowlisting-keypair`

`$3`

Type declarations are currently manually generated and are located in the`/src/types/index.d.ts`file. Please make sure to update this file each time you want to create or update a type.

`Documentation`

For more information, please refer to the [API documention][api-docs].

`Development`

`$3`

* Node >= 18.16 * npm >= 9

`$3`

`npm install`

`$3`

`npm run build -- --scope @eyeo/webext-ad-filtering-solution`

`$3`

`cd core/sdk/ npx webpack --watch`

#### Custom builds

Our build script is a CLI program with a few additional flags that can be passed to it. It can list the options available if you ask for--help.

`npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --help`

There are some specific flags which might be useful to customise the build:

`Build only engine, no test extensions`


npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --config-name engine
Don't generate any sourcemaps

npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --no-devtool


In the background, this script is using Webpack. You can also see the
webpack command line options for
further information on these flags.
##### Managing Bundled Subscriptions in the test build
In MV3 extensions (and the MV3 test extension), subscriptions are
bundled statically at build time. The bundled subscriptions are based
on the custom subscriptions
file. Bundled
subscriptions are updated by the build script if this file changes.

`npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --force-subscription-update`

##### Using your own test-server instance

`npm run -w @eyeo/test-utils start-sdk-server & npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --use-external-server`

#### Release builds

By default, debug builds are created. If building the library to be used in another project you would want to create a release build.

`npm run build:release -- --scope @eyeo/webext-ad-filtering-solution`

`$3`

`npm run -w @eyeo/webext-ad-filtering-solution docs`

`$3`

Linting is run from the root of the monorepo.

`npm run lint`

`Events`

The library provides the listeners to observe the events:

Use addListener(...) to subscribe and removeListener(...)` to unsubscribe.

Manifest V3

See the Manifest V3 documentation for further
explanations.

Testing

For full documentation about testing please refer to our testing document.

@eyeo/webext-ad-filtering-solution

eyeo's WebExtension Ad-Filtering Solution

Table of contents

Code of Conduct

Getting started

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Documentation

Development

$3

$3

$3

$3

Build only engine, no test extensions

Don't generate any sourcemaps

$3

$3

Events

Manifest V3

Testing

@eyeo/webext-ad-filtering-solution

eyeo's WebExtension Ad-Filtering Solution

Table of contents

Code of Conduct

Getting started

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Documentation

Development

$3

$3

$3

$3

Build only engine, no test extensions

Don't generate any sourcemaps

$3

$3

Events

Manifest V3

Testing

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Documentation`

`Development`

`$3`

`$3`

`$3`

`$3`

`Build only engine, no test extensions`

`$3`

`$3`

`Events`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Documentation`

`Development`

`$3`

`$3`

`$3`

`$3`

`Build only engine, no test extensions`

`$3`

`$3`

`Events`