webextensions-examples/dnr-dynamic-with-options

dnr-dynamic-with-options

Demonstrates a generic way to request host permissions and register declarativeNetRequest rules to modify network requests, without any install-time permission warnings. The options_ui page offers a way to request permissions and register declarative net request (DNR) rules.

What it does

After loading the extension, visit the extension options page:

1. Visit about:addons.
2. Go to the extension at "DNR Dynamic with options".
3. Click on Preferences to view its options page (options.html).

On the options page:

1. Input the list of host permissions and click on "Grant host permissions".
2. Input the list of declarativeNetRequest rules and click "Save".
3. Trigger a network request to verify that the rule matched.

Example for options page

Host permissions:

["*://example.com/"]

DNR rules:

[
  {
    "id": 1,
    "priority": 1,
    "condition": {
      "urlFilter": "|https://example.com/",
      "resourceTypes": [
        "main_frame"
      ]
    },
    "action": {
      "type": "block"
    }
  }
]

Manual test case: Visit https://example.com/ and verify that it is blocked.

What it shows

How to create an extension with no install-time permission warnings and request (host) permissions as needed:

• declares the "declarativeNetRequestWithHostAccess" permission, which unlocks the declarativeNetRequest API without install-time warning. In contrast, the "declarativeNetRequest" permission has the same effect, but has the "Block content on any page" permission warning.
• declares the most permissive match pattern in optional_host_permissions.
• calls permissions.request to request host permissions.
• uses permissions.getAll and permissions.remove to reset permissions.

How to retrieve and dynamically register declarativeNetRequest rules, using:

• declarativeNetRequest.getDynamicRules and declarativeNetRequest.updateDynamicRules to manage DNR rules that persist across extension restarts. These rules also persist across browser restarts, unless the extension is loaded temporarily or unloaded.
• declarativeNetRequest.getSessionRules and declarativeNetRequest.updateSessionRules to manage DNR rules that are session-scoped, that is, cleared when an extension unloads or the browser quits.

How these registered DNR rules can modify network requests without requiring an active extension script in the background, in a cross-browser way (at least in Firefox, Chrome, and Safari).

Note on optional_host_permissions and optional_permissions

Firefox does not support optional_host_permissions permissions, it supports host permissions in optional_permissions (https://bugzilla.mozilla.org/show_bug.cgi?id=1766026).

Chrome recognizes optional_host_permissions but does not support host permissions in optional_permissions.

To support both, include optional_host_permissions and optional_permissions in your manifest.json.

Comparison with Manifest Version 2

While this example uses "manifest_version": 3, the functionality is not specific to Manifest Version 3.

To create a MV2 version of the extension, modify manifest.json as follows:

• Set manifest_version to 2.
• Use optional_permissions instead of optional_host_permissions to list optional host permissions.
  • In this example, optional_permissions is present with the same value as optional_host_permissions for the reasons explained in the previous section. The latter is MV3-only and can be removed from a MV2 manifest.