title | slug | page-type | browser-compat |
---|---|---|---|
declarativeNetRequest.RuleCondition |
Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition |
webextension-api-type |
webextensions.api.declarativeNetRequest.RuleCondition |
{{AddonSidebar()}}
Details of the condition that determines whether a rule matches a request, as the condition
property of a {{WebExtAPIRef("declarativeNetRequest.Rule")}}.
Values of this type are objects. They contain these properties:
-
domainType
{{optional_inline}}- : A
string
. Specifies whether the network request is first-party or third-party to the domain from where it originated. If omitted, all requests are accepted. Possible values are"firstParty"
and"thirdParty"
.
- : A
-
domains
{{deprecated_inline}} {{optional_inline}}- : An array of
string
. UseinitiatorDomains
instead. The rule only matches network requests originating from this list of domains.
- : An array of
-
excludedDomains
{{deprecated_inline}} {{optional_inline}}- : An array of
string
. UseexcludedInitiatorDomains
instead. The rule does not match network requests originating from this list of domains.
- : An array of
-
initiatorDomains
{{optional_inline}}- : An array of
string
. The rule only matches network requests originating from this list of domains. If the list is omitted, the rule is applied to requests from all domains. An empty list is not allowed. A canonical domain should be used. This matches against the request initiator and not the request URL.
- : An array of
-
excludedInitiatorDomains
{{optional_inline}}- : An array of
string
. The rule does not match network requests originating from this list of domains. If the list is empty or omitted, no domains are excluded. This takes precedence overinitiatorDomains
. A canonical domain should be used. This matches against the request initiator and not the request URL.
- : An array of
-
isUrlFilterCaseSensitive
{{optional_inline}}- : A
boolean
. Whether theurlFilter
orregexFilter
(whichever is specified) is case sensitive. While there is consensus on defaulting tofalse
across browsers in WECG issue 269, the value used to betrue
in (older) versions of Chrome and Safari. See Browser compatibility for details.
- : A
-
regexFilter
{{optional_inline}}- : A
string
. Regular expression to match against the network request URL. Note that:- The supported format is not stable and varies across browsers, see "Regular expressions in DNR API (regexFilter)" in WECG issue 344 for details.
- Only one of
urlFilter
orregexFilter
can be specified. - The
regexFilter
must be composed of only {{Glossary("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.
- : A
-
requestDomains
{{optional_inline}}- : An array of
string
. The rule only matches network requests when the domain matches one from this list. If the list is omitted, the rule is applied to requests from all domains. An empty list is not allowed. A canonical domain should be used.
- : An array of
-
excludedRequestDomains
{{optional_inline}}- : An array of
string
. The rule does not match network requests when the domains matches one from this list. If the list is empty or omitted, no domains are excluded. This takes precedence overrequestDomains
. A canonical domain should be used.
- : An array of
-
requestMethods
{{optional_inline}}- : An array of
string
. List of HTTP request methods that the rule matches. An empty list is not allowed. Specifying arequestMethods
rule condition also excludes non-HTTP(s) requests, whereas specifyingexcludedRequestMethods
does not.
- : An array of
-
excludedRequestMethods
{{optional_inline}}- : An array of
string
. List of request methods that the rule does not match on. Only one ofrequestMethods
andexcludedRequestMethods
should be specified. If neither of them is specified, all request methods are matched.
- : An array of
-
resourceTypes
{{optional_inline}}- : An array of {{WebExtAPIRef("declarativeNetRequest.ResourceType")}}. List of resource types that the rule matches with. An empty list is not allowed. This must be specified for
"allowAllRequests"
rules and may only include the"sub_frame"
and"main_frame"
resource types.
- : An array of {{WebExtAPIRef("declarativeNetRequest.ResourceType")}}. List of resource types that the rule matches with. An empty list is not allowed. This must be specified for
-
excludedResourceTypes
{{optional_inline}}- : An array of {{WebExtAPIRef("declarativeNetRequest.ResourceType")}}. List of resource types that the rule does not match on. Only one of
resourceTypes
andexcludedResourceTypes
should be specified. If neither of them is specified, all resource types except"main_frame"
are blocked.
- : An array of {{WebExtAPIRef("declarativeNetRequest.ResourceType")}}. List of resource types that the rule does not match on. Only one of
-
tabIds
{{optional_inline}}- : An array of
number
. List of {{WebExtAPIRef("tabs.Tab")}}.id
that the rule should match. An ID of {{WebExtAPIRef("tabs.TAB_ID_NONE")}} matches requests that don't originate from a tab. An empty list is not allowed. Only supported for session-scoped rules.
- : An array of
-
excludedTabIds
{{optional_inline}}- : An array of
number
. List of {{WebExtAPIRef("tabs.Tab")}}.id
that the rule should not match. An ID of {{WebExtAPIRef("tabs.TAB_ID_NONE")}} excludes requests that do not originate from a tab. Only supported for session-scoped rules.
- : An array of
-
urlFilter
{{optional_inline}}-
: A
string
. The pattern that is matched against the network request URL. Supported constructs:*
: Wildcard: Matches any number of characters.|
: Left or right anchor: If used at either end of the pattern, specifies the beginning or 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_
,-
,.
, or%
. The last^
may also match the end of the URL instead of a separator character.
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 that:- Only one of
urlFilter
orregexFilter
can be specified. - 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 ishttp://abc.рф?q=ф
, theurlFilter
is matched against the URLhttp://abc.xn--p1ai/?q=%D1%84
.
-
Domains specified in initiatorDomains
, excludedInitiatorDomains
, requestDomains
, or excludedRequestDomains
should comply with the following:
- Sub-domains such as "a.example.com" are allowed.
- The entries must consist of only lowercase ASCII characters.
- Use Punycode encoding for internationalized domains.
- IPv4 addresses must be represented as 4 numbers separated by a dot.
- IPv6 addresses should be represented in their canonical form, wrapped in square brackets.
To programmatically generate the canonical domain for a URL, use the URL API and read its hostname
property, i.e., new URL(url).hostname
.
{{WebExtExamples("h2")}}
{{Compat}}