| OLD | NEW |
|---|
| (Empty) |
| 1 <!-- BEGIN AUTHORED CONTENT --> | |
| 2 <p id="classSummary"> | |
| 3 Use the <code>chrome.webRequest</code> module to intercept, block, | |
| 4 or modify requests in-flight and to observe and analyze traffic. | |
| 5 </p> | |
| 6 <h2 id="manifest">Manifest</h2> | |
| 7 <p>You must declare the "webRequest" permission in the <a | |
| 8 href="manifest.html">extension manifest</a> to use the web request | |
| 9 API, along with <a href="manifest.html#permissions">host permissions</a> | |
| 10 for any hosts whose network requests you want to access. If you want to | |
| 11 use the web request API in a blocking fashion, you need to request | |
| 12 the "webRequestBlocking" permission in addition. | |
| 13 For example:</p> | |
| 14 <pre>{ | |
| 15 "name": "My extension", | |
| 16 ... | |
| 17 <b>"permissions": [ | |
| 18 "webRequest", | |
| 19 "*://*.google.com" | |
| 20 ]</b>, | |
| 21 ... | |
| 22 }</pre> | |
| 23 <p class="note"> | |
| 24 <b>Node:</b> If you request the "webRequestBlocking" permission, web requests | |
| 25 are delayed until the background page of your extension has been loaded. This | |
| 26 allows you to register event listeners before any web requests are processed. | |
| 27 In order to avoid deadlocks, you must not start synchronous XmlHttpRequests or | |
| 28 include scripts from the internet via <code><script src="..."></code> tags | |
| 29 in your background page. | |
| 30 </p> | |
| 31 <h2 id="life_cycle">Life cycle of requests</h2> | |
| 32 <p> | |
| 33 The web request API defines a set of events that follow the life cycle of a web | |
| 34 request. You can use these events to observe and analyze traffic. Certain | |
| 35 synchronous events will allow you to intercept, block, or modify a request. | |
| 36 </p> | |
| 37 <p> | |
| 38 The event life cycle for successful requests is illustrated here, followed by | |
| 39 event definitions:<br/> | |
| 40 <img src="{{static}}/images/webrequestapi.png" | |
| 41 width="385" height="503" | |
| 42 alt="Life cycle of a web request from the perspective of the webrequest API" | |
| 43 style="margin-left: auto; margin-right: auto; display: block"/> | |
| 44 </p> | |
| 45 <p> | |
| 46 <dl> | |
| 47 <dt><code>onBeforeRequest</code> (optionally synchronous)</dt> | |
| 48 <dd>Fires when a request is about to occur. This event is sent before any TCP | |
| 49 connection is made and can be used to cancel or redirect requests.</dd> | |
| 50 <dt><code>onBeforeSendHeaders</code> (optionally synchronous)</dt> | |
| 51 <dd>Fires when a request is about to occur and the initial headers have been | |
| 52 prepared. The event is intended to allow extensions to add, modify, and delete | |
| 53 request headers <a href="#life_cycle_footnote">(*)</a>. The | |
| 54 <code>onBeforeSendHeaders</code> event is passed to all subscribers, so | |
| 55 different subscribers may attempt to modify the request; see the <a | |
| 56 href="#implementation">Implementation details</a> section for how this is | |
| 57 handled. This event can be used to cancel the request.</dd> | |
| 58 <dt><code>onSendHeaders</code></dt> | |
| 59 <dd>Fires after all extensions have had a chance to modify the request | |
| 60 headers, and presents the final <a href="#life_cycle_footnote">(*)</a> | |
| 61 version. The event is triggered before the headers are sent to the network. | |
| 62 This event is informational and handled asynchronously. It does not allow | |
| 63 modifying or cancelling the request.</dd> | |
| 64 <dt><code>onHeadersReceived</code> (optionally synchronous)</dt> | |
| 65 <dd>Fires each time that an HTTP(S) response header is received. Due | |
| 66 to redirects and authentication requests this can happen multiple times per | |
| 67 request. This event is intended to allow extensions to add, modify, and delete | |
| 68 response headers, such as incoming Set-Cookie headers.</dd> | |
| 69 <dt><code>onAuthRequired</code> (optionally synchronous)</dt> | |
| 70 <dd>Fires when a request requires authentication of the user. This event can | |
| 71 be handled synchronously to provide authentication credentials. Note that | |
| 72 extensions may provide invalid credentials. Take care not to enter an infinite | |
| 73 loop by repeatedly providing invalid credentials.</dd> | |
| 74 <dt><code>onBeforeRedirect</code></dt> | |
| 75 <dd>Fires when a redirect is about to be executed. A redirection can be | |
| 76 triggered by an HTTP response code or by an extension. This event is | |
| 77 informational and handled asynchronously. It does not allow you to modify or | |
| 78 cancel the request. </dd> | |
| 79 <dt><code>onResponseStarted</code></dt> | |
| 80 <dd>Fires when the first byte of the response body is received. For HTTP | |
| 81 requests, this means that the status line and response headers are | |
| 82 available. This event is informational and handled asynchronously. It does not | |
| 83 allow modifying or cancelling the request.</dd> | |
| 84 <dt><code>onCompleted</code></dt> | |
| 85 <dd>Fires when a request has been processed successfully.</dd> | |
| 86 <dt><code>onErrorOccurred</code></dt> | |
| 87 <dd>Fires when a request could not be processed successfully.</dd> | |
| 88 </dl> | |
| 89 The web request API guarantees that for each request either | |
| 90 <code>onCompleted</code> or <code>onErrorOccurred</code> is fired as the final | |
| 91 event with one exception: If a request is redirected to a <code>data://</code> | |
| 92 URL, <code>onBeforeRedirect</code> is the last reported event. | |
| 93 </p> | |
| 94 <p id="life_cycle_footnote">(*) Note that the web request API presents an | |
| 95 abstraction of the network stack to the extension. Internally, one URL request | |
| 96 can be split into several HTTP requests (for example to fetch individual byte | |
| 97 ranges from a large file) or can be handled by the network stack without | |
| 98 communicating with the network. For this reason, the API does not provide the | |
| 99 final HTTP headers that are sent to the network. For example, all headers that | |
| 100 are related to caching are invisible to the extension.</p> | |
| 101 <p>The following headers are currently <b>not provided</b> to the | |
| 102 <code>onBeforeSendHeaders</code> event. This list is not guaranteed to be | |
| 103 complete nor stable. | |
| 104 <ul> | |
| 105 <li>Authorization</li> | |
| 106 <li>Cache-Control</li> | |
| 107 <li>Connection</li> | |
| 108 <li>Content-Length</li> | |
| 109 <li>Host</li> | |
| 110 <li>If-Modified-Since</li> | |
| 111 <li>If-None-Match</li> | |
| 112 <li>If-Range</li> | |
| 113 <li>Partial-Data</li> | |
| 114 <li>Pragma</li> | |
| 115 <li>Proxy-Authorization</li> | |
| 116 <li>Proxy-Connection</li> | |
| 117 <li>Transfer-Encoding</li> | |
| 118 </ul> | |
| 119 </p> | |
| 120 <p> | |
| 121 The webRequest API only exposes requests that the extension has | |
| 122 permission to see, given its | |
| 123 <a href="manifest.html#permissions">host permissions</a>. | |
| 124 Moreover, only the following schemes are accessible: | |
| 125 <code>http://</code>, | |
| 126 <code>https://</code>, | |
| 127 <code>ftp://</code>, | |
| 128 <code>file://</code>, or | |
| 129 <code>chrome-extension://</code>. | |
| 130 In addition, even certain requests with URLs using one of the above schemes | |
| 131 are hidden, e.g., | |
| 132 <code>chrome-extension://other_extension_id</code> where | |
| 133 <code>other_extension_id</code> is not the ID of the extension to handle | |
| 134 the request, | |
| 135 <code>https://www.google.com/chrome</code>, | |
| 136 and others (this list is not complete). | |
| 137 </p> | |
| 138 <h2 id="concepts">Concepts</h2> | |
| 139 <p>As the following sections explain, events in the web request API use request | |
| 140 IDs, and you can optionally specify filters and extra information when you | |
| 141 register event listeners.</p> | |
| 142 <h3 id="Request IDs">Request IDs</h3> | |
| 143 <p>Each request is identified by a request ID. This ID is unique within a | |
| 144 browser session and the context of an extension. It remains constant during the | |
| 145 the life cycle of a request and can be used to match events for the same | |
| 146 request. Note that several HTTP requests are mapped to one web request in case | |
| 147 of HTTP redirection or HTTP authentication.</p> | |
| 148 <h3 id="subscription">Registering event listeners</h3> | |
| 149 <p>To register an event listener for a web request, you use a variation on the | |
| 150 <a href="events.html">usual <code>addListener()</code> function</a>. | |
| 151 In addition to specifying a callback function, | |
| 152 you have to specify a filter argument and you may specify an optional extra info | |
| 153 argument.</p> | |
| 154 <p>The three arguments to the web request API's <code>addListener()</code> have | |
| 155 the following definitions:</p> | |
| 156 <pre> | |
| 157 var callback = function(details) {...}; | |
| 158 var filter = {...}; | |
| 159 var opt_extraInfoSpec = [...]; | |
| 160 </pre> | |
| 161 <p>Here's an example of listening for the <code>onBeforeRequest</code> | |
| 162 event:</p> | |
| 163 <pre> | |
| 164 chrome.webRequest.onBeforeRequest.addListener( | |
| 165 callback, filter, opt_extraInfoSpec); | |
| 166 </pre> | |
| 167 <p>Each <code>addListener()</code> call takes a mandatory callback function as | |
| 168 the first parameter. This callback function is passed a dictionary containing | |
| 169 information about the current URL request. The information in this dictionary | |
| 170 depends on the specific event type as well as the content of | |
| 171 <code>opt_extraInfoSpec</code>.</p> | |
| 172 <p>If the optional <code>opt_extraInfoSpec</code> array contains the string | |
| 173 <code>'blocking'</code> (only allowed for specific events), the callback | |
| 174 function is handled synchronously. That means that the request is blocked until | |
| 175 the callback function returns. In this case, the callback can return a <a | |
| 176 href="#type-webRequest.BlockingResponse">BlockingResponse</a> that determines
the further | |
| 177 life cycle of the request. Depending on the context, this response allows | |
| 178 cancelling or redirecting a request (<code>onBeforeRequest</code>), cancelling a | |
| 179 request or modifying headers (<code>onBeforeSendHeaders</code>, | |
| 180 <code>onHeadersReceived</code>), or providing authentication credentials | |
| 181 (<code>onAuthRequired</code>).</p> | |
| 182 <p>The <a href="#type-webRequest.RequestFilter">RequestFilter</a> | |
| 183 <code>filter</code> allows limiting the requests for which events are | |
| 184 triggered in various dimensions: | |
| 185 <dl> | |
| 186 <dt>URLs</dt> | |
| 187 <dd><a href="match_patterns.html">URL patterns</a> such as | |
| 188 <code>*://www.google.com/foo*bar</code>.</dd> | |
| 189 <dt>Types</dt> | |
| 190 <dd>Request types such as <code>main_frame</code> (a document that is loaded | |
| 191 for a top-level frame), <code>sub_frame</code> (a document that is loaded for | |
| 192 an embedded frame), and <code>image</code> (an image on a web site). | |
| 193 See <a href="#type-webRequest.RequestFilter">RequestFilter</a>.</dd> | |
| 194 <dt>Tab ID</dt> | |
| 195 <dd>The identifier for one tab.</dd> | |
| 196 <dt>Window ID</dt> | |
| 197 <dd>The identifier for a window.</dd> | |
| 198 </p> | |
| 199 <p>Depending on the event type, you can specify strings in | |
| 200 <code>opt_extraInfoSpec</code> to ask for additional information about the | |
| 201 request. This is used to provide detailed information on request's data only | |
| 202 if explicitly requested.</p> | |
| 203 <h2 id="implementation">Implementation details</h2> | |
| 204 <p>Several implementation details can be important to understand when developing | |
| 205 an extension that uses the web request API:</p> | |
| 206 <h3>Conflict resolution</h3> | |
| 207 <p>In the current implementation of the web request API, a request is considered | |
| 208 as cancelled if at least one extension instructs to cancel the request. If | |
| 209 an extension cancels a request, all extensions are notified by an | |
| 210 <code>onErrorOccurred</code> event. Only one extension is allowed to redirect a | |
| 211 request or modify a header at a time. If more than one extension attempts to | |
| 212 modify the request, the most recently installed extension wins and all others | |
| 213 are ignored. An extension is not notified if its instruction to modify or | |
| 214 redirect has been ignored.</p> | |
| 215 <h3>Caching</h3> | |
| 216 <p> | |
| 217 Chrome employs two caches — an on-disk cache and a very fast in-memory | |
| 218 cache. The lifetime of an in-memory cache is attached to the lifetime of a | |
| 219 render process, which roughly corresponds to a tab. Requests that are answered | |
| 220 from the in-memory cache are invisible to the web request API. If a request | |
| 221 handler changes its behavior (for example, the behavior according to which | |
| 222 requests are blocked), a simple page refresh might not respect this changed | |
| 223 behavior. To make sure the behavior change goes through, call | |
| 224 <code>handlerBehaviorChanged()</code> to flush the in-memory cache. But don't do | |
| 225 it often; flushing the cache is a very expensive operation. You don't need to | |
| 226 call <code>handlerBehaviorChanged()</code> after registering or unregistering an | |
| 227 event listener.</p> | |
| 228 <h3>Timestamps</h3> | |
| 229 <p> | |
| 230 The <code>timestamp</code> property of web request events is only guaranteed to | |
| 231 be <i>internally</i> consistent. Comparing one event to another event will give | |
| 232 you the correct offset between them, but comparing them to the current time | |
| 233 inside the extension (via <code>(new Date()).getTime()</code>, for instance) | |
| 234 might give unexpected results. | |
| 235 </p> | |
| 236 <h2 id="examples">Examples</h2> | |
| 237 <p>The following example illustrates how to block all requests to | |
| 238 <code>www.evil.com</code>:</p> | |
| 239 <pre> | |
| 240 chrome.webRequest.onBeforeRequest.addListener( | |
| 241 function(details) { | |
| 242 return {cancel: details.url.indexOf("://www.evil.com/") != -1}; | |
| 243 }, | |
| 244 {urls: ["<all_urls>"]}, | |
| 245 ["blocking"]); | |
| 246 </pre> | |
| 247 <p>As this function uses a blocking event handler, it requires the "webRequest" | |
| 248 as well as the "webRequestBlocking" permission in the manifest file.</p> | |
| 249 <p>The following example achieves the same goal in a more efficient way because | |
| 250 requests that are not targeted to <code>www.evil.com</code> do not need to be | |
| 251 passed to the extension:</p> | |
| 252 <pre> | |
| 253 chrome.webRequest.onBeforeRequest.addListener( | |
| 254 function(details) { return {cancel: true}; }, | |
| 255 {urls: ["*://www.evil.com/*"]}, | |
| 256 ["blocking"]); | |
| 257 </pre> | |
| 258 <p>The following example illustrates how to delete the User-Agent header from | |
| 259 all requests:</p> | |
| 260 <pre> | |
| 261 chrome.webRequest.onBeforeSendHeaders.addListener( | |
| 262 function(details) { | |
| 263 for (var i = 0; i < details.requestHeaders.length; ++i) { | |
| 264 if (details.requestHeaders[i].name === 'User-Agent') { | |
| 265 details.requestHeaders.splice(i, 1); | |
| 266 break; | |
| 267 } | |
| 268 } | |
| 269 return {requestHeaders: details.requestHeaders}; | |
| 270 }, | |
| 271 {urls: ["<all_urls>"]}, | |
| 272 ["blocking", "requestHeaders"]); | |
| 273 </pre> | |
| 274 <p> For more example code, see the <a href="samples.html#webrequest">web request | |
| 275 samples</a>.</p> | |
| 276 <!-- END AUTHORED CONTENT --> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10750017:
Extensions Docs Server: Intro data source (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src