The Device APIs Working Group decided to discontinue work on the Feature Permissions draft as the only immediately obvious relevant use case is for Web Notifications. Any follow-up discussions should happen on the public-web-notification mailing list.

This document defines APIs for web pages to request permission to use privileged user agent features.

Definitions

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

The NavigatorPermissions interface provides 3 pieces of functionality, which are added to the Navigator object.

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.