Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(161)

Side by Side Diff: chrome/common/extensions/docs/server2/templates/private/permissions_intro.html

Issue 10750017: Extensions Docs Server: Intro data source (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src
Patch Set: nits Created 8 years, 5 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
OLDNEW
(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 -->
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698