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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<div id="pageData-name" class="pageData">Optional Permissions</div>
<!-- BEGIN AUTHORED CONTENT -->
<p id="classSummary">
Use the <code>chrome.permissions</code> module to implement
optional permissions. You can request optional permissions during your
extension's regular application flow rather than at install time, so users
understand why the permissions are needed and use only those that are
necessary.
</p>
<p>
For general information about permissions and details about each permission,
see the <a href="manifest.html#permissions">permissions</a> section of the
manifest documentation.
</p>
<h2 id="howto"> Implementing optional permissions </h2>
<h3 id="types">
Step 1: Decide which permissions are optional and required
</h3>
<p>
Extensions should generally require permissions when they are needed for the
extension's basic functionality and employ optional permissions for optional
features.
</p>
<p>
Advantages of optional permissions:
<ul>
<li>
Users run with less permissions since they enable only what is needed.
</li>
<li>
The extension can help explain why it needs particular permissions by
requesting them when the user enables the relevant feature.
</li>
<li>
Chrome can avoid disabling extensions that upgrade if they add permissions
as optional rather than required.
</li>
</ul>
</p>
<p>
Advantages of required permissions:
<ul>
<li>
The extension can prompt the user once to accept all permissions.
</li>
<li>
They simplify extension development by guaranteeing which permissions are
present.
</li>
</ul>
</p>
<h3 id="manifest"> Step 2: Declare optional permissions in the manifest </h3>
<p>
Declare optional permissions in your <a href="manifest.html">extension
manifest</a> with the <code>optional_permissions</code> key, using the
same format as the <a href="manifest.html#permissions">permissions</a>
field:
<pre>{
"name": "My extension",
...
<b>"optional_permissions": [ "tabs", "http://www.google.com/" ],</b>
...
}</pre>
</p>
<p>
You can specify any of the following as optional permissions:
<ul>
<li><i>host permissions</i></li>
<li>appNotifications</li>
<li>background</li>
<li>bookmarks</li>
<li>clipboardRead</li>
<li>clipboardWrite</li>
<li>contentSettings</li>
<li>contextMenus</li>
<li>cookies</li>
<li>debugger</li>
<li>history</li>
<li>idle</li>
<li>management</li>
<li>notifications</li>
<li>pageCapture</li>
<li>tabs</li>
<li>topSites</li>
<li>webNavigation</li>
<li>webRequest</li>
<li>webRequestBlocking</li>
</ul>
</p>
<p class="note">
<b>Version note:</b> This list is correct as of Chrome 17.
More optional permissions might be allowed in future releases.
</p>
<h3 id="request"> Step 3: Request optional permissions </h3>
<p>
Request the permissions from within a user gesture using
<code>permissions.request()</code>:
<pre>
document.querySelector('#my-button').addEventListener('click', function(event) {
// Permissions must be requested from inside a user gesture, like a button's
// click handler.
chrome.permissions.request({
permissions: ['tabs'],
origins: ['http://www.google.com/']
}, function(granted) {
// The callback argument will be true if the user granted the permissions.
if (granted) {
doSomething();
} else {
doSomethingElse();
}
});
});
</pre>
</p>
<p>
Chrome prompts the user if adding the permissions results in different
<a href="permission_warnings.html">warning messages</a> than the user has
already seen and accepted. For example, the previous code might result in
a prompt like this:
</p>
<p style="text-align: center">
<img src="images/perms-optional.png"
alt="example permission confirmation prompt"
width="416" height="234">
</p>
<h3 id="contains"> Step 4: Check the extension's current permissions </h3>
<p>
To check whether your extension has a specific permission or set of
permissions, use <code>permission.contains()</code>:
</p>
<pre>
chrome.permissions.contains({
permissions: ['tabs'],
origins: ['http://www.google.com/']
}, function(result) {
if (result) {
// The extension has the permissions.
} else {
// The extension doesn't have the permissions.
}
});
</pre>
<h3 id="remove"> Step 5: Remove the permissions </h3>
<p>
You should remove permissions when you no longer need them.
After a permission has been removed, calling
<code>permissions.request()</code> usually adds the permission back without
prompting the user.
</p>
<pre>
chrome.permissions.remove({
permissions: ['tabs'],
origins: ['http://www.google.com/']
}, function(removed) {
if (removed) {
// The permissions have been removed.
} else {
// The permissions have not been removed (e.g., you tried to remove
// required permissions).
}
});
</pre>
<!-- END AUTHORED CONTENT -->
|
