• Getting Started
• Overview
• What's New?
• Developer's Guide
  • Browser UI
    • Browser Actions
    • Context Menus
    • Desktop Notifications
    • Omnibox
    • Options Pages
    • Override Pages
    • Page Actions
  • Browser Interaction
    • Bookmarks
    • Cookies
    • Developer Tools
    • Events
    • History
    • Management
    • Tabs
    • Windows
  • Implementation
    • Accessibility
    • Event Pages
    • Content Security Policy
    • Content Scripts
    • Cross-Origin XHR
    • Internationalization
    • Message Passing
    • Optional Permissions
    • NPAPI Plugins
  • Finishing
    • Hosting
    • Other Deployment Options
• Tutorials
  • Manifest V2
  • Debugging
  • Google Analytics
  • OAuth
• Reference
  • Formats
    • Manifest Files
    • Match Patterns
  • Permission Warnings
  • chrome.* APIs
  • Other APIs
• More
  • FAQ
  • Chrome Web Store
  • Hosted Apps
  • Themes

chrome.declarativeWebRequest

This API is in beta. It is only available to Chrome users on the beta channel and dev channel.

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.

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

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.

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.

chrome.declarativeWebRequest reference

Sample Extensions that use chrome.declarativeWebRequest