Google Chrome Extensions

chrome.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:

Advantages of 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:

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:

example permission confirmation prompt

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

API Reference: chrome.permissions

Types

Permissions

( object )

Properties of Permissions

permissions ( optional array of string )
List of named permissions (does not include hosts or origins).
origins ( optional array of string )
List of origin permissions.

Methods

getAll

chrome.permissions.getAll()

Gets the extension's current set of permissions.

contains

chrome.permissions.contains(Permissions permissions)

Checks if the extension has the specified permissions.

Parameters

permissions ( Permissions )

Callback function

The callback parameter should specify a function that looks like this:

function(boolean result) {...};
result ( boolean )
True if the extension has the specified permissions.

request

chrome.permissions.request(Permissions permissions)

Requests access to the specified permissions. These permissions must be defined in the optional_permissions field of the manifest. If there are any problems requesting the permissions, chrome.extension.lastError will be set.

Parameters

permissions ( Permissions )

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(boolean granted) {...};
granted ( boolean )
True if the user granted the specified permissions.

remove

chrome.permissions.remove(Permissions permissions)

Removes access to the specified permissions. If there are any problems removing the permissions, chrome.extension.lastError will be set.

Parameters

permissions ( Permissions )

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(boolean removed) {...};
removed ( boolean )
True if the permissions were removed.

Events

onAdded

chrome.permissions.onAdded.addListener(function(Permissions permissions) {...});

Fired when the extension acquires new permissions.

Listener Parameters

permissions ( Permissions )
The newly acquired permissions.

onRemoved

chrome.permissions.onRemoved.addListener(function(Permissions permissions) {...});

Fired when access to permissions has been removed from the extension.

Listener Parameters

permissions ( Permissions )
The permissions that have been removed.

Sample Extensions that use chrome.permissions

  • Top Chrome Extension Questions – Sample demonstration of the optional permissions API.