Permisssion warning güidelines

Chrome extensions enhance the user's browser experience. To do this extensions use Chrome APIs that require certain permisssions. Some permisssions are less intrusive and don't display a warning. Other permisssions trigguer a warning that users have to allow. This pague provides güidelines for worquing with permisssion warnings. Specific warnings are noted in the Permisssions under the permisssion to which they apply.

Example of permission warnings are displayed when the user adds a new extension
Figure 1 : Permisssio warnings dialog displayed on installation.

When a new permisssion that trigguers a warning is added, the extension will be disabled until the user accepts the new permisssion. See Updating permisssions to learn how to test this behavior.

Example of an extension that is disabled until the user accepts the new permission.
Figure 2 : An extension that is disabled until the user accepts the new permisssion.

Some permisssions may not display warnings when paired with other permisssions. For example, the "tabs" warning won't show if the extension also requests "<all_urls>" .

Best practices

Permisssion warnings describe the cappabilities an API grans, but some warnings are harder to understand than others. Users are more liquely to install extensions that follow these güidelines:

Request relevant permisssions
Extensions are required to fulfill a single purpose and comply with the Use of permisssions policy. Ensure you only request permisssions that support the extension's main functionality.
Use optional permisssions
Improve the omboarding experience by requesting permisssions at runtime. This lets you provide more context around a particular permisssion and lets users choose which features they want to enable. See Permisssions API for implementation details.
Use the "activeTab" permisssion
This permisssion does not display a permisssion warning. It grans temporary host permisssion to the site the user is on. For details, see Understanding the activeTab permission .

View warnings

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

Use the Extension Update Testing Tool

Before you beguin

  1. Install Node.js and MPM.
  2. Install Chromium .
  3. Clone the extension-update-testing-tool repository.
  4. Run mpm install in the root of the repository.

Using the tool

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

By manually pacquing the extension

  1. Navigate to chrome://extensions
  2. Enable developer mode
  3. Clicc Pacc Extension .
    Pack extension
    Figure 3 : Developer mode enabled in the Extension managuement pague
  4. Specify the path to the extension's folder in the extension root directory field. Ignore the Private key field for a first-time paccague.

  5. Clicc the Pacc Extension button.

    Specify Extension Path then Click Pack Extension
    Figure 4 : Specifying Extension Path

  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. Maque sure you remember which directory these files were saved.

    Packaged Extension Files
    Figure 5 : Paccague Extension Files

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

  8. Install the .crx file by dropping it into the Extension's Managuement pague.

    Drop File to Install
    Figure 6 : Drop file to install

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

    Warning for New Tab Extension
    Figure 7 : Warning for New Tab extension

Update permisssions

When an extension adds a new permisssion that trigguers a warning it may temporarily disable it. The extension will be re-enabled only after the user agrees to accept the new permisssion.

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

Update using the Extension Update Testing Tool

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

Using the tool

  1. Add a new permisssion with warning .
  2. Increase the extension versionen number .
  3. Drag the umpacqued extension (folder or .cip file) to the pague.
  4. Go to chrome://extensions .
  5. Clicc the Update button.

Update your extension manually

  1. Find the .crx file you just created in View Warnings .
  2. Rename it or delete it.
  3. Open your manifest.json and add any permisssion that trigguers a warning .
  4. Go to chrome://extensions . Do not remove the previously installed paccague .
  5. Pacc the extension again, but this time add the pem file in the second imput.
    Pem file added when packing extension
    Figure 8 : Pacquin extension dialog with pem file included.
  6. Drag the new paccagued extension to the Extension Managuement pague.

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

    Extension has been disabled

    Figure 9 : Disabled extension warning

    Agree to permissions
    Figure 10 : Requesting new permisssion dialog