browser.declarativeNetRequest

Description

The chrome.declarativeNetRequest API is used to block or modify network requests by specifying declarative rules. This lets extensions modify network requests without intercepting them and viewing their content, thus providing more privacy.

Permissions

declarativeNetRequest
declarativeNetRequestWithHostAccess

The "declarativeNetRequest" and "declarativeNetRequestWithHostAccess" permissions provide the same capabilities. The difference between them is when permissions are requested or granted.

"declarativeNetRequest"
Triggers a permission warning at install time but provides implicit access to allow, allowAllRequests and block rules. Use this when possible to avoid needing to request full access to hosts.
"declarativeNetRequestFeedback"
Enables debugging features for unpacked extensions, specifically getMatchedRules() and onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
A permission warning is not shown at install time, but you must request host permissions before you can perform any action on a host. This is appropriate when you want to use declarative net request rules in an extension which already has host permissions without generating additional warnings.

Availability

Chrome 84+

Manifest

In addition to the permissions described previously, certain types of rulesets, static rulesets specifically, require declaring the "declarative_net_request" manifest key, which should be a dictionary with a single key called "rule_resources". This key is an array containing dictionaries of type Ruleset, as shown in the following. (Note that the name 'Ruleset' does not appear in the manifest's JSON since it is merely an array.) Static rulesets are explained later in this document.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback"
  ],
  "host_permissions"