content

  1. Implement optional permissions in an extension

    1. Step 1: Determine which permissions are optional and which are required.
    2. Step 2: Declare optional permissions in the manifest file
    3. Step 3: Extend optional permissions requested during runtime
    4. Step 4: Extend the existing permissions checked during the run
    5. Step 5: Extend the run process to remove permissions that are no longer needed

  2. API reference: Chrome.permissions

    1. methods

      1. contains
      2. getAll
      3. remove
      4. request

    2. The event

      1. onAdded
      2. onRemoved

    3. type

      1. Permissions

Chrome.permissions is used to implement optional permissions. Request permissions while your extension is running, not at install time. This helps users understand why they need this permission and only run extensions to use it when necessary.

For information about permissions and details on each permission, see Permissions in the MANIFEST section.

Implement optional permissions

Step 1: Determine which permissions are optional and which are required.

Extensions require some necessary permissions to meet basic functionality, while others can be requested from the user during the extension run.

Advantages of optional permissions:

  • Only a few permissions are required when the extension is active, and more permissions are requested when the extension is running.
  • When more permissions are requested during an extension run, users can be more clearly explained why they need those specific permissions.
  • Prevents Chrome from blocking extension upgrades (because Chrome prevents automatic upgrades of a new version of an extension that requires more required permissions than an older version).

Advantages of mandatory permissions:

  • The extension can prompt the user once to accept the required permissions.
  • The extension runtime ensures that you have permissions, simplifying extension development.

Step 2: Declare optional permissions in the manifest file

Declare optional permissions with the optional_permissions keyword in the Extension Manifest, the same as declaring permissions:

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

You can specify any of the following 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 works with Chrome 17. More optional permissions will be available in later versions.

Step 3: Request optional permissions

Permissions are requested by calling permissions.request() and user authorization is required:

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

If the add is different from what the user sees and accepts. Chrome prompts the user with Warning messages. For example, the above sample code results in a prompt like this:

Step 4: Check the current permissions of the extension

Checking whether the extension has a specific permission can be done by using 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.
        }
});
Copy the code

Step 5: Delete permissions

You should remove permissions that are no longer needed. When a user’s permission has been removed, the user is not prompted to add it again using permissions. Request ().

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

API reference: Chrome.permissions

methods

contains

Chrome.permissions.contains(Permissions permissions, function callback)

Check whether you have certain permissions.

parameter

permissions ( Permissions )

Undocumented.

callback ( function )

Undocumented.

Callback function

If you need to specify a callback function, the format is as follows:

function(boolean result) {... };Copy the code

result ( boolean )

Returns true if the extension already has the specified permissions.

getAll

Chrome.permissions.getAll(function callback)

Gets the current permission for the extension.

parameter

callback ( function )

Undocumented.

Callback function

If you need to specify a callback function, the format is as follows:

function(Permissions permissions) {... };Copy the code

permissions ( Permissions )

Extend current permissions.

remove

Chrome.permissions.remove(Permissions permissions, function callback)

Deletes the specified permission. If during the process of removing abnormal, Chrome extension. The lastError will be set up

parameter

permissions ( Permissions )

Undocumented.

callback ( optional function )

Undocumented.

Callback function

If you need to specify a callback function, the format is as follows:

function(boolean removed) {... };Copy the code

removed ( boolean )

Returns true on successful deletion.

request

Chrome.permissions.request(Permissions permissions, function callback)

Request the specified permission. The requested permissions must be included in the Optional_Permissions section of the manifest file. If during the process of removing abnormal, Chrome extension. The lastError will be set up

parameter

permissions ( Permissions )

Undocumented.

callback ( optional function )

Undocumented.

Callback function

If you need to specify a callback function, the format is as follows:

function(boolean granted) {... };Copy the code

granted ( boolean )

Returns true if the user grants permission to request.

The event

onAdded

Chrome.permissions.onAdded.addListener(function(Permissions permissions) {… });

Triggered when the extension acquires new permissions.

parameter

permissions ( Permissions )

Newly acquired permissions.

onRemoved

Chrome.permissions.onRemoved.addListener(function(Permissions permissions) {… });

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

parameter

permissions ( Permissions )

Deleted permission.

type

Permissions

( object )

Undocumented.

permissions ( optional array of string )

List of permission names (excluding hosts or origins).

origins ( optional array of string )

List of original permissions.