You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
paramName
( optional enumerated Type array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Parameters
  1. Properties
    1. propertyName
  2. Methods
    1. methodName
  3. Events
    1. eventName
  4. Types
    1. id

Google Chrome Extensions (Labs)

Optional Permissions

Optional 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
  • 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:

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

Methods

contains

void chrome.permissions.contains(, Permissions permissions, function callback)

Checks if the extension has the specified permissions.

Parameters

permissions
( Permissions array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

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

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

function(boolean result) {...};
result
( Type array of boolean )
True if the extension has the specified permissions.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

getAll

void chrome.permissions.getAll(, function callback)

Gets the extension's current set of permissions.

Parameters

callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

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

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

function(Permissions permissions) {...};
permissions
( Permissions array of paramType )
The extension's active permissions.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

remove

void chrome.permissions.remove(, Permissions permissions, function callback)

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

Parameters

permissions
( Permissions array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

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

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

function(boolean removed) {...};
removed
( Type array of boolean )
True if the permissions were removed.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

request

void chrome.permissions.request(, Permissions permissions, function callback)

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 array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

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

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

function(boolean granted) {...};
granted
( Type array of boolean )
True if the user granted the specified permissions.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Events

onAdded

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

Fired when the extension acquires new permissions.

Listener parameters

permissions
( Permissions array of paramType )
The newly acquired permissions.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

Listener returns

onRemoved

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

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

Listener parameters

permissions
( Permissions array of paramType )
The permissions that have been removed.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

Listener returns

Types

Permissions

paramName
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
permissions
( optional Type array of Type array of string paramType )
List of named permissions (does not include hosts or origins).
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
origins
( optional Type array of Type array of string paramType )
List of origin permissions.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.