Notes

Use the chrome.declarativeWebRequest module 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 very high efficiency.

Manifest

You must declare the "declarativeWebRequest" permission in the extension manifest to use this API, along with host permissions for any hosts whose network requests you want to access. 

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*.google.com"
  ],
  ...
}

Note that certain types of non-sensitive requests do not require host permissions:

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.

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✓
SetRequestHeader✓

Note: Applicable stages can be further constrained by using the "stages" attribute.

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.RedirectToTransparentImage() because redirects cannot be executed any more by the time the content type has been determined.

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.