chrome/common/extensions/docs/templates/intros/declarativeWebRequest.html

<h2 id="manifest">Manifest</h2>

<p>
You must declare the "declarativeWebRequest" permission in the
<a href="manifest.html">extension manifest</a> to use this API,
along with <a href="declare_permissions.html">host permissions</a>.
</p>

<pre>{
  "name": "My extension",
  ...
<b>  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ]</b>,
  ...
}</pre>

<p>
Note that certain types of non-sensitive actions do not require host
permissions:
<ul>
  <li><code>CancelRequest</code>
  <li><code>IgnoreRules</code>
  <li><code>RedirectToEmptyDocument</code>
  <li><code>RedirectToTransparentImage</code>
</ul>
</p>
<p>
The <code>SendMessageToExtension</code> action requires host permissions
for any hosts whose network requests you want to trigger a message.
</p>
<p>
All other actions require host permissions to all URLs.
</p>
<p>
As an example, if <code>"*://*.google.com/*"</code> is the only host permission
an extension has, than such an extension may set up a rule to
<ul>
  <li> cancel a request to "http://www.google.com" or "http://anything.else.com"
  <li> send a message when navigating to "http://www.google.com" but not to
"http://something.else.com"
</ul>
The extension cannot set up a rule to redirect "http://www.google.com" to
"http://mail.google.com".
</p>

<h2 id="rules">Rules</h2>

<p>
The Declarative Web Request API follows the concepts of the <a
  href="events.html#declarative">Declarative API</a>. You can register rules to
the <code>chrome.declarativeWebRequest.onRequest</code> event object.
</p>

<p>
The Declarative Web Request API supports a single type of match criteria, the
<code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network
requests if and only if all listed criteria are met. The following
<code>RequestMatcher</code> would match a network request when the user enters
"http://www.example.com" in the URL bar:
</p>

<pre>
var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
  });
</pre>

<p>
Requests to "https://www.example.com" would be rejected by the
<code>RequestMatcher</code> due to the scheme. Also all requests for an embedded
iframe would be rejected due to the <code>resourceType</code>.
</p>

<p class="note">
<strong>Note:</strong> All conditions and actions are created via a constructor
as shown in the example above.
<p>

<p>
In order to cancel all requests to "example.com", you can define a rule as
follows:
</p>
<pre>
var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]};
</pre>

<p>
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:
</p>
<pre>
var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]};
</pre>

<p>
Register rules as follows:
</p>
<pre>
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
</pre>

<p class="note">
<strong>Note:</strong> 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
<a href="events.html#performance">Performance section</a> of the $ref:[events
Events] API provides further performance tips.
</p>


<h2 id="evaluation">Evaluation of conditions and actions</h2>

<p>
The Declarative Web Request API follows the
<a href="webRequest.html#life_cycle">Life cycle model for web requests</a> of
the <a href="webRequest.html">Web Request API</a>. 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.
</p>

<p>
<table>
  <tr>
    <th colspan="5">Request stages during which condition attributes can be processed.
  </tr>
  <tr>
    <th>Condition attribute
    <th>onBeforeRequest
    <th>onBeforeSendHeaders
    <th>onHeadersReceived
    <th>onAuthRequired
  </tr>
  <tr><td>url<td>✓<td>✓<td>✓<td>✓
  <tr><td>resourceType<td>✓<td>✓<td>✓<td>✓
  <tr><td>contentType<td><td><td>✓<td>
  <tr><td>excludeContentType<td><td><td>✓<td>
  <tr><td>responseHeaders<td><td><td>✓<td>
  <tr><td>excludeResponseHeaders<td><td><td>✓<td>
  <tr><td>requestHeaders<td><td>✓<td><td>
  <tr><td>excludeRequestHeaders<td><td>✓<td><td>
  <tr><td>thirdPartyForCookies<td>✓<td>✓<td>✓<td>✓
  <tr>
    <th colspan="5" style="padding-top:2em">Request stages during which actions can be executed.
  </tr>
  <tr>
    <th>Event
    <th>onBeforeRequest
    <th>onBeforeSendHeaders
    <th>onHeadersReceived
    <th>onAuthRequired
  </tr>
  <tr><td>AddRequestCookie<td><td>✓<td><td>
  <tr><td>AddResponseCookie<td><td><td>✓<td>
  <tr><td>AddResponseHeader<td><td><td>✓<td>
  <tr><td>CancelRequest<td>✓<td>✓<td>✓<td>✓
  <tr><td>EditRequestCookie<td><td>✓<td><td>
  <tr><td>EditResponseCookie<td><td><td>✓<td>
  <tr><td>IgnoreRules<td>✓<td>✓<td>✓<td>✓
  <tr><td>RedirectByRegEx<td>✓<td><td><td>
  <tr><td>RedirectRequest<td>✓<td><td><td>
  <tr><td>RedirectToEmptyDocument<td>✓<td><td><td>
  <tr><td>RedirectToTransparentImage<td>✓<td><td><td>
  <tr><td>RemoveRequestCookie<td><td>✓<td><td>
  <tr><td>RemoveRequestHeader<td><td>✓<td><td>
  <tr><td>RemoveResponseCookie<td><td><td>✓<td>
  <tr><td>RemoveResponseHeader<td><td><td>✓<td>
  <tr><td>SendMessageToExtension<td>✓<td>✓<td>✓<td>✓
  <tr><td>SetRequestHeader<td><td>✓<td><td>
</table>
</p>

<p>
<strong>Note:</strong> Applicable stages can be further constrained by using the
"stages" attribute.
</p>
<p>
<strong>Example:</strong> It is possible to combine a
<code>new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})</code>
condition with a <code>new chrome.declarativeWebRequest.CancelRequest()</code>
action because both of them can be evaluated in the onHeadersReceived stage.
It is, however, impossible to combine the request matcher with a
<code>new chrome.declarativeWebRequest.RedirectToTransparentImage()</code>
because redirects cannot be executed any more by the time the content
type has been determined.
</p>

<h2 id="precedences">Using priorities to override rules</h2>

<p>
Rules can be associated with priorities as described in the
<a href="events.html#declarative">Events API</a>. 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".
</p>

<pre>
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]);
</pre>

<p>
It is important to recognize that the <code>IgnoreRules</code> action is not
persisted across <a href="#evaluation">request stages</a>. All conditions of
all rules are evaluated at each stage of a web request. If an
<code>IgnoreRules</code> action is executed, it applies only to other actions
that are executed for the same web request in the same stage.
</p>