declarativeNetRequest.RuleCondition

Details of the condition that determines whether a rule matches a request, as the condition property of a declarativeNetRequest.Rule.

Type

Values of this type are objects. They contain these properties:

domainType Optional

A string. Specifies whether the network request is first-party or third-party. The request is considered first-party if it's for the same domain as the document or subdocument that initiates the request. Otherwise, it's considered third-party. If omitted, all requests are accepted. Possible values are "firstParty" and "thirdParty".

domains Optional

An array of string. Use initiatorDomains instead. The rule only matches network requests originating from this list of domains.

excludedDomains Optional

An array of string. Use excludedInitiatorDomains instead. The rule does not match network requests originating from this list of domains.

initiatorDomains Optional

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.

excludedInitiatorDomains Optional

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 over initiatorDomains. A canonical domain should be used. This matches against the request initiator and not the request URL.

isUrlFilterCaseSensitive Optional

A boolean. Whether the urlFilter or regexFilter (whichever is specified) is case sensitive. While there is consensus on defaulting to false across browsers in WECG issue 269, the value used to be true in (older) versions of Chrome and Safari. See Browser compatibility for details.

regexFilter Optional

A string. Regular expression to match against the network request URL. Note that:

requestDomains Optional

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.

excludedRequestDomains Optional

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 over requestDomains. A canonical domain should be used.

requestMethods Optional

An array of string. List of HTTP request methods that the rule matches. An empty list is not allowed. Specifying a requestMethods rule condition also excludes non-HTTP(s) requests, whereas specifying excludedRequestMethods does not.

excludedRequestMethods Optional

An array of string. List of request methods that the rule does not match on. Only one of requestMethods and excludedRequestMethods should be specified. If neither of them is specified, all request methods are matched.

resourceTypes Optional

An array of 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.

excludedResourceTypes Optional

An array of declarativeNetRequest.ResourceType. List of resource types that the rule does not match on. Only one of resourceTypes and excludedResourceTypes should be specified. If neither of them is specified, all resource types except "main_frame" are blocked.

responseHeaders Optional

An array of declarativeNetRequest.HeaderInfo. The rule matches if the request matches any response header condition in this list (if specified).

excludedResponseHeaders Optional

An array of declarativeNetRequest.HeaderInfo. The rule does not match if the request matches any response header condition in this list (if specified). If both excludedResponseHeaders and responseHeaders are specified, then the excludedResponseHeaders property takes precedence.

tabIds Optional

An array of number. List of tabs.Tab.id that the rule should match. An ID of 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.

excludedTabIds Optional

An array of number. List of tabs.Tab.id that the rule should not match. An ID of tabs.TAB_ID_NONE excludes requests that do not originate from a tab. Only supported for session-scoped rules.

urlFilter Optional

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 or regexFilter 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 percent-encoded in UTF-8. For example, when the request URL is http://abc.рф?q=ф, the urlFilter is matched against the URL http://abc.xn--p1ai/?q=%D1%84.

Canonical domain

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.

Example extensions

Browser compatibility

BCD tables only load in the browser