OLD | NEW |
| (Empty) |
1 <!-- BEGIN AUTHORED CONTENT --> | |
2 <p id="classSummary"> | |
3 Use the <code>chrome.permissions</code> module to implement | |
4 optional permissions. You can request optional permissions during your | |
5 extension's regular application flow rather than at install time, so users | |
6 understand why the permissions are needed and use only those that are | |
7 necessary. | |
8 </p> | |
9 <p> | |
10 For general information about permissions and details about each permission, | |
11 see the <a href="manifest.html#permissions">permissions</a> section of the | |
12 manifest documentation. | |
13 </p> | |
14 <h2 id="howto"> Implementing optional permissions </h2> | |
15 | |
16 <h3 id="types"> | |
17 Step 1: Decide which permissions are optional and required | |
18 </h3> | |
19 <p> | |
20 Extensions should generally require permissions when they are needed for the | |
21 extension's basic functionality and employ optional permissions for optional | |
22 features. | |
23 </p> | |
24 <p> | |
25 Advantages of optional permissions: | |
26 <ul> | |
27 <li> | |
28 Users run with less permissions since they enable only what is needed. | |
29 </li> | |
30 <li> | |
31 The extension can help explain why it needs particular permissions by | |
32 requesting them when the user enables the relevant feature. | |
33 </li> | |
34 <li> | |
35 Chrome can avoid disabling extensions that upgrade if they add permissions | |
36 as optional rather than required. | |
37 </li> | |
38 </ul> | |
39 </p> | |
40 <p> | |
41 Advantages of required permissions: | |
42 <ul> | |
43 <li> | |
44 The extension can prompt the user once to accept all permissions. | |
45 </li> | |
46 <li> | |
47 They simplify extension development by guaranteeing which permissions are | |
48 present. | |
49 </li> | |
50 </ul> | |
51 </p> | |
52 <h3 id="manifest"> Step 2: Declare optional permissions in the manifest </h3> | |
53 <p> | |
54 Declare optional permissions in your <a href="manifest.html">extension | |
55 manifest</a> with the <code>optional_permissions</code> key, using the | |
56 same format as the <a href="manifest.html#permissions">permissions</a> | |
57 field: | |
58 <pre>{ | |
59 "name": "My extension", | |
60 ... | |
61 <b>"optional_permissions": [ "tabs", "http://www.google.com/" ],</b> | |
62 ... | |
63 }</pre> | |
64 </p> | |
65 <p> | |
66 You can specify any of the following as optional permissions: | |
67 <ul> | |
68 <li><i>host permissions</i></li> | |
69 <li>appNotifications</li> | |
70 <li>background</li> | |
71 <li>bookmarks</li> | |
72 <li>clipboardRead</li> | |
73 <li>clipboardWrite</li> | |
74 <li>contentSettings</li> | |
75 <li>contextMenus</li> | |
76 <li>cookies</li> | |
77 <li>debugger</li> | |
78 <li>history</li> | |
79 <li>idle</li> | |
80 <li>management</li> | |
81 <li>notifications</li> | |
82 <li>pageCapture</li> | |
83 <li>tabs</li> | |
84 <li>topSites</li> | |
85 <li>webNavigation</li> | |
86 <li>webRequest</li> | |
87 <li>webRequestBlocking</li> | |
88 </ul> | |
89 </p> | |
90 <p class="note"> | |
91 <b>Version note:</b> This list is correct as of Chrome 17. | |
92 More optional permissions might be allowed in future releases. | |
93 </p> | |
94 <h3 id="request"> Step 3: Request optional permissions </h3> | |
95 <p> | |
96 Request the permissions from within a user gesture using | |
97 <code>permissions.request()</code>: | |
98 <pre> | |
99 document.querySelector('#my-button').addEventListener('click', function(event) { | |
100 // Permissions must be requested from inside a user gesture, like a button's | |
101 // click handler. | |
102 chrome.permissions.request({ | |
103 permissions: ['tabs'], | |
104 origins: ['http://www.google.com/'] | |
105 }, function(granted) { | |
106 // The callback argument will be true if the user granted the permissions. | |
107 if (granted) { | |
108 doSomething(); | |
109 } else { | |
110 doSomethingElse(); | |
111 } | |
112 }); | |
113 }); | |
114 </pre> | |
115 </p> | |
116 <p> | |
117 Chrome prompts the user if adding the permissions results in different | |
118 <a href="permission_warnings.html">warning messages</a> than the user has | |
119 already seen and accepted. For example, the previous code might result in | |
120 a prompt like this: | |
121 </p> | |
122 <p style="text-align: center"> | |
123 <img src="{{static}}/images/perms-optional.png" | |
124 alt="example permission confirmation prompt" | |
125 width="416" height="234"> | |
126 </p> | |
127 <h3 id="contains"> Step 4: Check the extension's current permissions </h3> | |
128 <p> | |
129 To check whether your extension has a specific permission or set of | |
130 permissions, use <code>permission.contains()</code>: | |
131 </p> | |
132 <pre> | |
133 chrome.permissions.contains({ | |
134 permissions: ['tabs'], | |
135 origins: ['http://www.google.com/'] | |
136 }, function(result) { | |
137 if (result) { | |
138 // The extension has the permissions. | |
139 } else { | |
140 // The extension doesn't have the permissions. | |
141 } | |
142 }); | |
143 </pre> | |
144 <h3 id="remove"> Step 5: Remove the permissions </h3> | |
145 <p> | |
146 You should remove permissions when you no longer need them. | |
147 After a permission has been removed, calling | |
148 <code>permissions.request()</code> usually adds the permission back without | |
149 prompting the user. | |
150 </p> | |
151 <pre> | |
152 chrome.permissions.remove({ | |
153 permissions: ['tabs'], | |
154 origins: ['http://www.google.com/'] | |
155 }, function(removed) { | |
156 if (removed) { | |
157 // The permissions have been removed. | |
158 } else { | |
159 // The permissions have not been removed (e.g., you tried to remove | |
160 // required permissions). | |
161 } | |
162 }); | |
163 </pre> | |
164 <!-- END AUTHORED CONTENT --> | |
OLD | NEW |