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