• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<h2 id="howto"> Implementing optional permissions </h2>
2
3<h3 id="types">
4Step 1: Decide which permissions are required and which are optional
5</h3>
6
7<p>
8An extension can declare both required and optional permissions. In general, you should:
9<ul>
10  <li>Use required permissions when they are needed for your extension’s basic functionality.</li>
11  <li>Use optional permissions when they are needed for optional features in your extension.</li>
12</ul>
13</p>
14
15<p>
16Advantages of <em>required</em> permissions:
17<ul>
18  <li><strong>Fewer prompts:</strong>
19      An extension can prompt the user once to accept all permissions.</li>
20  <li><strong>Simpler development:</strong>
21      Required permissions are guaranteed to be present.</li>
22</ul>
23</p>
24
25<p>
26Advantages of <em>optional</em> permissions:
27<ul>
28  <li><strong>Better security:</strong>
29      Extensions run with fewer permissions since users only enable permissions that are needed.</li>
30  <li><strong>Better information for users:</strong>
31      An extension can explain why it needs a particular permission when the user enables the relevant feature.</li>
32  <li><strong>Easier upgrades:</strong>
33      When you upgrade your extension, Chrome will not disable it for your users if the upgrade adds optional rather than required permissions.</li>
34</ul>
35</p>
36
37<h3 id="manifest"> Step 2: Declare optional permissions in the manifest </h3>
38<p>
39  Declare optional permissions in your <a href="manifest">extension
40  manifest</a> with the <code>optional_permissions</code> key, using the
41  same format as the <a href="declare_permissions#manifest">permissions</a>
42  field:
43</p>
44
45<pre data-filename="manifest.json">
46{
47  "name": "My extension",
48  ...
49  <b>"optional_permissions": [ "tabs", "http://www.google.com/" ],</b>
50  ...
51}
52</pre>
53
54<p>
55You can specify any of the following as optional
56<a href="declare_permissions">permissions</a>:
57<ul>
58  <li><i>host permissions</i></li>
59  <li>background</li>
60  <li>bookmarks</li>
61  <li>clipboardRead</li>
62  <li>clipboardWrite</li>
63  <li>contentSettings</li>
64  <li>contextMenus</li>
65  <li>cookies</li>
66  <li>debugger</li>
67  <li>history</li>
68  <li>idle</li>
69  <li>management</li>
70  <li>notifications</li>
71  <li>pageCapture</li>
72  <li>tabs</li>
73  <li>topSites</li>
74  <li>webNavigation</li>
75  <li>webRequest</li>
76  <li>webRequestBlocking</li>
77</ul>
78</p>
79
80<p>If you want to request hosts that you only discover at runtime, include
81<code>"http://*/"</code> and/or <code>"https://*/"</code> as an
82<code>optional_permission</code>.  This lets you specify any origin in
83$(ref:Permissions.origins) as long as it has a matching scheme.
84</p>
85
86<h3 id="request"> Step 3: Request optional permissions </h3>
87<p>
88  Request the permissions from within a user gesture using
89  <code>permissions.request()</code>:
90<pre>
91document.querySelector('#my-button').addEventListener('click', function(event) {
92  // Permissions must be requested from inside a user gesture, like a button's
93  // click handler.
94  chrome.permissions.request({
95    permissions: ['tabs'],
96    origins: ['http://www.google.com/']
97  }, function(granted) {
98    // The callback argument will be true if the user granted the permissions.
99    if (granted) {
100      doSomething();
101    } else {
102      doSomethingElse();
103    }
104  });
105});
106</pre>
107</p>
108
109<p>
110  Chrome prompts the user if adding the permissions results in different
111  <a href="permission_warnings">warning messages</a> than the user has
112  already seen and accepted. For example, the previous code might result in
113  a prompt like this:
114</p>
115
116<p style="text-align: center">
117  <img src="{{static}}/images/perms-optional.png"
118       alt="example permission confirmation prompt"
119       width="490" height="193">
120</p>
121
122<h3 id="contains"> Step 4: Check the extension's current permissions </h3>
123<p>
124  To check whether your extension has a specific permission or set of
125  permissions, use <code>permission.contains()</code>:
126</p>
127
128<pre>
129chrome.permissions.contains({
130  permissions: ['tabs'],
131  origins: ['http://www.google.com/']
132}, function(result) {
133  if (result) {
134    // The extension has the permissions.
135  } else {
136    // The extension doesn't have the permissions.
137  }
138});
139</pre>
140
141<h3 id="remove"> Step 5: Remove the permissions </h3>
142<p>
143  You should remove permissions when you no longer need them.
144  After a permission has been removed, calling
145  <code>permissions.request()</code> usually adds the permission back without
146  prompting the user.
147</p>
148
149<pre>
150chrome.permissions.remove({
151  permissions: ['tabs'],
152  origins: ['http://www.google.com/']
153}, function(removed) {
154  if (removed) {
155    // The permissions have been removed.
156  } else {
157    // The permissions have not been removed (e.g., you tried to remove
158    // required permissions).
159  }
160});
161</pre>
162