Definitions

• feature id: A string which uniquely identifies a privileged feature.
• privileged feature: A feature of a user agent which requires the user's permission before web pages can use it. Examples of privileged features may include desktop notifications, geolocation, file system access, etc.
• origin: In this document, "origin" or "security origin" refers to an origin as used by Cross-Origin Resource Sharing. [[!CORS]]
• user gesture: A script event is considered a user gesture if it directly resulted from the user using an input device, and the event is generated by the user agent, not a script. For example, the onclick event on an A element and the onkeypress event on an INPUT element are user gestures. Scripts run by a timeout, or for example an onload event are not user gestures.

Introduction

This specification provides an generic API for user agents which offer privileged features to web pages in order to manage permissions in a consistent manner.

The purpose of the specification is to allow users to grant permission to use individual privileged features to only the web pages which the user selects.

Permissions are granted and denied on a per-origin basis.

The following code illustrates how to query the permission level of a feature:

      // A feature that requires permissions
      var featureID = "notifications";

      // feature is ready to use in the app as the permission has been already granted
      var useFeature = false;

      function permissionRequestCallback() {
        if (permission == USER_DENIED) {
          // Perform the action knowing that permission is already granted
          alert("This app will not be able to use " + featureID + ".");
        } else if (permission == USER_ALLOWED) {
          // Feature is ready to be used as the permission is granted
          useFeature = true;
        }
      }

      // Getting the permission level of the feature identified by 'featureID'
      var permission = navigator.permissionLevel(featureID);

      if (permission == DEFAULT_DENIED) {
        // Indicate to the user that allowing the feature will result in a better experience
        alert("Enabling " + featureID + " will enable functionality XXX");

        // Optionally the app can decide at any time to request a permission for the feature
        navigator.requestPermission(featureID, permissionRequestCallback());
      }

      if (permission == DEFAULT_ALLOWED || permission == USER_ALLOWED) {
        // Feature is ready to be used as the permission is granted
        useFeature = true;
      } else if (permission == DEFAULT_DENIED) {
        // Proceed without using functionality that requires permission until the user responds to the permission request
      }

      // Main application logic
      if (useFeature) {
        useFeature();
      } else {
        // Limited functionality as the feature is not allowed to be used
        doNotUseFeature();
      }
    

The NavigatorPermissions interface

• Identify the privileged features available in the user agent, using the privilegedFeatures array. Each feature has a unique string identifier in the array.
• Check the current permissions level of each feature for the current security origin, using the permissionLevel method.
• Request the user's permission to use a feature, using the requestPermission method, and receive an asynchronous callback when the user has made a decision.

NavigatorPermissions

const long USER_ALLOWED = 2

Indicates that the user has granted permission.

const long DEFAULT_ALLOWED = 1

Indicates that the user has not made a permissions decision, but the user agent's default policy is to allow permission.

const long DEFAULT_DENIED = -1

Indicates that the user has not made a permissions decision, but the user agent's default policy is to deny permission.

const long USER_DENIED = -2

Indicates that the user has denied permission.

long permissionLevel (in DOMString feature) raises(Exception)

Returns the permission level of a feature.

in DOMString feature

A string containing a feature id.

If feature does not identify a feature known to the user agent, the user agent must throw an exception.

void requestPermission (in DOMString feature, in Function callback) raises(Exception)

Requests that the user agent ask the user for permission for web pages from the current security origin to use the feature identified by feature. This method should only be called while handling a user gesture; in other circumstances the user agent should take no action in response.

This method is asynchronous. The function provided in the callback parameter will be invoked when the user has responded to the permission request.

If the current permission level is DEFAULT_DENIED, the user agent should display a prompt to the user requesting permission for pages in the current security origin to user the feature identified by feature, which allows the user to allow or deny permission.

If the user allows permission, the current permission level should change to USER_ALLOWED, and the callback function should be called.

If the user denies permission, the current permission level should change to USER_DENIED, and the callback function should be called.

If the current permission level is USER_ALLOWED, DEFAULT_ALLOWED, or USER_DENIED, the user agent should not prompt the user, and call callback immediately.

in DOMString feature

A string containing a feature id.

in Function callback

A callback function to be called when the permission level is determined, such as by the user responding to a permission dialog.

If feature does not identify a feature known to the user agent, the user agent must throw an exception.

attribute DOMString[] privilegedFeatures

Contains an array of strings which represent the valid feature identifiers that can be used in permissionLevel and requestPermission.

Default permission levels

The NavigatorPermissions interface requires the user agent to indicate DEFAULT_ALLOWED and DEFAULT_DENIED permission levels for feature/origin combinations where the user has not made an explicit decision.

The purpose of the distinction between user-selected and default behavior is to allow the web page to present appropriate user interfaces advising the user of the need for permission and what actions should be taken to ensure permission is granted.

The user agent may select appropriate initial default settings for each feature, but must not indicate USER_ALLOWED or USER_DENIED until the user has made a permissions decision.