OLD | NEW |
1 <h2 id="manifest">Manifest</h2> | 1 <h2 id="manifest">Manifest</h2> |
2 | 2 |
3 <p> | 3 <p> |
4 You must declare the "declarativeWebRequest" permission in the | 4 You must declare the "declarativeWebRequest" permission in the |
5 <a href="manifest.html">extension manifest</a> to use this API, | 5 <a href="manifest">extension manifest</a> to use this API, |
6 along with <a href="declare_permissions.html">host permissions</a>. | 6 along with <a href="declare_permissions">host permissions</a>. |
7 </p> | 7 </p> |
8 | 8 |
9 <pre data-filename="manifest.json"> | 9 <pre data-filename="manifest.json"> |
10 { | 10 { |
11 "name": "My extension", | 11 "name": "My extension", |
12 ... | 12 ... |
13 <b> "permissions": [ | 13 <b> "permissions": [ |
14 "declarativeWebRequest", | 14 "declarativeWebRequest", |
15 "*://*/*" | 15 "*://*/*" |
16 ]</b>, | 16 ]</b>, |
(...skipping 27 matching lines...) Expand all Loading... |
44 "http://something.else.com" | 44 "http://something.else.com" |
45 </ul> | 45 </ul> |
46 The extension cannot set up a rule to redirect "http://www.google.com" to | 46 The extension cannot set up a rule to redirect "http://www.google.com" to |
47 "http://mail.google.com". | 47 "http://mail.google.com". |
48 </p> | 48 </p> |
49 | 49 |
50 <h2 id="rules">Rules</h2> | 50 <h2 id="rules">Rules</h2> |
51 | 51 |
52 <p> | 52 <p> |
53 The Declarative Web Request API follows the concepts of the <a | 53 The Declarative Web Request API follows the concepts of the <a |
54 href="events.html#declarative">Declarative API</a>. You can register rules to | 54 href="events#declarative">Declarative API</a>. You can register rules to |
55 the <code>chrome.declarativeWebRequest.onRequest</code> event object. | 55 the <code>chrome.declarativeWebRequest.onRequest</code> event object. |
56 </p> | 56 </p> |
57 | 57 |
58 <p> | 58 <p> |
59 The Declarative Web Request API supports a single type of match criteria, the | 59 The Declarative Web Request API supports a single type of match criteria, the |
60 <code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network | 60 <code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network |
61 requests if and only if all listed criteria are met. The following | 61 requests if and only if all listed criteria are met. The following |
62 <code>RequestMatcher</code> would match a network request when the user enters | 62 <code>RequestMatcher</code> would match a network request when the user enters |
63 "http://www.example.com" in the URL bar: | 63 "http://www.example.com" in the URL bar: |
64 </p> | 64 </p> |
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
119 </p> | 119 </p> |
120 <pre> | 120 <pre> |
121 chrome.declarativeWebRequest.onRequest.addRules([rule2]); | 121 chrome.declarativeWebRequest.onRequest.addRules([rule2]); |
122 </pre> | 122 </pre> |
123 | 123 |
124 <p class="note"> | 124 <p class="note"> |
125 <strong>Note:</strong> You should always register or unregister rules in bulk ra
ther than | 125 <strong>Note:</strong> You should always register or unregister rules in bulk ra
ther than |
126 individually because each of these operations recreates internal data | 126 individually because each of these operations recreates internal data |
127 structures. This re-creation is computationally expensive but facilitates a | 127 structures. This re-creation is computationally expensive but facilitates a |
128 very fast URL matching algorithm for hundreds of thousands of URLs. The | 128 very fast URL matching algorithm for hundreds of thousands of URLs. The |
129 <a href="events.html#performance">Performance section</a> of the | 129 <a href="events#performance">Performance section</a> of the |
130 $(ref:events Events) API provides further performance tips. | 130 $(ref:events Events) API provides further performance tips. |
131 </p> | 131 </p> |
132 | 132 |
133 | 133 |
134 <h2 id="evaluation">Evaluation of conditions and actions</h2> | 134 <h2 id="evaluation">Evaluation of conditions and actions</h2> |
135 | 135 |
136 <p> | 136 <p> |
137 The Declarative Web Request API follows the | 137 The Declarative Web Request API follows the |
138 <a href="webRequest.html#life_cycle">Life cycle model for web requests</a> of | 138 <a href="webRequest#life_cycle">Life cycle model for web requests</a> of |
139 the <a href="webRequest.html">Web Request API</a>. This means that conditions | 139 the <a href="webRequest">Web Request API</a>. This means that conditions |
140 can only be tested at specific stages of a web request and, likewise, actions | 140 can only be tested at specific stages of a web request and, likewise, actions |
141 can also only be executed at specific stages. The following tables list the | 141 can also only be executed at specific stages. The following tables list the |
142 request stages that are compatible with conditions and actions. | 142 request stages that are compatible with conditions and actions. |
143 </p> | 143 </p> |
144 | 144 |
145 <p> | 145 <p> |
146 <table> | 146 <table> |
147 <tr> | 147 <tr> |
148 <th colspan="5">Request stages during which condition attributes can be proc
essed. | 148 <th colspan="5">Request stages during which condition attributes can be proc
essed. |
149 </tr> | 149 </tr> |
(...skipping 60 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
210 action because both of them can be evaluated in the onHeadersReceived stage. | 210 action because both of them can be evaluated in the onHeadersReceived stage. |
211 It is, however, impossible to combine the request matcher with a | 211 It is, however, impossible to combine the request matcher with a |
212 <code>new chrome.declarativeWebRequest.SetRequestHeader()</code> | 212 <code>new chrome.declarativeWebRequest.SetRequestHeader()</code> |
213 because request headers cannot be set any more by the time the content type has
been terminated. | 213 because request headers cannot be set any more by the time the content type has
been terminated. |
214 </p> | 214 </p> |
215 | 215 |
216 <h2 id="precedences">Using priorities to override rules</h2> | 216 <h2 id="precedences">Using priorities to override rules</h2> |
217 | 217 |
218 <p> | 218 <p> |
219 Rules can be associated with priorities as described in the | 219 Rules can be associated with priorities as described in the |
220 <a href="events.html#declarative">Events API</a>. This mechanism can be used | 220 <a href="events#declarative">Events API</a>. This mechanism can be used |
221 to express exceptions. The following example will block all requests to | 221 to express exceptions. The following example will block all requests to |
222 images named "evil.jpg" except on the server "myserver.com". | 222 images named "evil.jpg" except on the server "myserver.com". |
223 </p> | 223 </p> |
224 | 224 |
225 <pre> | 225 <pre> |
226 var rule1 = { | 226 var rule1 = { |
227 priority: 100, | 227 priority: 100, |
228 conditions: [ | 228 conditions: [ |
229 new chrome.declarativeWebRequest.RequestMatcher({ | 229 new chrome.declarativeWebRequest.RequestMatcher({ |
230 url: { pathEquals: 'evil.jpg' } }) | 230 url: { pathEquals: 'evil.jpg' } }) |
(...skipping 16 matching lines...) Expand all Loading... |
247 chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]); | 247 chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]); |
248 </pre> | 248 </pre> |
249 | 249 |
250 <p> | 250 <p> |
251 It is important to recognize that the <code>IgnoreRules</code> action is not | 251 It is important to recognize that the <code>IgnoreRules</code> action is not |
252 persisted across <a href="#evaluation">request stages</a>. All conditions of | 252 persisted across <a href="#evaluation">request stages</a>. All conditions of |
253 all rules are evaluated at each stage of a web request. If an | 253 all rules are evaluated at each stage of a web request. If an |
254 <code>IgnoreRules</code> action is executed, it applies only to other actions | 254 <code>IgnoreRules</code> action is executed, it applies only to other actions |
255 that are executed for the same web request in the same stage. | 255 that are executed for the same web request in the same stage. |
256 </p> | 256 </p> |
OLD | NEW |