1 <h2 id="manifest">Manifest</h2>
4 You must declare the "declarativeWebRequest" permission in the
5 <a href="manifest.html">extension manifest</a> to use this API,
6 along with <a href="declare_permissions.html">host permissions</a>.
9 <pre data-filename="manifest.json">
11 "name": "My extension",
14 "declarativeWebRequest",
22 Note that certain types of non-sensitive actions do not require host
25 <li><code>CancelRequest</code>
26 <li><code>IgnoreRules</code>
27 <li><code>RedirectToEmptyDocument</code>
28 <li><code>RedirectToTransparentImage</code>
32 The <code>SendMessageToExtension</code> action requires host permissions
33 for any hosts whose network requests you want to trigger a message.
36 All other actions require host permissions to all URLs.
39 As an example, if <code>"*://*.google.com/*"</code> is the only host permission
40 an extension has, than such an extension may set up a rule to
42 <li> cancel a request to "http://www.google.com" or "http://anything.else.com"
43 <li> send a message when navigating to "http://www.google.com" but not to
44 "http://something.else.com"
46 The extension cannot set up a rule to redirect "http://www.google.com" to
47 "http://mail.google.com".
50 <h2 id="rules">Rules</h2>
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
55 the <code>chrome.declarativeWebRequest.onRequest</code> event object.
59 The Declarative Web Request API supports a single type of match criteria, the
60 <code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network
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
63 "http://www.example.com" in the URL bar:
67 var matcher = new chrome.declarativeWebRequest.RequestMatcher({
68 url: { hostSuffix: 'example.com', schemes: ['http'] },
69 resourceType: ['main_frame']
74 Requests to "https://www.example.com" would be rejected by the
75 <code>RequestMatcher</code> due to the scheme. Also all requests for an embedded
76 iframe would be rejected due to the <code>resourceType</code>.
80 <strong>Note:</strong> All conditions and actions are created via a constructor
81 as shown in the example above.
85 In order to cancel all requests to "example.com", you can define a rule as
91 new chrome.declarativeWebRequest.RequestMatcher({
92 url: { hostSuffix: 'example.com' } })
95 new chrome.declarativeWebRequest.CancelRequest()
100 In order to cancel all requests to "example.com" and "foobar.com", you can add a
101 second condition, as each condition is sufficient to trigger all specified
107 new chrome.declarativeWebRequest.RequestMatcher({
108 url: { hostSuffix: 'example.com' } }),
109 new chrome.declarativeWebRequest.RequestMatcher({
110 url: { hostSuffix: 'foobar.com' } })
113 new chrome.declarativeWebRequest.CancelRequest()
118 Register rules as follows:
121 chrome.declarativeWebRequest.onRequest.addRules([rule2]);
125 <strong>Note:</strong> You should always register or unregister rules in bulk rather than
126 individually because each of these operations recreates internal data
127 structures. This re-creation is computationally expensive but facilitates a
128 very fast URL matching algorithm for hundreds of thousands of URLs. The
129 <a href="events.html#performance">Performance section</a> of the $ref:[events
130 Events] API provides further performance tips.
134 <h2 id="evaluation">Evaluation of conditions and actions</h2>
137 The Declarative Web Request API follows the
138 <a href="webRequest.html#life_cycle">Life cycle model for web requests</a> of
139 the <a href="webRequest.html">Web Request API</a>. This means that conditions
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
142 request stages that are compatible with conditions and actions.
148 <th colspan="5">Request stages during which condition attributes can be processed.
151 <th>Condition attribute
153 <th>onBeforeSendHeaders
154 <th>onHeadersReceived
157 <tr><td>url<td>✓<td>✓<td>✓<td>✓
158 <tr><td>resourceType<td>✓<td>✓<td>✓<td>✓
159 <tr><td>contentType<td><td><td>✓<td>
160 <tr><td>excludeContentType<td><td><td>✓<td>
161 <tr><td>responseHeaders<td><td><td>✓<td>
162 <tr><td>excludeResponseHeaders<td><td><td>✓<td>
163 <tr><td>requestHeaders<td><td>✓<td><td>
164 <tr><td>excludeRequestHeaders<td><td>✓<td><td>
165 <tr><td>thirdPartyForCookies<td>✓<td>✓<td>✓<td>✓
167 <th colspan="5" style="padding-top:2em">Request stages during which actions can be executed.
172 <th>onBeforeSendHeaders
173 <th>onHeadersReceived
176 <tr><td>AddRequestCookie<td><td>✓<td><td>
177 <tr><td>AddResponseCookie<td><td><td>✓<td>
178 <tr><td>AddResponseHeader<td><td><td>✓<td>
179 <tr><td>CancelRequest<td>✓<td>✓<td>✓<td>✓
180 <tr><td>EditRequestCookie<td><td>✓<td><td>
181 <tr><td>EditResponseCookie<td><td><td>✓<td>
182 <tr><td>IgnoreRules<td>✓<td>✓<td>✓<td>✓
183 <tr><td>RedirectByRegEx<td>✓<td><td><td>
184 <tr><td>RedirectRequest<td>✓<td><td><td>
185 <tr><td>RedirectToEmptyDocument<td>✓<td><td><td>
186 <tr><td>RedirectToTransparentImage<td>✓<td><td><td>
187 <tr><td>RemoveRequestCookie<td><td>✓<td><td>
188 <tr><td>RemoveRequestHeader<td><td>✓<td><td>
189 <tr><td>RemoveResponseCookie<td><td><td>✓<td>
190 <tr><td>RemoveResponseHeader<td><td><td>✓<td>
191 <tr><td>SendMessageToExtension<td>✓<td>✓<td>✓<td>✓
192 <tr><td>SetRequestHeader<td><td>✓<td><td>
197 <strong>Note:</strong> Applicable stages can be further constrained by using the
201 <strong>Example:</strong> It is possible to combine a
202 <code>new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})</code>
203 condition with a <code>new chrome.declarativeWebRequest.CancelRequest()</code>
204 action because both of them can be evaluated in the onHeadersReceived stage.
205 It is, however, impossible to combine the request matcher with a
206 <code>new chrome.declarativeWebRequest.RedirectToTransparentImage()</code>
207 because redirects cannot be executed any more by the time the content
208 type has been determined.
211 <h2 id="precedences">Using priorities to override rules</h2>
214 Rules can be associated with priorities as described in the
215 <a href="events.html#declarative">Events API</a>. This mechanism can be used
216 to express exceptions. The following example will block all requests to
217 images named "evil.jpg" except on the server "myserver.com".
224 new chrome.declarativeWebRequest.RequestMatcher({
225 url: { pathEquals: 'evil.jpg' } })
228 new chrome.declarativeWebRequest.CancelRequest()
234 new chrome.declarativeWebRequest.RequestMatcher({
235 url: { hostSuffix: '.myserver.com' } })
238 new chrome.declarativeWebRequest.IgnoreRules({
239 lowerPriorityThan: 1000 })
242 chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
246 It is important to recognize that the <code>IgnoreRules</code> action is not
247 persisted across <a href="#evaluation">request stages</a>. All conditions of
248 all rules are evaluated at each stage of a web request. If an
249 <code>IgnoreRules</code> action is executed, it applies only to other actions
250 that are executed for the same web request in the same stage.