src/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.html">extension manifest</a> to use this API,
   6 along with <a href="declare_permissions.html">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.html#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.html#performance">Performance section</a> of the $ref:[events
 130 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.html#life_cycle">Life cycle model for web requests</a> of
 139 the <a href="webRequest.html">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>Example:</strong> It is possible to combine a
 202 <code>new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})</code>
 203 condition with a <code>new chrome.declarativeWebRequest.CancelRequest()</code>
 204 action because both of them can be evaluated in the onHeadersReceived stage.
 205 It is, however, impossible to combine the request matcher with a
 206 <code>new chrome.declarativeWebRequest.RedirectToTransparentImage()</code>
 207 because redirects cannot be executed any more by the time the content
 208 type has been determined.
 209 </p>
 210
 211 <h2 id="precedences">Using priorities to override rules</h2>
 212
 213 <p>
 214 Rules can be associated with priorities as described in the
 215 <a href="events.html#declarative">Events API</a>. This mechanism can be used
 216 to express exceptions. The following example will block all requests to
 217 images named "evil.jpg" except on the server "myserver.com".
 218 </p>
 219
 220 <pre>
 221 var rule1 = {
 222   priority: 100,
 223   conditions: [
 224     new chrome.declarativeWebRequest.RequestMatcher({
 225         url: { pathEquals: 'evil.jpg' } })
 226   ],
 227   actions: [
 228     new chrome.declarativeWebRequest.CancelRequest()
 229   ]
 230 };
 231 var rule2 = {
 232   priority: 1000,
 233   conditions: [
 234     new chrome.declarativeWebRequest.RequestMatcher({
 235       url: { hostSuffix: '.myserver.com' } })
 236   ],
 237   actions: [
 238     new chrome.declarativeWebRequest.IgnoreRules({
 239       lowerPriorityThan: 1000 })
 240   ]
 241 };
 242 chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
 243 </pre>
 244
 245 <p>
 246 It is important to recognize that the <code>IgnoreRules</code> action is not
 247 persisted across <a href="#evaluation">request stages</a>. All conditions of
 248 all rules are evaluated at each stage of a web request. If an
 249 <code>IgnoreRules</code> action is executed, it applies only to other actions
 250 that are executed for the same web request in the same stage.
 251 </p>