Manifest V3 Subscriptions

Manifest V3 Subscriptions

MV3 subscriptions

EWE keeps track of filter lists through subscriptions. With the introduction of Manifest V3 (MV3), all extensions must define filtering rules in a specific format that's incompatible with eyeo's filter list format.

Filter lists have to be converted to rulesets, which are referenced in the extension manifest file. With MV3, both rulesets and subscriptions must be bundled and distributed together within the extension.

On this page, you'll learn about how subscription lists work, how to convert them to rulesets, and how to add custom subscriptions.

Subscription list basics

A subscription list is a JSON file with information that defines the subscription's details and where it should be fetched from.

The following example shows the EasyList subscription list:

[
  {
    "id": "8C13E995-8F06-4927-BEA7-6C845FB7EEBF",
    "type": "ads",
    "languages": ["en"],
    "title": "EasyList",
    "homepage": "https://easylist.to/",
    "url": "https://easylist-downloads.adblockplus.org/v3/full/easylist.txt",
    "mv2_url": "https://easylist-downloads.adblockplus.org/easylist.txt"
  }
]

Subscriptions

A filter list is a text file with filtering rules, referenced by its URL or ID in subscription lists. In Manifest V2, a subscription consisted mostly of a filter list in a specific format:

[Adblock Plus 2.0]
! id: 8C13E995-8F06-4927-BEA5-6C885FB7EEBF
...
testpages.adblockplus.org###eh-id
...

DNR rules and rulesets

DNR rules are the filtering rule format used in Manifest V3, provided in JSON ruleset files:

[
  {
    "priority": 1000,
    "condition": {
      "urlFilter": "&werbemittel=",
      "isUrlFilterCaseSensitive": false
    },
    "action": {
      "type": "block"
    },
    "id": 8163
  }
]

Manifest file changes

To filter network requests, rulesets have to be listed in the extension manifest file:

{
  "declarative_net_request": {
    "rule_resources": [
      {
        "id": "0798B6A2-94A4-4ADF-89ED-BEC112FC4C7F",
        "enabled": false,
        "path": "rulesets/0798B6A2-94A4-4ADF-89ED-BEC112FC4C7F"
      }
    ]
  }
}

Converting filter lists to DNR rulesets

Follow these steps to convert a filter list to a DNR ruleset:

1. Get at least one filter list.

2. (Optional) Merge several filter lists into a single list.

3. Download filters.

4. Convert filters to DNR rules.

5. Add DNR ruleset information to the manifest file.

Command line scripts

Several command-line scripts are available to help with this process. In the most common use case:

# Download default subscription list
npm exec subs-init

# Merge subscription lists
npm exec subs-merge

# Download subscriptions
npm exec subs-fetch

# Convert subscriptions to rulesets
npm exec subs-convert

# Generate manifest file fragment
npm exec subs-generate

subs-init

Downloads default subscription list to given output file location.

npm exec subs-init -- [--output/-o output_file]

Options:

• output/o: Output file. Default: "scriptsOutput/subscriptions_mv3.json"

subs-merge

Merges subscription lists.

npm exec subs-merge -- [--input/-i input_file...]
                       [--output/-o output_file]
                       [--space/-s space]

Options:

• input/i: Input file(s). Default: "scriptsOutput/subscriptions_mv3.json"

• output/o: Output file. Default: "scriptsOutput/custom-subscriptions.json"

• space/s: Number of spaces for indentation. Default: 0

subs-fetch

Downloads filter lists from the subscriptions defined in input files.

npm exec subs-fetch -- [--input/-i input_file...]
                       [--output/-o output_dir]
                       [--ignoreFetchErrors/-ife]

Options:

• input/i: Input file(s). Default: "scriptsOutput/custom-subscriptions.json"

• output/o: Output directory. Default: "scriptsOutput/subscriptions"

• ignoreFetchErrors/ife: Whether to ignore fetching errors. Default: false

subs-convert

Converts filter lists to rulesets.

npm exec subs-convert -- [--input/-i input_dir]
                         [--output/-o output_dir]
                         [--report/-r]
                         [--report-output/-O report_dir]

Options:

• input/i: Input directory. Default: "scriptsOutput/subscriptions"

• output/o: Output directory. Default: "scriptsOutput/rulesets"

• report/r: Boolean flag to generate a report. Default: false

• report-output/O: Report directory. Default: "scriptsOutput/report"

subs-generate

Generates web extension manifest fragment.

npm exec subs-generate -- [--input/-i input_dir]
                          [--output/-o output_file]
                          [--prefix/-p prefix_text]

Options:

• input/i: Input directory. Default: "scriptsOutput/rulesets"

• output/o: Output file. Default: "scriptsOutput/rulesets/rulesets.json"

• prefix/p: Prefix text. Default: ""

Adding subscriptions

Before subscriptions are added, check availability through the Solution:

EWE.subscriptions.getRecommendations();

Then add subscriptions using their URLs:

EWE.subscriptions.add('http://myhost.com/subscription.txt');

To check which subscriptions are added and available:

await EWE.subscriptions.getDownloadable();

Custom subscriptions list

The default provided subscriptions can be overridden by adding a file called custom-subscriptions.json in the scriptsOutput directory.

Examples:

# Merge product-specific subscriptions file with default subscriptions
npm run subs-merge -- \
  -i /tmp/product-subscriptions.json \
  -o $(pwd)/scriptsOutput/custom-subscriptions.json

# Merge two subscriptions files
npm run subs-merge -- \
  -i /tmp/product-subscriptions.json \
  -i /tmp/language_en-subscriptions.json \
  -o $(pwd)/scriptsOutput/custom-subscriptions.json