Optional Permissions

Contents

1. Implementing optional permissions
   1. Step 1: Decide which permissions are optional and required
   2. Step 2: Declare optional permissions in the manifest
   3. Step 3: Request optional permissions
   4. Step 4: Check the extension's current permissions
   5. Step 5: Remove the permissions
2. API reference: chrome.permissions
   1. Methods
      1. contains
      2. getAll
      3. remove
      4. request
   2. Events
      1. onAdded
      2. onRemoved
   3. Types
      1. Permissions

Use the chrome.permissions 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.

For general information about permissions and details about each permission, see the permissions section of the manifest documentation.

Implementing optional permissions

Step 1: Decide which permissions are optional and required

Extensions should generally require permissions when they are needed for the extension's basic functionality and employ optional permissions for optional features.

Advantages of optional permissions:

• Users run with less permissions since they enable only what is needed.
• The extension can help explain why it needs particular permissions by requesting them when the user enables the relevant feature.
• Chrome can avoid disabling extensions that upgrade if they add permissions as optional rather than required.

Advantages of required permissions:

• The extension can prompt the user once to accept all permissions.
• They simplify extension development by guaranteeing which permissions are present.

Step 2: Declare optional permissions in the manifest

Declare optional permissions in your extension manifest with the optional_permissions key, using the same format as the permissions field:

{
  "name": "My extension",
  ...
  "optional_permissions": [ "tabs", "http://www.google.com/" ],
  ...
}

You can specify any of the following as optional permissions:

• host permissions
• appNotifications
• background
• bookmarks
• clipboardRead
• clipboardWrite
• contentSettings
• contextMenus
• cookies
• debugger
• history
• idle
• management
• notifications
• pageCapture
• tabs
• topSites
• webNavigation
• webRequest
• webRequestBlocking

Version note: This list is correct as of Chrome 17. More optional permissions might be allowed in future releases.

Step 3: Request optional permissions

Request the permissions from within a user gesture using permissions.request():

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();
    }
  });
});

Chrome prompts the user if adding the permissions results in different warning messages than the user has already seen and accepted. For example, the previous code might result in a prompt like this:

Step 4: Check the extension's current permissions

To check whether your extension has a specific permission or set of permissions, use permission.contains():

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.
  }
});

Step 5: Remove the permissions

You should remove permissions when you no longer need them. After a permission has been removed, calling permissions.request() usually adds the permission back without prompting the user.

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).
  }
});