| OLD | NEW |
|---|
| (Empty) |
| 1 <!-- BEGIN AUTHORED CONTENT --> | |
| 2 <h2 id="notes">Notes</h2> | |
| 3 <p> | |
| 4 Use the <code>chrome.declarativeWebRequest</code> module to intercept, block, or | |
| 5 modify requests in-flight. It is significantly faster than the <a | |
| 6 href="webRequest.html"><code>chrome.webRequest</code> API</a> because you can | |
| 7 register rules that are evaluated in the browser rather than the | |
| 8 JavaScript engine which reduces roundtrip latencies and allows for very high | |
| 9 efficiency. | |
| 10 </p> | |
| 11 <h2 id="manifest">Manifest</h2> | |
| 12 <p> | |
| 13 You must declare the "declarative" and the "declarativeWebRequest" permission in | |
| 14 the <a href="manifest.html">extension manifest</a> to use this API, | |
| 15 along with <a href="manifest.html#permissions">host permissions</a> for any | |
| 16 hosts whose network requests you want to access. | |
| 17 </p> | |
| 18 <pre>{ | |
| 19 "name": "My extension", | |
| 20 ... | |
| 21 <b> "permissions": [ | |
| 22 "declarative", | |
| 23 "declarativeWebRequest", | |
| 24 "*://*.google.com" | |
| 25 ]</b>, | |
| 26 ... | |
| 27 }</pre> | |
| 28 <h2 id="rules">Rules</h2> | |
| 29 <p> | |
| 30 The Declarative Web Request API follows the concepts of the <a | |
| 31 href="events.html#declarative">Declarative API</a>. You can register rules to | |
| 32 the <code>chrome.declarativeWebRequest.onRequest</code> event object. | |
| 33 </p> | |
| 34 <p> | |
| 35 The Declarative Web Request API supports a single type of match criteria, the | |
| 36 <code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network | |
| 37 requests if and only if all listed criteria are met. The following | |
| 38 <code>RequestMatcher</code> would match a network request when the user enters | |
| 39 "http://www.example.com" in the URL bar: | |
| 40 </p> | |
| 41 <pre> | |
| 42 var matcher = new chrome.declarativeWebRequest.RequestMatcher({ | |
| 43 url: { hostSuffix: 'example.com', schemes: ['http'] }, | |
| 44 resourceType: 'main_frame' | |
| 45 }); | |
| 46 </pre> | |
| 47 <p> | |
| 48 Requests to "https://www.example.com" would be rejected by the | |
| 49 <code>RequestMatcher</code> due to the scheme. Also all requests for an embedded | |
| 50 iframe would be rejected due to the <code>resourceType</code>. | |
| 51 </p> | |
| 52 <p class="note"> | |
| 53 <strong>Note:</strong> All conditions and actions are created via a constructor | |
| 54 as shown in the example above. | |
| 55 <p> | |
| 56 <p> | |
| 57 In order to cancel all requests to "example.com", you can define a rule as | |
| 58 follows: | |
| 59 </p> | |
| 60 <pre> | |
| 61 var rule = { | |
| 62 conditions: [ | |
| 63 new chrome.declarativeWebRequest.RequestMatcher({ | |
| 64 url: { hostSuffix: 'example.com' } }) | |
| 65 ], | |
| 66 actions: [ | |
| 67 new chrome.declarativeWebRequest.CancelRequest() | |
| 68 ]}; | |
| 69 </pre> | |
| 70 <p> | |
| 71 In order to cancel all requests to "example.com" and "foobar.com", you can add a | |
| 72 second condition, as each condition is sufficient to trigger all specified | |
| 73 actions: | |
| 74 </p> | |
| 75 <pre> | |
| 76 var rule2 = { | |
| 77 conditions: [ | |
| 78 new chrome.declarativeWebRequest.RequestMatcher({ | |
| 79 url: { hostSuffix: 'example.com' } }), | |
| 80 new chrome.declarativeWebRequest.RequestMatcher({ | |
| 81 url: { hostSuffix: 'foobar.com' } }) | |
| 82 ], | |
| 83 actions: [ | |
| 84 new chrome.declarativeWebRequest.CancelRequest() | |
| 85 ]}; | |
| 86 </pre> | |
| 87 <p> | |
| 88 Register rules as follows: | |
| 89 </p> | |
| 90 <pre> | |
| 91 chrome.declarativeWebRequest.onRequest.addRules([rule2]); | |
| 92 </pre> | |
| 93 <p class="note"> | |
| 94 <strong>Note:</strong> You should always register or unregister rules in bulk ra
ther than | |
| 95 individually because each of these operations recreates internal data | |
| 96 structures. This re-creation is computationally expensive but facilitates a | |
| 97 very fast URL matching algorithm for hundreds of thousands of URLs. | |
| 98 </p> | |
| 99 <h2 id="TODO">Todo</h2> | |
| 100 <ul> | |
| 101 <li>Explain precedences, once we can ignore rules based on their priority | |
| 102 (e.g. how can I cancel all requests except for a specific whitelist?) | |
| 103 <li>Explain when conditions can be evaluated, when actions can be executed, | |
| 104 and when rules can be executed (e.g. you cannot cancel a request when you | |
| 105 have received the response already) | |
| 106 </ul> | |
| 107 <!-- 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