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 |