Chrome extensions enhance the user's browser experience. To do this extensions useChromeAPIs that require certain permissions. Some permissions are less intrusive and don'tdisplay a warning. Other permissions trigger a warning that users have to allow. This pageprovides guidelines for working with permission warnings. Specific warnings are noted in thePermissions under the permission to whichthey apply.

When a new permission thattriggers a warning is added, the extensionwill be disabled until the user accepts the new permission. SeeUpdating permissions to learn how to test this behavior.

Some permissions may not display warnings when pairedwith other permissions. For example, the"tabs" warning won't show if the extension alsorequests"<all_urls>".

Best practices

Permission warnings describe the capabilities an API grants, but some warnings areharder to understand than others. Users are more likely to install extensions that follow theseguidelines:

Request relevant permissions

Extensions are required to fulfill asingle purpose andcomply with theUse of permissions policy. Ensure you onlyrequest permissions that support the extension's main functionality.

Use optional permissions

Improve the onboarding experience by requesting permissions at runtime. This lets you provide more contextaround a particular permission and lets users choose which features they want to enable. SeePermissions API for implementation details.

Use the "activeTab" permission

This permission doesnot display a permission warning. It grants temporary host permission tothe site the user is on. For details, seeUnderstanding the activeTabpermission.

View warnings

To view an extension's permission warnings, you have the following options:

Use the Extension Update Testing Tool

Before you begin

1. InstallNode.js and NPM.
2. InstallChromium.
3. Clone theextension-update-testing-tool repository.
4. Runnpm install in the root of the repository.

Using the tool

1. Runnpm start.
2. Open the local server at http://localhost:8080 in Chromium.
3. Drag an unpacked extension (folder or .zip file) to the page.
4. Follow the instructions under "Install manually" to download and install the extension.

By manually packing the extension

1. Navigate tochrome://extensions
2. Enable developer mode
3. ClickPack Extension.

   

4. Specify the path to the extension's folder in the extension root directory field. Ignore thePrivate key field for a first-time package.

5. Click thePack Extension button.

   

6. Chrome will create two files, a.crx file and a.pem file. The.pem file contains the private key used to sign the extension. Make sure you remember which directory these files were saved.

   

7. Keep the.pem file in a secret and secure place; it will be needed toupdate the extension.

8. Install the.crx file by dropping it into the Extension's Management page.

   

9. After dropping the.crx file the browser will ask if the extension can be added and display warnings.

   

Update permissions

When an extension adds a new permission thattriggers a warning it maytemporarily disable it. The extension will be re-enabled only after the user agrees to accept thenew permission.

To check if your extension will be disabled when adding a new permission, you have the following options:

Update using the Extension Update Testing Tool

These steps assume you followed theUsing the Extension Update Testing Tool instructions to start the server.

Using the tool

1. Add a newpermission with warning.
2. Increase the extensionversion number.
3. Drag the unpacked extension (folder or .zip file) to the page.
4. Go tochrome://extensions.
5. Click theUpdate button.

Update your extension manually

1. Find the.crx file you just created inView Warnings.
2. Rename it or delete it.
3. Open yourmanifest.json and add anypermission that triggers a warning.
4. Go tochrome://extensions.Do not remove the previously installed package.
5. Pack the extension again, but this time add the pem file in the second input.

   

6. Drag the new packaged extension to the Extension Management page.

7. You will see a dialog that prompts the user to accept the new permissions.