/
index.bs
127 lines (101 loc) · 5.05 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
<pre class='metadata'>
Title: Requesting Permissions
Shortname: permissions-request
Level: 1
Status: CG-DRAFT
Group: WICG
Repository: jyasskin/permissions-request
URL: https://jyasskin.github.io/permissions-request
Editor: Balazs Engedy, w3cid 113009, Google Inc. https://google.com/, engedy@google.com
Former Editor: Jeffrey Yasskin, w3cid 72192, Google Inc. https://google.com/, jyasskin@google.com
!Tests: <a href=https://github.com/w3c/web-platform-tests/tree/master/permissions-request>web-platform-tests permissions-request/</a> (<a href=https://github.com/w3c/web-platform-tests/labels/permissions-request>ongoing work</a>)
!Polyfills: <a href="https://github.com/chromium/permissions.request">chromium/permissions.request</a>
Abstract: This specification extends the Permissions API to provide a uniform function for requesting permission to use powerful features.
</pre>
<pre class="link-defaults">
spec: permissions
type: dfn
text: create a permissionstatus
</pre>
# Introduction # {#intro}
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.
# Request API # {#api}
<xmp class=idl>
partial interface Permissions {
Promise<PermissionStatus> request(object permissionDesc);
};
</xmp>
When the <dfn for='Permissions' method>request(permissionDesc)</dfn> method is
invoked, the user agent MUST run the following algorithm, passing the parameter
|permissionDesc|:
<ol class="algorithm">
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.
1. Let |typedDescriptor| be the object |permissionDesc| refers to, [=converted
to an IDL value=] of <code>|rootDesc|.{{PermissionDescriptor/name}}</code>'s
[=permission descriptor type=]. If this throws an exception, return [=a
promise rejected with=] that exception and abort these steps.
1. Let |promise| be a newly-created {{Promise}}.
1. Return |promise| and continue the following steps asynchronously.
1. Run the steps to [=create a PermissionStatus=] for |typedDescriptor|, and let
|status| be the result.
1. Run the [=permission request algorithm=] of the feature named
<code>|typedDescriptor|.name</code> with |typedDescriptor| and |status| as
arguments.
1. If the previous step threw an exception, [=reject=] |promise| with that
exception.
1. Otherwise resolve |promise| with |status|.
</ol>
# Additional fields in the Permission Registry # {#registry-additions}
Powerful features in the <a
href="https://w3c.github.io/permissions/#permission-registry">Permission
Registry</a> additionally define a <dfn export>permission request
algorithm</dfn>:
: Input
:: * An instance of the [=permission descriptor type=]
* A newly-created instance of the <a>permission result type</a>.
: Behavior
:: Uses the algorithms in <a
href="https://w3c.github.io/permissions/#requesting-more-permission">Requesting
more permission</a> 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
:: * <code>{{Permissions}}.{{Permissions/request(permissionDesc)}}</code>
: Default
:: If unspecified, this defaults to the [=default permission request
algorithm=].
## Default request algorithm ## {#default-request-algorithm}
The <dfn export>default permission request algorithm</dfn>, given a
{{PermissionDescriptor}} <var>permissionDesc</var> and a {{PermissionStatus}}
|status|, runs the following steps:
<ol class="algorithm">
1. Run the [=default permission query algorithm=] on |permissionDesc| and
|status|.
1. If <code>|status|.state</code> is not {{"prompt"}}, abort these steps.
1. [=Request permission to use=] |permissionDesc|.
1. Run the [=default permission query algorithm=] again on |permissionDesc|
and |status|.
<p class="issue" id="issue-non-persistent-grants">
On browsers that don't store permissions persistently within an
<a>environment settings object</a>, this will always return {{"prompt"}},
but still show the user an unnecessary prompt. That may mean that no
permissions should use the <a>default permission request algorithm</a>,
since it can never return an appropriate object-capability.
</p>
</ol>
# Security Considerations # {#security}
No security considerations have been identified.
# Privacy Considerations # {#privacy}
No privacy considerations have been identified.