chrome.declarativeWebRequest

Contents

1. Notes
2. Manifest
3. Rules
4. Todo
5. API reference: chrome.declarativeWebRequest
   1. Events
      1. onRequest
   2. Types
      1. declarativeWebRequest.RedirectByRegEx
      2. RequestMatcher
      3. RedirectRequest
      4. declarativeWebRequest.RedirectToTransparentImage
      5. declarativeWebRequest.RedirectToEmptyDocument
      6. CancelRequest
      7. declarativeWebRequest.SetRequestHeader
      8. declarativeWebRequest.RemoveRequestHeader
      9. declarativeWebRequest.AddResponseHeader
      10. declarativeWebRequest.RemoveResponseHeader
      11. declarativeWebRequest.IgnoreRules

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 for very high efficiency.

Manifest

You must declare the "declarative" and 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": [
    "declarative",
    "declarativeWebRequest",
    "*://*.google.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.

Todo

• Explain precedences, once we can ignore rules based on their priority (e.g. how can I cancel all requests except for a specific whitelist?)
• Explain when conditions can be evaluated, when actions can be executed, and when rules can be executed (e.g. you cannot cancel a request when you have received the response already)