| 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 10700118:
Extensions Docs Server: First doc conversions (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src