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