chrome.declarativeWebRequest
Description: |
Note: this API is currently on hold, without concrete plans to move to stable. Use the chrome.declarativeWebRequest API to intercept, block, or modify requests in-flight. It is significantly faster than the chrome.webRequest API because you can register rules that are evaluated in the browser rather than the JavaScript engine, which reduces roundtrip latencies and allows higher efficiency.
|
Availability: |
Beta and Dev channels only.
Learn more.
|
Permissions: |
"declarativeWebRequest"
host permissions |
Manifest
You must declare the "declarativeWebRequest" permission in the extension manifest to use this API, along with host permissions.
{ "name": "My extension", ... "permissions": [ "declarativeWebRequest", "*://*/*" ], ... }
Note that certain types of non-sensitive actions do not require host permissions:
CancelRequest
IgnoreRules
RedirectToEmptyDocument
RedirectToTransparentImage
The SendMessageToExtension
action requires host permissions
for any hosts whose network requests you want to trigger a message.
All other actions require host permissions to all URLs.
As an example, if "*://*.google.com/*"
is the only host permission
an extension has, than such an extension may set up a rule to
- cancel a request to "http://www.google.com" or "http://anything.else.com"
- send a message when navigating to "http://www.google.com" but not to "http://something.else.com"
Rules
The Declarative Web Request API follows the concepts of the Declarative API. You can register rules to
the chrome.declarativeWebRequest.onRequest
event object.
The Declarative Web Request API supports a single type of match criteria, the
RequestMatcher
. The RequestMatcher
matches network
requests if and only if all listed criteria are met. The following
RequestMatcher
would match a network request when the user enters
"http://www.example.com" in the URL bar:
var matcher = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com', schemes: ['http'] }, resourceType: ['main_frame'] });
Requests to "https://www.example.com" would be rejected by the
RequestMatcher
due to the scheme. Also all requests for an embedded
iframe would be rejected due to the resourceType
.
Note: All conditions and actions are created via a constructor as shown in the example above.
In order to cancel all requests to "example.com", you can define a rule as follows:
var rule = { conditions: [ new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }) ], actions: [ new chrome.declarativeWebRequest.CancelRequest() ]};
In order to cancel all requests to "example.com" and "foobar.com", you can add a second condition, as each condition is sufficient to trigger all specified actions:
var rule2 = { conditions: [ new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }), new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'foobar.com' } }) ], actions: [ new chrome.declarativeWebRequest.CancelRequest() ]};
Register rules as follows:
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
Note: You should always register or unregister rules in bulk rather than individually because each of these operations recreates internal data structures. This re-creation is computationally expensive but facilitates a very fast URL matching algorithm for hundreds of thousands of URLs. The Performance section of the Events API provides further performance tips.
Evaluation of conditions and actions
The Declarative Web Request API follows the Life cycle model for web requests of the Web Request API. This means that conditions can only be tested at specific stages of a web request and, likewise, actions can also only be executed at specific stages. The following tables list the request stages that are compatible with conditions and actions.
Request stages during which condition attributes can be processed. | ||||
---|---|---|---|---|
Condition attribute | onBeforeRequest | onBeforeSendHeaders | onHeadersReceived | onAuthRequired |
url | ✓ | ✓ | ✓ | ✓ |
resourceType | ✓ | ✓ | ✓ | ✓ |
contentType | ✓ | |||
excludeContentType | ✓ | |||
responseHeaders | ✓ | |||
excludeResponseHeaders | ✓ | |||
requestHeaders | ✓ | |||
excludeRequestHeaders | ✓ | |||
thirdPartyForCookies | ✓ | ✓ | ✓ | ✓ |
Request stages during which actions can be executed. | ||||
Event | onBeforeRequest | onBeforeSendHeaders | onHeadersReceived | onAuthRequired |
AddRequestCookie | ✓ | |||
AddResponseCookie | ✓ | |||
AddResponseHeader | ✓ | |||
CancelRequest | ✓ | ✓ | ✓ | ✓ |
EditRequestCookie | ✓ | |||
EditResponseCookie | ✓ | |||
IgnoreRules | ✓ | ✓ | ✓ | ✓ |
RedirectByRegEx | ✓ | ✓ | ||
RedirectRequest | ✓ | ✓ | ||
RedirectToEmptyDocument | ✓ | ✓ | ||
RedirectToTransparentImage | ✓ | ✓ | ||
RemoveRequestCookie | ✓ | |||
RemoveRequestHeader | ✓ | |||
RemoveResponseCookie | ✓ | |||
RemoveResponseHeader | ✓ | |||
SendMessageToExtension | ✓ | ✓ | ✓ | ✓ |
SetRequestHeader | ✓ |
Note: Applicable stages can be further constrained by using the "stages" attribute.
Note: Redirects initiated by a redirect action use the original request method for the redirect, with one exception: If the redirect is initiated at the onHeadersReceived stage, then the redirect will be issued using the GET method.
Example: It is possible to combine a
new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})
condition with a new chrome.declarativeWebRequest.CancelRequest()
action because both of them can be evaluated in the onHeadersReceived stage.
It is, however, impossible to combine the request matcher with a
new chrome.declarativeWebRequest.SetRequestHeader()
because request headers cannot be set any more by the time the content type has been terminated.
Using priorities to override rules
Rules can be associated with priorities as described in the Events API. This mechanism can be used to express exceptions. The following example will block all requests to images named "evil.jpg" except on the server "myserver.com".
var rule1 = { priority: 100, conditions: [ new chrome.declarativeWebRequest.RequestMatcher({ url: { pathEquals: 'evil.jpg' } }) ], actions: [ new chrome.declarativeWebRequest.CancelRequest() ] }; var rule2 = { priority: 1000, conditions: [ new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: '.myserver.com' } }) ], actions: [ new chrome.declarativeWebRequest.IgnoreRules({ lowerPriorityThan: 1000 }) ] }; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
It is important to recognize that the IgnoreRules
action is not
persisted across request stages. All conditions of
all rules are evaluated at each stage of a web request. If an
IgnoreRules
action is executed, it applies only to other actions
that are executed for the same web request in the same stage.
Summary
Types
Stage
Enum |
---|
"onBeforeRequest" ,
"onBeforeSendHeaders" ,
"onHeadersReceived" ,
or "onAuthRequired"
|
HeaderFilter
properties | ||
---|---|---|
string | (optional) namePrefix |
Matches if the header name starts with the specified string. |
string | (optional) nameSuffix |
Matches if the header name ends with the specified string. |
array of string or string | (optional) nameContains |
Matches if the header name contains all of the specified strings. |
string | (optional) nameEquals |
Matches if the header name is equal to the specified string. |
string | (optional) valuePrefix |
Matches if the header value starts with the specified string. |
string | (optional) valueSuffix |
Matches if the header value ends with the specified string. |
array of string or string | (optional) valueContains |
Matches if the header value contains all of the specified strings. |
string | (optional) valueEquals |
Matches if the header value is equal to the specified string. |
RequestMatcher
properties | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | (optional) url |
Matches if the conditions of the UrlFilter are fulfilled for the URL of the request.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object | (optional) firstPartyForCookiesUrl |
Deprecated since Chrome 84. Ignored since release 82. Matches if the conditions of the UrlFilter are fulfilled for the 'first party' URL of the request. The 'first party' URL of a request, when present, can be different from the request's target URL, and describes what is considered 'first party' for the sake of third-party checks for cookies.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
array of webRequest.ResourceType | (optional) resourceType |
Matches if the request type of a request is contained in the list. Requests that cannot match any of the types will be filtered out. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
array of string | (optional) contentType |
Matches if the MIME media type of a response (from the HTTP Content-Type header) is contained in the list. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
array of string | (optional) excludeContentType |
Matches if the MIME media type of a response (from the HTTP Content-Type header) is not contained in the list. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
array of HeaderFilter | (optional) requestHeaders |
Matches if some of the request headers is matched by one of the HeaderFilters. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
array of HeaderFilter | (optional) excludeRequestHeaders |
Matches if none of the request headers is matched by any of the HeaderFilters. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
array of HeaderFilter | (optional) responseHeaders |
Matches if some of the response headers is matched by one of the HeaderFilters. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
array of HeaderFilter | (optional) excludeResponseHeaders |
Matches if none of the response headers is matched by any of the HeaderFilters. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
boolean | (optional) thirdPartyForCookies |
If set to true, matches requests that are subject to third-party cookie policies. If set to false, matches all other requests. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
array of Stage | (optional) stages |
Contains a list of strings describing stages. Allowed values are 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'. If this attribute is present, then it limits the applicable stages to those listed. Note that the whole condition is only applicable in stages compatible with all attributes. |
CancelRequest
RedirectRequest
properties | ||
---|---|---|
string | redirectUrl |
Destination to where the request is redirected. |
RedirectToTransparentImage
RedirectToEmptyDocument
RedirectByRegEx
properties | ||
---|---|---|
string | from |
A match pattern that may contain capture groups. Capture groups are referenced in the Perl syntax ($1, $2, ...) instead of the RE2 syntax (\1, \2, ...) in order to be closer to JavaScript Regular Expressions. |
string | to |
Destination pattern. |
SetRequestHeader
properties | ||
---|---|---|
string | name |
HTTP request header name. |
string | value |
HTTP request header value. |
RemoveRequestHeader
properties | ||
---|---|---|
string | name |
HTTP request header name (case-insensitive). |
AddResponseHeader
properties | ||
---|---|---|
string | name |
HTTP response header name. |
string | value |
HTTP response header value. |
RemoveResponseHeader
properties | ||
---|---|---|
string | name |
HTTP request header name (case-insensitive). |
string | (optional) value |
HTTP request header value (case-insensitive). |
IgnoreRules
properties | ||
---|---|---|
integer | (optional) lowerPriorityThan |
If set, rules with a lower priority than the specified value are ignored. This boundary is not persisted, it affects only rules and their actions of the same network request stage. |
string | (optional) hasTag |
If set, rules with the specified tag are ignored. This ignoring is not persisted, it affects only rules and their actions of the same network request stage. Note that rules are executed in descending order of their priorities. This action affects rules of lower priority than the current rule. Rules with the same priority may or may not be ignored. |
SendMessageToExtension
properties | ||
---|---|---|
string | message |
The value that will be passed in the |
RequestCookie
properties | ||
---|---|---|
string | (optional) name |
Name of a cookie. |
string | (optional) value |
Value of a cookie, may be padded in double-quotes. |
ResponseCookie
properties | ||
---|---|---|
string | (optional) name |
Name of a cookie. |
string | (optional) value |
Value of a cookie, may be padded in double-quotes. |
string | (optional) expires |
Value of the Expires cookie attribute. |
double | (optional) maxAge |
Value of the Max-Age cookie attribute |
string | (optional) domain |
Value of the Domain cookie attribute. |
string | (optional) path |
Value of the Path cookie attribute. |
string | (optional) secure |
Existence of the Secure cookie attribute. |
string | (optional) httpOnly |
Existence of the HttpOnly cookie attribute. |
FilterResponseCookie
properties | ||
---|---|---|
string | (optional) name |
Name of a cookie. |
string | (optional) value |
Value of a cookie, may be padded in double-quotes. |
string | (optional) expires |
Value of the Expires cookie attribute. |
double | (optional) maxAge |
Value of the Max-Age cookie attribute |
string | (optional) domain |
Value of the Domain cookie attribute. |
string | (optional) path |
Value of the Path cookie attribute. |
string | (optional) secure |
Existence of the Secure cookie attribute. |
string | (optional) httpOnly |
Existence of the HttpOnly cookie attribute. |
integer | (optional) ageUpperBound |
Inclusive upper bound on the cookie lifetime (specified in seconds after current time). Only cookies whose expiration date-time is in the interval [now, now + ageUpperBound] fulfill this criterion. Session cookies and cookies whose expiration date-time is in the past do not meet the criterion of this filter. The cookie lifetime is calculated from either 'max-age' or 'expires' cookie attributes. If both are specified, 'max-age' is used to calculate the cookie lifetime. |
integer | (optional) ageLowerBound |
Inclusive lower bound on the cookie lifetime (specified in seconds after current time). Only cookies whose expiration date-time is set to 'now + ageLowerBound' or later fulfill this criterion. Session cookies do not meet the criterion of this filter. The cookie lifetime is calculated from either 'max-age' or 'expires' cookie attributes. If both are specified, 'max-age' is used to calculate the cookie lifetime. |
boolean | (optional) sessionCookie |
Filters session cookies. Session cookies have no lifetime specified in any of 'max-age' or 'expires' attributes. |
AddRequestCookie
properties | ||
---|---|---|
declarativeWebRequest.RequestCookie | cookie |
Cookie to be added to the request. No field may be undefined. |
AddResponseCookie
properties | ||
---|---|---|
declarativeWebRequest.ResponseCookie | cookie |
Cookie to be added to the response. The name and value need to be specified. |
EditRequestCookie
properties | ||
---|---|---|
declarativeWebRequest.RequestCookie | filter |
Filter for cookies that will be modified. All empty entries are ignored. |
declarativeWebRequest.RequestCookie | modification |
Attributes that shall be overridden in cookies that machted the filter. Attributes that are set to an empty string are removed. |
EditResponseCookie
properties | ||
---|---|---|
declarativeWebRequest.FilterResponseCookie | filter |
Filter for cookies that will be modified. All empty entries are ignored. |
declarativeWebRequest.ResponseCookie | modification |
Attributes that shall be overridden in cookies that machted the filter. Attributes that are set to an empty string are removed. |
RemoveRequestCookie
properties | ||
---|---|---|
declarativeWebRequest.RequestCookie | filter |
Filter for cookies that will be removed. All empty entries are ignored. |
RemoveResponseCookie
properties | ||
---|---|---|
declarativeWebRequest.FilterResponseCookie | filter |
Filter for cookies that will be removed. All empty entries are ignored. |
Events
onRequest
Provides the Declarative Event API consisting of addRules, removeRules, and getRules.
chrome.declarativeWebRequest.onRequest.addRules(array of Rule rules, function callback)
chrome.declarativeWebRequest.onRequest.removeRules(array of string ruleIdentifiers, function callback)
chrome.declarativeWebRequest.onRequest.getRules(array of string ruleIdentifiers, function callback)
Supported conditions
Supported actions
onMessage
Fired when a message is sent via declarativeWebRequest.SendMessageToExtension from an action of the declarative web request API.
addListener
chrome.declarativeWebRequest.onMessage.addListener(function callback)
Parameters | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function(object details) {...};
|