chrome.permissions

Implementing optional permissions

Step 1: Decide which permissions are required and which are optional

An extension can declare both required and optional permissions. In general, you should:

• Use required permissions when they are needed for your extension’s basic functionality.
• Use optional permissions when they are needed for optional features in your extension.

Advantages of required permissions:

• Fewer prompts: An extension can prompt the user once to accept all permissions.
• Simpler development: Required permissions are guaranteed to be present.

Advantages of optional permissions:

• Better security: Extensions run with fewer permissions since users only enable permissions that are needed.
• Better information for users: An extension can explain why it needs a particular permission when the user enables the relevant feature.
• Easier upgrades: When you upgrade your extension, Chrome will not disable it for your users if the upgrade adds optional rather than required permissions.

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
• background
• bookmarks
• clipboardRead
• clipboardWrite
• contentSettings
• contextMenus
• cookies
• debugger
• history
• idle
• management
• notifications
• pageCapture
• tabs
• topSites
• webNavigation
• webRequest
• webRequestBlocking

If you want to request hosts that you only discover at runtime, include "http://*/" and/or "https://*/" as an optional_permission. This lets you specify any origin in Permissions.origins as long as it has a matching scheme.

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

Summary