From deeac36746027bd80183e52de125db7ebc880d8a Mon Sep 17 00:00:00 2001 From: Chris Dumez Date: Fri, 1 Feb 2019 13:51:17 -0800 Subject: [PATCH] Add permission request API Add requestPermission() static operation to both DeviceOrientationEvent and DeviceMotionEvent so that JavaScript can request permission to use the API so that user agents may ask the user before sharing the device orientation & motion with the page. Fixes: #57 --- index.bs | 110 +++++++++++++++++++++++++++++++++++- index.html | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 268 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 810bd93..bf8ff8b 100644 --- a/index.bs +++ b/index.bs @@ -164,6 +164,8 @@ interface DeviceOrientationEvent : Event { readonly attribute double? beta; readonly attribute double? gamma; readonly attribute boolean absolute; + + static Promise<PermissionState> requestPermission(); }; dictionary DeviceOrientationEventInit : EventInit { @@ -172,6 +174,11 @@ dictionary DeviceOrientationEventInit : EventInit { double? gamma = null; boolean absolute = false; }; + +enum PermissionState { + "granted", + "denied", +}; The {{DeviceOrientationEvent/alpha}} attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to null. @@ -182,6 +189,39 @@ The {{DeviceOrientationEvent/gamma}} attribute must return the value it was init The {{DeviceOrientationEvent/absolute}} attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to false. +The static {{DeviceOrientationEvent/requestPermission()}} operation, when invoked, must run these steps: +
    +

  1. Let promise be a new promise. + +

  2. +

    Run these steps in parallel: + +

      +

    1. Let permission be permission for + relevant settings object's origin. + +

    2. If permission is "default" and the method call was not triggered by user activation, then reject promise with a + NotAllowedError exception and abort these steps. + +

    3. If permission is "default", ask the user whether sharing device orientation + for the relevant settings object's + origin is acceptable. If it is, set + permission to "granted", and "denied" otherwise. + +

    4. +

      Queue a task to run these steps: + +

        +

      1. Set permission for the relevant settings object's + origin to permission. + +

      2. Fullfill promise with permission. +

      +
    + +

  3. Return promise. +

+ The event should fire whenever a significant change in orientation occurs. The definition of a significant change in this context is left to the implementation, though a maximum threshold for change of one degree is recommended. Implementations may also fire the event if they have reason to believe that the page does not have sufficiently fresh data. The {{DeviceOrientationEvent/alpha}}, {{DeviceOrientationEvent/beta}} and {{DeviceOrientationEvent/gamma}} attributes of the event must specify the orientation of the device in terms of the transformation from a coordinate frame fixed on the Earth to a coordinate frame fixed in the device. The coordinate frames must be oriented as described below. @@ -297,6 +337,8 @@ interface DeviceMotionEvent : Event { readonly attribute DeviceMotionEventAcceleration? accelerationIncludingGravity; readonly attribute DeviceMotionEventRotationRate? rotationRate; readonly attribute double interval; + + static Promise<PermissionState> requestPermission(); }; dictionary DeviceMotionEventAccelerationInit { @@ -327,6 +369,39 @@ The {{DeviceMotionEvent/rotationRate}} attribute must return the value it was in The {{DeviceMotionEvent/interval}} attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to 0. +The static {{DeviceMotionEvent/requestPermission()}} operation, when invoked, must run these steps: +
    +

  1. Let promise be a new promise. + +

  2. +

    Run these steps in parallel: + +

      +

    1. Let permission be permission for + relevant settings object's origin. + +

    2. If permission is "default" and the method call was not triggered by user activation, then reject promise with a + NotAllowedError exception and abort these steps. + +

    3. If permission is "default", ask the user whether sharing device motion + for the relevant settings object's + origin is acceptable. If it is, set + permission to "granted", and "denied" otherwise. + +

    4. +

      Queue a task to run these steps: + +

        +

      1. Set permission for the relevant settings object's + origin to permission. + +

      2. Fullfill promise with permission. +

      +
    + +

  3. Return promise. +

+ In the {{DeviceMotionEvent}} events fired by the user agent, the following requirements must apply: The {{DeviceMotionEvent/acceleration}} attribute must be initialized with the acceleration of the hosting device relative to the Earth frame, expressed in the body frame, as defined in [[#deviceorientation|deviceorientation Event]] section. The acceleration must be expressed in meters per second squared (m/s2). @@ -339,6 +414,31 @@ The {{DeviceMotionEvent/interval}} attribute must be initialized with the interv Implementations that are unable to provide all attributes must initialize the values of the unknown attributes to null. If an implementation can never provide motion information, the event should be fired with the {{DeviceMotionEvent/acceleration}}, {{DeviceMotionEvent/accelerationIncludingGravity}} and {{DeviceMotionEvent/rotationRate}} attributes set to null. +

Permission model

+ +

Implementations may choose to share device orientation & motion only if the +user (or user agent on behalf of the user) has granted permission. +The permission to share device orientation & motion +for a given origin is one of three strings: + +

+
"default" +

This is equivalent to "denied", but the user has made no + explicit choice thus far. + +

"denied" +

This means the user does not want + to share device orientation or motion. + +

"granted" +

This means device orientation or motion may be shared. +

+ +

There is no equivalent to "default" +meaning "granted". In that case +"granted" is simply returned as there would be no reason +for the application to ask for permission. + Security and privacy considerations {#security-and-privacy} =========================================================== @@ -609,7 +709,15 @@ as expected.

Acknowledgments

-Lars Erik Bolstad, Dean Jackson, Claes Nilsson, George Percivall, Doug Turner, Matt Womer +Lars Erik Bolstad, Dean Jackson, Claes Nilsson, George Percivall, Doug Turner, Matt Womer, Chris Dumez + +
+urlPrefix: https://html.spec.whatwg.org/multipage/
+    urlPrefix: webappapis.html; type: dfn
+        text: relevant settings object
+    urlPrefix: interaction.html; type: dfn
+        text: triggered by user activation
+
 {
diff --git a/index.html b/index.html
index 7e1bf5f..2a5c7dd 100644
--- a/index.html
+++ b/index.html
@@ -1219,8 +1219,9 @@
       background-attachment: fixed;
     }
   
-  
+  
   
+