Requesting Permissions

1. Introduction

This document specifies a function to request permission to use powerful features on the Web platform.

Different Web APIs have disparate ways to signal a developer’s intent to use them:

• The [notifications] API allows developers to request a permission and check the permission status explicitly.

• The [geolocation-API] conflates the permission request with a location request.

It’s easier for developers to design their permission-related code if they have a single pattern to follow for all powerful features.

2. Request API

partial interface Permissions {
  Promise<PermissionStatus> request(object permissionDesc);
};

When the request(permissionDesc) method is invoked, the user agent MUST run the following algorithm, passing the parameter permissionDesc:

1. Let rootDesc be the object permissionDesc refers to, converted to an IDL value of type PermissionDescriptor. If this throws an exception, return a promise rejected with that exception and abort these steps.

2. Let typedDescriptor be the object permissionDesc refers to, converted to an IDL value of rootDesc.name’s permission descriptor type. If this throws an exception, return a promise rejected with that exception and abort these steps.

3. Let promise be a newly-created Promise.

4. Return promise and continue the following steps asynchronously.

5. Run the steps to create a PermissionStatus for typedDescriptor, and let status be the result.

6. Run the permission request algorithm of the feature named typedDescriptor.name with typedDescriptor and status as arguments.

7. If the previous step threw an exception, reject promise with that exception.

8. Otherwise resolve promise with status.

3. Additional fields in the Permission Registry

Powerful features in the Permission Registry additionally define a permission request algorithm:

Input

• An instance of the permission descriptor type

• A newly-created instance of the permission result type.

Behavior

Uses the algorithms in Requesting more permission to show the user any necessary prompt to try to increase permissions, and updates the instance of the permission result type to match.

Returns

Nothing, but may throw an exception if the request can fail exceptionally. (Merely being denied permission is not exceptional.)

Example callers

• Permissions.request(permissionDesc)

Default

If unspecified, this defaults to the default permission request algorithm.

3.1. Default request algorithm

The default permission request algorithm, given a PermissionDescriptor permissionDesc and a PermissionStatus status, runs the following steps:

1. Run the default permission query algorithm on permissionDesc and status.

2. If status.state is not "prompt", abort these steps.

3. Request permission to use permissionDesc.

4. Run the default permission query algorithm again on permissionDesc and status.

   On browsers that don’t store permissions persistently within an environment settings object, this will always return "prompt", but still show the user an unnecessary prompt. That may mean that no permissions should use the default permission request algorithm, since it can never return an appropriate object-capability.

4. Security Considerations

No security considerations have been identified.

5. Privacy Considerations

No privacy considerations have been identified.