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

   1 <h2 id="manifest">Manifest</h2>
   2
   3 <p>
   4 You must declare the "declarativeWebRequest" permission in the
   5 <a href="manifest">extension manifest</a> to use this API,
   6 along with <a href="declare_permissions">host permissions</a>.
   7 </p>
   8
   9 <pre data-filename="manifest.json">
  10 {
  11   "name": "My extension",
  12   ...
  13 <b>  "permissions": [
  14     "declarativeWebRequest",
  15     "*://*/*"
  16   ]</b>,
  17   ...
  18 }
  19 </pre>
  20
  21 <p>
  22 Note that certain types of non-sensitive actions do not require host
  23 permissions:
  24 <ul>
  25   <li><code>CancelRequest</code>
  26   <li><code>IgnoreRules</code>
  27   <li><code>RedirectToEmptyDocument</code>
  28   <li><code>RedirectToTransparentImage</code>
  29 </ul>
  30 </p>
  31 <p>
  32 The <code>SendMessageToExtension</code> action requires host permissions
  33 for any hosts whose network requests you want to trigger a message.
  34 </p>
  35 <p>
  36 All other actions require host permissions to all URLs.
  37 </p>
  38 <p>
  39 As an example, if <code>"*://*.google.com/*"</code> is the only host permission
  40 an extension has, than such an extension may set up a rule to
  41 <ul>
  42   <li> cancel a request to "http://www.google.com" or "http://anything.else.com"
  43   <li> send a message when navigating to "http://www.google.com" but not to
  44 "http://something.else.com"
  45 </ul>
  46 The extension cannot set up a rule to redirect "http://www.google.com" to
  47 "http://mail.google.com".
  48 </p>
  49
  50 <h2 id="rules">Rules</h2>
  51
  52 <p>
  53 The Declarative Web Request API follows the concepts of the <a
  54   href="events#declarative">Declarative API</a>. You can register rules to
  55 the <code>chrome.declarativeWebRequest.onRequest</code> event object.
  56 </p>
  57
  58 <p>
  59 The Declarative Web Request API supports a single type of match criteria, the
  60 <code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network
  61 requests if and only if all listed criteria are met. The following
  62 <code>RequestMatcher</code> would match a network request when the user enters
  63 "http://www.example.com" in the URL bar:
  64 </p>
  65
  66 <pre>
  67 var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  68   url: { hostSuffix: 'example.com', schemes: ['http'] },
  69   resourceType: ['main_frame']
  70   });
  71 </pre>
  72
  73 <p>
  74 Requests to "https://www.example.com" would be rejected by the
  75 <code>RequestMatcher</code> due to the scheme. Also all requests for an embedded
  76 iframe would be rejected due to the <code>resourceType</code>.
  77 </p>
  78
  79 <p class="note">
  80 <strong>Note:</strong> All conditions and actions are created via a constructor
  81 as shown in the example above.
  82 <p>
  83
  84 <p>
  85 In order to cancel all requests to "example.com", you can define a rule as
  86 follows:
  87 </p>
  88 <pre>
  89 var rule = {
  90   conditions: [
  91     new chrome.declarativeWebRequest.RequestMatcher({
  92       url: { hostSuffix: 'example.com' } })
  93   ],
  94   actions: [
  95     new chrome.declarativeWebRequest.CancelRequest()
  96   ]};
  97 </pre>
  98
  99 <p>
 100 In order to cancel all requests to "example.com" and "foobar.com", you can add a
 101 second condition, as each condition is sufficient to trigger all specified
 102 actions:
 103 </p>
 104 <pre>
 105 var rule2 = {
 106   conditions: [
 107     new chrome.declarativeWebRequest.RequestMatcher({
 108       url: { hostSuffix: 'example.com' } }),
 109     new chrome.declarativeWebRequest.RequestMatcher({
 110       url: { hostSuffix: 'foobar.com' } })
 111   ],
 112   actions: [
 113     new chrome.declarativeWebRequest.CancelRequest()
 114   ]};
 115 </pre>
 116
 117 <p>
 118 Register rules as follows:
 119 </p>
 120 <pre>
 121 chrome.declarativeWebRequest.onRequest.addRules([rule2]);
 122 </pre>
 123
 124 <p class="note">
 125 <strong>Note:</strong> You should always register or unregister rules in bulk rather than
 126 individually because each of these operations recreates internal data
 127 structures.  This re-creation is computationally expensive but facilitates a
 128 very fast URL matching algorithm for hundreds of thousands of URLs. The
 129 <a href="events#performance">Performance section</a> of the
 130 $(ref:events Events) API provides further performance tips.
 131 </p>
 132
 133
 134 <h2 id="evaluation">Evaluation of conditions and actions</h2>
 135
 136 <p>
 137 The Declarative Web Request API follows the
 138 <a href="webRequest#life_cycle">Life cycle model for web requests</a> of
 139 the <a href="webRequest">Web Request API</a>. This means that conditions
 140 can only be tested at specific stages of a web request and, likewise, actions
 141 can also only be executed at specific stages. The following tables list the
 142 request stages that are compatible with conditions and actions.
 143 </p>
 144
 145 <p>
 146 <table>
 147   <tr>
 148     <th colspan="5">Request stages during which condition attributes can be processed.
 149   </tr>
 150   <tr>
 151     <th>Condition attribute
 152     <th>onBeforeRequest
 153     <th>onBeforeSendHeaders
 154     <th>onHeadersReceived
 155     <th>onAuthRequired
 156   </tr>
 157   <tr><td>url<td>✓<td>✓<td>✓<td>✓
 158   <tr><td>resourceType<td>✓<td>✓<td>✓<td>✓
 159   <tr><td>contentType<td><td><td>✓<td>
 160   <tr><td>excludeContentType<td><td><td>✓<td>
 161   <tr><td>responseHeaders<td><td><td>✓<td>
 162   <tr><td>excludeResponseHeaders<td><td><td>✓<td>
 163   <tr><td>requestHeaders<td><td>✓<td><td>
 164   <tr><td>excludeRequestHeaders<td><td>✓<td><td>
 165   <tr><td>thirdPartyForCookies<td>✓<td>✓<td>✓<td>✓
 166   <tr>
 167     <th colspan="5" style="padding-top:2em">Request stages during which actions can be executed.
 168   </tr>
 169   <tr>
 170     <th>Event
 171     <th>onBeforeRequest
 172     <th>onBeforeSendHeaders
 173     <th>onHeadersReceived
 174     <th>onAuthRequired
 175   </tr>
 176   <tr><td>AddRequestCookie<td><td>✓<td><td>
 177   <tr><td>AddResponseCookie<td><td><td>✓<td>
 178   <tr><td>AddResponseHeader<td><td><td>✓<td>
 179   <tr><td>CancelRequest<td>✓<td>✓<td>✓<td>✓
 180   <tr><td>EditRequestCookie<td><td>✓<td><td>
 181   <tr><td>EditResponseCookie<td><td><td>✓<td>
 182   <tr><td>IgnoreRules<td>✓<td>✓<td>✓<td>✓
 183   <tr><td>RedirectByRegEx<td>✓<td><td>✓<td>
 184   <tr><td>RedirectRequest<td>✓<td><td>✓<td>
 185   <tr><td>RedirectToEmptyDocument<td>✓<td><td>✓<td>
 186   <tr><td>RedirectToTransparentImage<td>✓<td><td>✓<td>
 187   <tr><td>RemoveRequestCookie<td><td>✓<td><td>
 188   <tr><td>RemoveRequestHeader<td><td>✓<td><td>
 189   <tr><td>RemoveResponseCookie<td><td><td>✓<td>
 190   <tr><td>RemoveResponseHeader<td><td><td>✓<td>
 191   <tr><td>SendMessageToExtension<td>✓<td>✓<td>✓<td>✓
 192   <tr><td>SetRequestHeader<td><td>✓<td><td>
 193 </table>
 194 </p>
 195
 196 <p>
 197 <strong>Note:</strong> Applicable stages can be further constrained by using the
 198 "stages" attribute.
 199 </p>
 200 <p>
 201 <strong>Note:</strong> Redirects initiated by a redirect action use the original
 202 request method for the redirect, with one exception: If the redirect is
 203 initiated at the onHeadersReceived stage, then the redirect will be issued using
 204 the GET method.
 205 </p>
 206 <p>
 207 <strong>Example:</strong> It is possible to combine a
 208 <code>new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})</code>
 209 condition with a <code>new chrome.declarativeWebRequest.CancelRequest()</code>
 210 action because both of them can be evaluated in the onHeadersReceived stage.
 211 It is, however, impossible to combine the request matcher with a
 212 <code>new chrome.declarativeWebRequest.SetRequestHeader()</code>
 213 because request headers cannot be set any more by the time the content type has been terminated.
 214 </p>
 215
 216 <h2 id="precedences">Using priorities to override rules</h2>
 217
 218 <p>
 219 Rules can be associated with priorities as described in the
 220 <a href="events#declarative">Events API</a>. This mechanism can be used
 221 to express exceptions. The following example will block all requests to
 222 images named "evil.jpg" except on the server "myserver.com".
 223 </p>
 224
 225 <pre>
 226 var rule1 = {
 227   priority: 100,
 228   conditions: [
 229     new chrome.declarativeWebRequest.RequestMatcher({
 230         url: { pathEquals: 'evil.jpg' } })
 231   ],
 232   actions: [
 233     new chrome.declarativeWebRequest.CancelRequest()
 234   ]
 235 };
 236 var rule2 = {
 237   priority: 1000,
 238   conditions: [
 239     new chrome.declarativeWebRequest.RequestMatcher({
 240       url: { hostSuffix: '.myserver.com' } })
 241   ],
 242   actions: [
 243     new chrome.declarativeWebRequest.IgnoreRules({
 244       lowerPriorityThan: 1000 })
 245   ]
 246 };
 247 chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
 248 </pre>
 249
 250 <p>
 251 It is important to recognize that the <code>IgnoreRules</code> action is not
 252 persisted across <a href="#evaluation">request stages</a>. All conditions of
 253 all rules are evaluated at each stage of a web request. If an
 254 <code>IgnoreRules</code> action is executed, it applies only to other actions
 255 that are executed for the same web request in the same stage.
 256 </p>