chrome.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
Manifest #
Extensions must declare the "declarativeNetRequest"
permission in the extension manifest to use this API. The "declarativeNetRequestFeedback"
permission is required to access functions and events which return information on declarative rules matched. Host permissions are required if the extension wants to redirect requests or modify headers. To specify static Rulesets, extensions must also declare the "declarative_net_request"
manifest key, which should be a dictionary with a single key called "rule_resources"
. It should be a list containing dictionaries of type Ruleset, as shown below.
{
"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",
"*://example.com/*"
],
...
}
Rule Resources #
An extension can specify up to MAX_NUMBER_OF_STATIC_RULESETS rulesets as part of the "rule_resources"
manifest key. An extension is allowed to enable at least GUARANTEED_MINIMUM_STATIC_RULES static rules. Additional static rule sets may or may not be enabled depending on the available global static rule limit.
Global Static Rule Limit #
In addition to the GUARANTEED_MINIMUM_STATIC_RULES static rules guaranteed for each extension, extensions can enable additional static rulesets depending on the available global static rule limit. This global limit is shared between all extensions and can be used by extensions on a first-come, first-served basis. Extensions shouldn't depend on the global limit having a specific value and should instead use the getAvailableStaticRuleCount API method to find the additional rule limit available to them.
Rules #
A single declarative Rule consists of four fields: id
, priority
, condition
, and action
. There are the following kinds of rules:
- Rules that block a network request.
- Rules that prevent a request from getting blocked by negating any matching blocked rules.
- Rules that redirect a network request.
- Rules that modify headers from a network request.
An example rule:
{
"id" : 1,
"priority": 1,
"action" : { "type" : "block" },
"condition" : {
"urlFilter" : "abc",
"domains" : ["foo.com"],
"resourceTypes" : ["script"]
}
}
The above rule will block all script requests originating from "foo.com"
to any URL with "abc"
as a substring.
The urlFilter
field of a rule condition is used to specify the pattern which is matched against the request URL. Some examples of URL filters:
urlFilter | Matches | Does not match |
---|---|---|
"abc" | https://abcd.com https://example.com/abcd | http://ab.com |
"abc*d" | https://abcd.com https://example.com/abcxyzd | http://abc.com |
"||a.example.com" | https://a.example.com/ https://b.a.example.com/xyz | http://example.com/ |
"|https*" | https://example.com | http://example.com/ http://https.com |
"example*^123|" | https://example.com/123 http://abc.com/example?123 | https://example.com/1234 https://abc.com/example0123 |
Dynamic rules #
To add or remove rules dynamically, use the updateDynamicRules API method.
- The number of dynamic rules that an an extension can add is bounded by the MAX_NUMBER_OF_DYNAMIC_RULES constant.
- The dynamic rules for an extension are persisted across both sessions and extension updates.
Updating enabled rulesets #
An extension can update the set of enabled static rulesets using the updateEnabledRulesets API method.
- The number of rules across enabled static rulesets must be less than the MAX_NUMBER_OF_RULES constant.
- The set of enabled static rulesets is persisted across sessions but not across extension updates. The
rule_resources
manifest key will determine the set of enabled static rulesets on initial extension install and on each subsequent extension update.
Implementation details #
Matching algorithm #
Before the request is sent, each extension is queried for an action to take. The following actions are considered at this stage:
- Actions which block requests of type
block
- Actions which redirect requests of type
redirect
orupgradeScheme
- Actions which allow requests of type
allow
orallowAllRequests
If more than one extension returns an action, the extension whose action type comes first in the list above gets priority. If more than one extension returns an action with the same priority (position in the list), the most recently installed extension gets priority.
When an extension is queried for how to handle a request, the highest priority matching static or dynamic rule is returned. If more than one matching rule has the highest priority, the tie is broken based on the action type, in the following order of decreasing precedence:
allow
allowAllRequests
block
upgradeScheme
redirect
If the request was not blocked or redirected, the matching modifyHeaders
rules are evaluated with the most recently installed extensions getting priority. Within each extension, all modifyHeaders
rules with a priority lower than matching allow
or allowAllRequests
rules are ignored.
If multiple modifyHeaders
rules specify the same header, the resulting modification for the header is determined based on the priority of each rule and the operations specified.
- If a rule has appended to a header, then lower priority rules can only append to that header.
set
andremove
operations are not permitted. - If a rule has set a header, then lower priority rules cannot further modify the header, except for
append
rules from the same extension. - If a rule has removed a header, then lower priority rules cannot further modify the header.
Comparison with the webRequest API #
- The declarativeNetRequest API allows for evaluating network requests in the browser itself. This makes it more performant than the webRequest API, where each network request is evaluated in JavaScript in the extension process.
- Because the requests are not intercepted by the extension process, declarativeNetRequest removes the need for extensions to have a background page; resulting in less memory consumption.
- Unlike the webRequest API, blocking requests using the declarativeNetRequest API requires no host permissions.
- The declarativeNetRequest API provides better privacy to users because extensions can't actually read the network requests made on the user's behalf.
- Unlike the webRequest API, any images or iframes blocked using the declarativeNetRequest API are automatically collapsed in the DOM.
- While deciding whether a request is to be blocked or redirected, the declarativeNetRequest API is given priority over the webRequest API because it allows for synchronous interception. Similarly, any headers removed through declarativeNetRequest API are not made visible to web request extensions.
- The webRequest API is more flexible as compared to the declarativeNetRequest API because it allows extensions to evaluate a request programmatically.
Example #
manifest.json
{
"name": "declarativeNetRequest extension",
"version": "1",
"declarative_net_request": {
"rule_resources": [{
"id": "ruleset_1",
"enabled": true,
"path": "rules.json"
}]
},
"permissions": [
"*://*.google.com/*",
"*://*.abcd.com/*",
"*://*.example.com/*",
"http://*.xyz.com/*",
"*://*.headers.com/*",
"declarativeNetRequest"
],
"manifest_version": 2
}
rules.json
[
{
"id": 1,
"priority": 1,
"action": { "type": "block" },
"condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
},
{
"id": 2,
"priority": 1,
"action": { "type": "allow" },
"condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
},
{
"id": 3,
"priority": 2,
"action": { "type": "block" },
"condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
},
{
"id": 4,
"priority": 1,
"action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
"condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
},
{
"id": 5,
"priority": 1,
"action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
"condition": { "urlFilter": "abcd.com", "resourceTypes": ["main_frame"] }
},
{
"id": 6,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": { "scheme": "https", "host": "new.example.com" }
}
},
"condition": { "urlFilter": "||example.com", "resourceTypes": ["main_frame"] }
},
{
"id": 7,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"regexSubstitution": "https://\\1.xyz.com/"
}
},
"condition": {
"regexFilter": "^http://www\\.(abc|def)\\.xyz\\.com/",
"resourceTypes": [
"main_frame"
]
}
},
{
"id" : 8,
"priority": 2,
"action" : {
"type" : "allowAllRequests"
},
"condition" : {
"urlFilter" : "||b.com/path",
"resourceTypes" : ["sub_frame"]
}
},
{
"id" : 9,
"priority": 1,
"action" : {
"type" : "block"
},
"condition" : {
"urlFilter" : "script.js",
"resourceTypes" : ["script"]
}
},
{
"id": 10,
"priority": 2,
"action": {
"type": "modifyHeaders",
"responseHeaders": [
{ "header": "h1", "operation": "remove" },
{ "header": "h2", "operation": "set", "value": "v2" },
{ "header": "h3", "operation": "append", "value": "v3" }
]
},
"condition": { "urlFilter": "headers.com/123", "resourceTypes": ["main_frame"] }
},
{
"id": 11,
"priority": 1,
"action": {
"type": "modifyHeaders",
"responseHeaders": [
{ "header": "h1", "operation": "set", "value": "v4" },
{ "header": "h2", "operation": "append", "value": "v5" },
{ "header": "h3", "operation": "append", "value": "v6" }
]
},
"condition": { "urlFilter": "headers.com/12345", "resourceTypes": ["main_frame"] }
},
]
- Consider a navigation to
"http://google.com"
. Rules with id (1) and (4) match. The request will be blocked because blocking rules have higher priority than redirect rules when the"priority"
is the same. - Consider a navigation to
"http://google.com/1234"
. Rules with id (1), (2), and (4) match. Because the request has a matchingallow
rule and no higher priority rules, the request is not blocked nor redirected and continues to"http://google.com/1234"
. - Consider a navigation to
"http://google.com/12345"
Rules with id (1), (2), (3), and (4) match. The request will be blocked because rule (3) has the highest priority, overriding all other matching rules. - Consider a navigation to
"http://abcd.com"
. The rule with id (5) matches. Since rule (5) specifies an extension path, the request is redirected to"chrome-extension://<extension-id>/a.jpg"
. - Consider a navigation to
"http://example.com/path"
. The rule with id (6) matches. Since rule (6) specifies a url transform, the request is redirected to"https://new.example.com/path"
. - Consider a navigation to
"http://www.abc.xyz.com/path"
. The rule with id (7) matches. The request will be redirected to"https://abc.xyz.com/path"
. - Consider the following request hierarchy:
- https://a.com/path (main-frame request)
- https://b.com/path (sub-frame request, matches rule with id (8))
- https://c.com/path (sub-frame request, matches rule with id (8))
- https://c.com/script.js (script request, matches rules with ids (8, 9) but (8) has higher priority)
- https://b.com/script.js (script request, matches rules with ids (8, 9) but (8) has higher priority)
- https://c.com/path (sub-frame request, matches rule with id (8))
- https://d.com/path (sub-frame request)
- https://d.com/script.js (script request, matches rule with ids (9))All requests in green will be allow-listed due to rule with id (8) and not be evaluated by the extensions' ruleset. Requests in red will be blocked due to rule with id (9).
- https://b.com/path (sub-frame request, matches rule with id (8))
- https://a.com/path (main-frame request)
- Consider a navigation to
"http://headers.com/12345"
with response headers{ "h1": "initial_1", "h2": "initial_2" }
. Rules with id (10) and (11) match. The request will have its response headers modified to{ "h2": "v2", "h2": "v5", "h3": "v3", "h3": "v6" }
. Headerh1
was removed by (10),h2
was set by (10) then appended by (11), andh3
was appended by (10) and (11).
Summary
- Types
- Properties
- Methods
chrome.declarativeNetRequest.getAvailableStaticRuleCount(callback: function)
chrome.declarativeNetRequest.getDynamicRules(callback: function)
chrome.declarativeNetRequest.getEnabledRulesets(callback: function)
chrome.declarativeNetRequest.getMatchedRules(filter?: MatchedRulesFilter, callback: function)
chrome.declarativeNetRequest.isRegexSupported(regexOptions: RegexOptions, callback: function)
chrome.declarativeNetRequest.setExtensionActionOptions(options: ExtensionActionOptions, callback: function)
chrome.declarativeNetRequest.updateDynamicRules(options: UpdateRuleOptions, callback: function)
chrome.declarativeNetRequest.updateEnabledRulesets(options: UpdateRulesetOptions, callback: function)
- Events
Types
ExtensionActionOptions
Properties
- displayActionCountAsBadgeTextboolean optional
Whether to automatically display the action count for a page as the extension's badge text. This preference is persisted across sessions.
- tabUpdateTabActionCountUpdate optional
Details of how the tab's action count should be adjusted.
IsRegexSupportedResult
Properties
- isSupportedboolean
- reasonUnsupportedRegexReason optional
Specifies the reason why the regular expression is not supported. Only provided if
isSupported
is false.
MatchedRule
Properties
- ruleIdnumber
A matching rule's ID.
- rulesetIdstring
ID of the
Ruleset
this rule belongs to. For a rule originating from the set of dynamic rules, this will be equal toDYNAMIC_RULESET_ID
.
MatchedRuleInfo
Properties
- rule
- tabIdnumber
The tabId of the tab from which the request originated if the tab is still active. Else -1.
- timeStampnumber
The time the rule was matched. Timestamps will correspond to the Javascript convention for times, i.e. number of milliseconds since the epoch.
MatchedRuleInfoDebug
Properties
- request
Details about the request for which the rule was matched.
- rule
MatchedRulesFilter
Properties
- minTimeStampnumber optional
If specified, only matches rules after the given timestamp.
- tabIdnumber optional
If specified, only matches rules for the given tab.
ModifyHeaderInfo
Properties
- headerstring
The name of the header to be modified.
- operation
The operation to be performed on a header.
- valuestring optional
The new value for the header. Must be specified for
append
andset
operations.
QueryKeyValue
Properties
- keystring
- valuestring
QueryTransform
Properties
- addOrReplaceParamsQueryKeyValue[] optional
The list of query key-value pairs to be added or replaced.
- removeParamsstring[] optional
The list of query keys to be removed.
Redirect
Properties
- extensionPathstring optional
Path relative to the extension directory. Should start with '/'.
- regexSubstitutionstring optional
Substitution pattern for rules which specify a
regexFilter
. The first match ofregexFilter
within the url will be replaced with this pattern. WithinregexSubstitution
, backslash-escaped digits (\1 to \9) can be used to insert the corresponding capture groups. \0 refers to the entire matching text. - transformURLTransform optional
Url transformations to perform.
- urlstring optional
The redirect url. Redirects to JavaScript urls are not allowed.
RegexOptions
Properties
- isCaseSensitiveboolean optional
Whether the
regex
specified is case sensitive. Default is true. - regexstring
The regular expresson to check.
- requireCapturingboolean optional
Whether the
regex
specified requires capturing. Capturing is only required for redirect rules which specify aregexSubstition
action. The default is false.
RequestDetails
Properties
- frameIdnumber
The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (
type
ismain_frame
orsub_frame
),frameId
indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab. - initiatorstring optional
The origin where the request was initiated. This does not change through redirects. If this is an opaque origin, the string 'null' will be used.
- methodstring
Standard HTTP method.
- parentFrameIdnumber
ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.
- requestIdstring
The ID of the request. Request IDs are unique within a browser session.
- tabIdnumber
The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab.
- type
The resource type of the request.
- urlstring
The URL of the request.
Rule
Properties
- action
The action to take if this rule is matched.
- condition
The condition under which this rule is triggered.
- idnumber
An id which uniquely identifies a rule. Mandatory and should be >= 1.
- prioritynumber optional
Rule priority. Defaults to 1. When specified, should be >= 1.
RuleAction
Properties
- redirectRedirect optional
Describes how the redirect should be performed. Only valid for redirect rules.
- requestHeadersModifyHeaderInfo[] optional
The request headers to modify for the request. Only valid if RuleActionType is "modifyHeaders".
- responseHeadersModifyHeaderInfo[] optional
The response headers to modify for the request. Only valid if RuleActionType is "modifyHeaders".
- type
The type of action to perform.
RuleCondition
Properties
- domainTypeDomainType optional
Specifies whether the network request is first-party or third-party to the domain from which it originated. If omitted, all requests are accepted.
- domainsstring[] optional
The rule will only match network requests originating from the list of
domains
. If the list is omitted, the rule is applied to requests from all domains. An empty list is not allowed.Notes:
- Sub-domains like "a.example.com" are also allowed.
- The entries must consist of only ascii characters.
- Use punycode encoding for internationalized domains.
- This matches against the request initiator and not the request url.
- excludedDomainsstring[] optional
The rule will not match network requests originating from the list of
excludedDomains
. If the list is empty or omitted, no domains are excluded. This takes precedence overdomains
.Notes:
- Sub-domains like "a.example.com" are also allowed.
- The entries must consist of only ascii characters.
- Use punycode encoding for internationalized domains.
- This matches against the request initiator and not the request url.
- excludedResourceTypesResourceType[] optional
List of resource types which the rule won't match. Only one of
resourceTypes
andexcludedResourceTypes
should be specified. If neither of them is specified, all resource types except "main_frame" are blocked. - isUrlFilterCaseSensitiveboolean optional
Whether the
urlFilter
orregexFilter
(whichever is specified) is case sensitive. Default is true. - regexFilterstring optional
Regular expression to match against the network request url. This follows the RE2 syntax.
Note: Only one of
urlFilter
orregexFilter
can be specified.Note: The
regexFilter
must be composed of only ASCII characters. This is matched against a url where the host is encoded in the punycode format (in case of internationalized domains) and any other non-ascii characters are url encoded in utf-8. - resourceTypesResourceType[] optional
List of resource types which the rule can match. An empty list is not allowed.
Note: this must be specified for
allowAllRequests
rules and may only include thesub_frame
andmain_frame
resource types. - urlFilterstring optional
The pattern which is matched against the network request url. Supported constructs:
'*' : Wildcard: Matches any number of characters.
'|' : Left/right anchor: If used at either end of the pattern, specifies the beginning/end of the url respectively.
'||' : Domain name anchor: If used at the beginning of the pattern, specifies the start of a (sub-)domain of the URL.
'^' : Separator character: This matches anything except a letter, a digit or one of the following: _ - . %. This can also match the end of the URL.
Therefore
urlFilter
is composed of the following parts: (optional Left/Domain name anchor) + pattern + (optional Right anchor).If omitted, all urls are matched. An empty string is not allowed.
A pattern beginning with
||*
is not allowed. Use*
instead.Note: Only one of
urlFilter
orregexFilter
can be specified.Note: The
urlFilter
must be composed of only ASCII characters. This is matched against a url where the host is encoded in the punycode format (in case of internationalized domains) and any other non-ascii characters are url encoded in utf-8. For example, when the request url is http://abc.рф?q=ф, theurlFilter
will be matched against the url http://abc.xn--p1ai/?q=%D1%84.
RulesMatchedDetails
Properties
- rulesMatchedInfo
Rules matching the given filter.
Ruleset
Properties
- enabledboolean
Whether the ruleset is enabled by default.
- idstring
A non-empty string uniquely identifying the ruleset. IDs beginning with '_' are reserved for internal use.
- pathstring
The path of the JSON ruleset relative to the extension directory.
TabActionCountUpdate
Properties
- incrementnumber
The amount to increment the tab's action count by. Negative values will decrement the count.
- tabIdnumber
The tab for which to update the action count.
URLTransform
Properties
- fragmentstring optional
The new fragment for the request. Should be either empty, in which case the existing fragment is cleared; or should begin with '#'.
- hoststring optional
The new host for the request.
- passwordstring optional
The new password for the request.
- pathstring optional
The new path for the request. If empty, the existing path is cleared.
- portstring optional
The new port for the request. If empty, the existing port is cleared.
- querystring optional
The new query for the request. Should be either empty, in which case the existing query is cleared; or should begin with '?'.
- queryTransformQueryTransform optional
Add, remove or replace query key-value pairs.
- schemestring optional
The new scheme for the request. Allowed values are "http", "https", "ftp" and "chrome-extension".
- usernamestring optional
The new username for the request.
UpdateRuleOptions
Properties
- addRulesRule[] optional
Rules to add.
- removeRuleIdsnumber[] optional
IDs of the rules to remove. Any invalid IDs will be ignored.
UpdateRulesetOptions
DomainType
This describes whether the request is first or third party to the frame in which it originated. A request is said to be first party if it has the same domain (eTLD+1) as the frame in which the request originated.
Enum
"firstParty"
, or "thirdParty"
HeaderOperation
This describes the possible operations for a "modifyHeaders" rule.
Enum
"append"
, "set"
, or "remove"
ResourceType
This describes the resource type of the network request.
Enum
"main_frame"
, "sub_frame"
, "stylesheet"
, "script"
, "image"
, "font"
, "object"
, "xmlhttprequest"
, "ping"
, "csp_report"
, "media"
, "websocket"
, or "other"
RuleActionType
Describes the kind of action to take if a given RuleCondition matches.
Enum
"block"
, "redirect"
, "allow"
, "upgradeScheme"
, "modifyHeaders"
, or "allowAllRequests"
UnsupportedRegexReason
Describes the reason why a given regular expression isn't supported.
Enum
"syntaxError"
, or "memoryLimitExceeded"
Properties
DYNAMIC_RULESET_ID
Ruleset ID for the dynamic rules added by the extension.
Value
GETMATCHEDRULES_QUOTA_INTERVAL
Time interval within which MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
calls can be made, specified in minutes. Additional calls will fail immediately and set runtime.lastError
. Note: getMatchedRules
calls associated with a user gesture are exempt from the quota.
Value
GUARANTEED_MINIMUM_STATIC_RULES
The minimum number of static rules guaranteed to an extension across its enabled static rulesets. Any rules above this limit will count towards the global rule limit.
Value
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
The number of times getMatchedRules
can be called within a period of GETMATCHEDRULES_QUOTA_INTERVAL
.
Value
MAX_NUMBER_OF_DYNAMIC_RULES
The maximum number of dynamic rules that an extension can add.
Value
MAX_NUMBER_OF_REGEX_RULES
The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of dynamic rules and those specified in the rule resources file.
Value
MAX_NUMBER_OF_STATIC_RULESETS
The maximum number of static Rulesets
an extension can specify as part of the "rule_resources"
manifest key.
Value
Methods
getAvailableStaticRuleCount
chrome.declarativeNetRequest.getAvailableStaticRuleCount(callback: function)
Returns the number of static rules an extension can enable before the global static rule limit is reached.
Parameters
- callbackfunction
The callback parameter should be a function that looks like this:
(count: number) => {...}
- countnumber
getDynamicRules
chrome.declarativeNetRequest.getDynamicRules(callback: function)
Returns the current set of dynamic rules for the extension.
getEnabledRulesets
chrome.declarativeNetRequest.getEnabledRulesets(callback: function)
Returns the ids for the current set of enabled static rulesets.
Parameters
- callbackfunction
Called with a list of ids, where each id corresponds to an enabled static
Ruleset
.The callback parameter should be a function that looks like this:
(rulesetIds: string[]) => {...}
- rulesetIdsstring[]
getMatchedRules
chrome.declarativeNetRequest.getMatchedRules(filter?: MatchedRulesFilter, callback: function)
Returns all rules matched for the extension. Callers can optionally filter the list of matched rules by specifying a |filter|. This method is only available to extensions with the declarativeNetRequestFeedback
permission or having the activeTab
permission granted for the tabId
specified in filter
. Note: Rules not associated with an active document that were matched more than five minutes ago will not be returned.
Parameters
- filterMatchedRulesFilter optional
An object to filter the list of matched rules.
- callbackfunction
Called once the list of matched rules has been fetched. In case of an error,
runtime.lastError
will be set and no rules will be returned. This can happen for multiple reasons, such as insufficient permissions, or exceeding the quota.The callback parameter should be a function that looks like this:
(details: RulesMatchedDetails) => {...}
- details
isRegexSupported
chrome.declarativeNetRequest.isRegexSupported(regexOptions: RegexOptions, callback: function)
Checks if the given regular expression will be supported as a regexFilter
rule condition.
Parameters
- regexOptions
The regular expression to check.
- callbackfunction
Called with details consisting of whether the regular expression is supported and the reason if not.
The callback parameter should be a function that looks like this:
(result: IsRegexSupportedResult) => {...}
- result
setExtensionActionOptions
chrome.declarativeNetRequest.setExtensionActionOptions(options: ExtensionActionOptions, callback: function)
Configures if the action count for tabs should be displayed as the extension action's badge text and provides a way for that action count to be incremented.
Parameters
- options
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
updateDynamicRules
chrome.declarativeNetRequest.updateDynamicRules(options: UpdateRuleOptions, callback: function)
Modifies the current set of dynamic rules for the extension. The rules with IDs listed in options.removeRuleIds
are first removed, and then the rules given in options.addRules
are added. Notes:
- This update happens as a single atomic operation: either all specified rules are added and removed, or an error is returned.
- These rules are persisted across browser sessions and across extension updates.
- Static rules specified as part of the extension package can not be removed using this function.
MAX_NUMBER_OF_DYNAMIC_RULES
is the maximum number of dynamic rules an extension can add.
Parameters
- options
- callbackfunction
Called once the update is complete or has failed. In case of an error,
runtime.lastError
will be set and no change will be made to the rule set. This can happen for multiple reasons, such as invalid rule format, duplicate rule ID, rule count limit exceeded, internal errors, and others.The callback parameter should be a function that looks like this:
() => {...}
updateEnabledRulesets
chrome.declarativeNetRequest.updateEnabledRulesets(options: UpdateRulesetOptions, callback: function)
Updates the set of enabled static rulesets for the extension. The rulesets with IDs listed in options.disableRulesetIds
are first removed, and then the rulesets listed in options.enableRulesetIds
are added.
Note that the set of enabled static rulesets is persisted across sessions but not across extension updates, i.e. the rule_resources
manifest key will determine the set of enabled static rulesets on each extension update.
Parameters
- options
- callbackfunction
Called once the update is complete. In case of an error,
runtime.lastError
will be set and no change will be made to set of enabled rulesets. This can happen for multiple reasons, such as invalid ruleset IDs, rule count limit exceeded, or internal errors.The callback parameter should be a function that looks like this:
() => {...}
Events
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(listener: function)
Fired when a rule is matched with a request. Only available for unpacked extensions with the declarativeNetRequestFeedback
permission as this is intended to be used for debugging purposes only.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(info: MatchedRuleInfoDebug) => {...}
The rule that has been matched along with information about the associated request.