From 71600c4d93cf74ef46d84469628496d2d30ba2f7 Mon Sep 17 00:00:00 2001
From: Reilly Grant Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply. Copyright © 2025 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply. This document is governed by the 03 November 2023 W3C Process Document. New features since publication as a Candidate Recommendation include integration of Permissions Policy and API, which now requires explicit user consent through New features since publication as a Candidate Recommendation include integration of Permissions Policy and API, which now requires explicit user consent through Device Orientation and Motion
-
+
More details about this document
Device Orientation and Motion
public-webapps@w3.org (subscribe, archives).
requestPermission()
for accessing device orientation data. Updates have been made to the coordinate system explanations and precision requirements to mitigate passive fingerprinting risks. The introduction of the deviceorientationabsolute event enhances applications requiring absolute orientation data (marked at risk). Interfaces are now only available in secure contexts, and security and privacy considerations have been made normative. The specification now also provides a means to automate testing of this API (marked at risk). See § 10 Changes section for more information.requestPermission()
for accessing device orientation data. Updates have been made to the coordinate system explanations and precision requirements to mitigate passive fingerprinting risks. The introduction of the deviceorientationabsolute event enhances applications requiring absolute orientation data (marked at risk). Interfaces are now only available in secure contexts, and security and privacy considerations have been made normative. The specification now also provides a means to automate testing of this API (marked at risk). See § 10 Changes section for more information.
Note: [MOTION-SENSORS] and [GYROSCOPE] both contain a more detailed discussion of gyroscopes, rotation rates and measurements.
DeviceMotionEvent.requestPermission()
and DeviceOrientationEvent.requestPermission()
tests. DeviceMotionEvent.requestPermission()
and DeviceOrientationEvent.requestPermission()
tests. This specification is a powerful feature and, as such, it defines the following permissions which are policy-controlled features with the given default allowlists:
DeviceOrientationEvent
: constructor
(type
, eventInitDict
= {});
+ constructor
(type
, eventInitDict
= {});
absolute
= absolute
= DeviceOrientationEventInit
: alpha
= beta
= gamma
= absolute
= alpha
= beta
= gamma
= absolute
= The ondeviceorientation
attribute is an event handler IDL attribute for the ondeviceorientation
event handler, whose event handler event type is deviceorientation
.
Let global be the current global object.
Let hasTransientActivation be true if this's relevant global object has transient activation, and false otherwise.
+Let hasTransientActivation be true if this’s relevant global object has transient activation, and false otherwise.
Let promise be a new promise in this's relevant Realm.
+Let promise be a new promise in this’s relevant Realm.
Let permissions be « "accelerometer", "gyroscope" ».
Let orientation be null.
Let topLevelTraversable be window’s navigable's top-level traversable.
+Let topLevelTraversable be window’s navigable’s top-level traversable.
Let virtualSensorType be "relative-orientation
" if absolute is false, and "absolute-orientation
" otherwise.
Note: Implementations must take § 9 Automation into account to determine whether a significant change in orientation has occurred, so that a virtual sensor reading update causes it to be assessed.
Let document be window’s associated Document.
@@ -1389,7 +1462,7 @@If an implementation can never provide orientation information, the event should be fired with the alpha
, beta
and gamma
attributes set to null, and the absolute
attribute set to false.
deviceorientationabsolute
event and its ondeviceorientationabsolute
event handler IDL attribute are at risk due to limited implementation experience. deviceorientationabsolute
event and its ondeviceorientationabsolute
event handler IDL attribute are at risk due to limited implementation experience. partial interface Window { [SecureContext ]attribute EventHandler ondeviceorientationabsolute ; }; @@ -1397,7 +1470,7 @@
The ondeviceorientationabsolute
attribute is an event handler IDL attribute for theondeviceorientationabsolute
event handler, whose event handler event type isdeviceorientationabsolute
.A deviceorientationabsolute event is completely analogous to the deviceorientation event, except that it must always provide absolute orientation data.
- Whenever a significant change in orientation occurs, the user agent must execute the following steps on a navigable's active window window: + Whenever a significant change in orientation occurs, the user agent must execute the following steps on a navigable’s active window window:
Fire an orientation event with deviceorientationabsolute, window, and true.
@@ -1425,9 +1498,9 @@
x
getter steps are to return the value of this's x axis acceleration. -The
-y
getter steps are to return the value of this's y axis acceleration.The
+z
getter steps are to return the value of this's z axis acceleration.The
+x
getter steps are to return the value of this’s x axis acceleration.The
+y
getter steps are to return the value of this’s y axis acceleration.The
z
getter steps are to return the value of this’s z axis acceleration.6.3.2. The DeviceMotionEventRotationRate interface
[Exposed =Window ,SecureContext ]interface { @@ -1448,9 +1521,9 @@
DeviceMotionEventRotationRate
alpha
getter steps are to return the value of this's x axis rotation rate. -The
-beta
getter steps are to return the value of this's y axis rotation rate.The
+gamma
getter steps are to return the value of this's z axis rotation rate.The
+alpha
getter steps are to return the value of this’s x axis rotation rate.The
+beta
getter steps are to return the value of this’s y axis rotation rate.The
gamma
getter steps are to return the value of this’s z axis rotation rate.6.3.3. The DeviceMotionEvent interface
partial interface Window { [SecureContext ]attribute EventHandler ondevicemotion ; @@ -1458,7 +1531,7 @@
Exposed =Window ,SecureContext ]interface :
DeviceMotionEvent Event { -(
constructor DOMString ,
type optional DeviceMotionEventInit = {}); +
eventInitDict (
constructor DOMString ,
type optional DeviceMotionEventInit = {});
eventInitDict readonly attribute DeviceMotionEventAcceleration ?acceleration ;readonly attribute DeviceMotionEventAcceleration ?accelerationIncludingGravity ;readonly attribute DeviceMotionEventRotationRate ?rotationRate ; @@ -1468,22 +1541,22 @@
dictionary { -
DeviceMotionEventAccelerationInit double ?=
x null ; -double ?=
y null ; -double ?=
z null ; +double ?=
x null ; +double ?=
y null ; +double ?=
z null ; };dictionary { -
DeviceMotionEventRotationRateInit double ?=
alpha null ; -double ?=
beta null ; -double ?=
gamma null ; +double ?=
alpha null ; +double ?=
beta null ; +double ?=
gamma null ; };dictionary :
DeviceMotionEventInit EventInit { -DeviceMotionEventAccelerationInit ; -
acceleration DeviceMotionEventAccelerationInit ; -
accelerationIncludingGravity DeviceMotionEventRotationRateInit ; -
rotationRate double = 0; +
interval DeviceMotionEventAccelerationInit ; +
acceleration DeviceMotionEventAccelerationInit ; +
accelerationIncludingGravity DeviceMotionEventRotationRateInit ; +
rotationRate double = 0; };
interval The
@@ -1497,9 +1570,9 @@ondevicemotion
attribute is an event handler IDL attribute for theondevicemotion
event handler, whose event handler event type isdevicemotion
.
Let global be the current global object.
- -
Let hasTransientActivation be true if this's relevant global object has transient activation, and false otherwise.
+Let hasTransientActivation be true if this’s relevant global object has transient activation, and false otherwise.
- -
Let result be a new promise in this's relevant Realm.
+Let result be a new promise in this’s relevant Realm.
Run these steps in parallel:
@@ -1534,14 +1607,13 @@
Queue a global task on the device motion and orientation task source given global to resolve result with permissionState.
-Return result.
- At an implementation-defined interval interval, the user agent must execute the following steps on a navigable's active window window: + At an implementation-defined interval interval, the user agent must execute the following steps on a navigable’s active window window:
Let document be window’s associated Document.
@@ -1554,7 +1626,7 @@
If document is not allowed to use the policy-controlled feature named policy, return. - -
Let topLevelTraversable be window’s navigable's top-level traversable.
+Let topLevelTraversable be window’s navigable’s top-level traversable.
Let platformLinearAcceleration be null.
- @@ -1700,11 +1772,11 @@
Furthermore, to minimize privacy risks, the chance of fingerprinting and other attacks the implementations must:
@@ -1736,7 +1808,7 @@
- -
fire events only when a navigable's active document's visibility state is "
+visible
",fire events only when a navigable’s active document’s visibility state is "
visible
",implement § 4 Permissions so that events are fired on child navigables (including but not restricted to cross-origin ones) only if allowed by the top-level traversable,
- -
fire events on a navigable's active windows only when its relevant settings object is a secure context,
+fire events on a navigable’s active windows only when its relevant settings object is a secure context,
limit precision of attribute values as described in the previous sections.
8. It is also important that the device’s orientation can be locked - a primary use case being someone who is interacting with a touch device, such as a phone, non-visually. They may have built up 'muscle memory' as to where elements are on the screen in a given orientation, and having the layout shift would break their ability to navigate. Again, this would most likely be done at the operating system level.
9. Automation
-This feature is at risk due to limited implementation experience.+This feature is at risk due to limited implementation experience.This specification can pose a challenge to test authors, as the events defined here depend on the presence of physical hardware whose readings cannot be easily controlled.
To address this challenge, this document builds upon the [WEBDRIVER2] extension commands and infrastructure laid out by Generic Sensor API § 9 Automation. This was chosen over the option of developing completely new and independent infrastructure with separate extension commands because there is significant overlap between the two specifications: not only does testing the [GENERIC-SENSOR] specification present similar challenges, but many derived APIs (e.g. [GYROSCOPE]) obtain and provide similar information.
This specification only requires implementations to support the Generic Sensor API § 9 Automation section of the [GENERIC-SENSOR] specification, not its interfaces and events.
@@ -1801,7 +1873,7 @@Key
- - +
"
accelerometer
"- Value
A virtual sensor metadata whose reading parsing algorithm is parse xyz reading.
@@ -1811,7 +1883,7 @@Key
- - +
"
linear-acceleration
"- Value
A virtual sensor metadata whose reading parsing algorithm is parse xyz reading.
@@ -1821,7 +1893,7 @@
- Key
- - +
"
gyroscope
"- Value
A virtual sensor metadata whose reading parsing algorithm is parse xyz reading.
@@ -1834,9 +1906,7 @@A.1 Calcul
Introduction section provided an example of using the DeviceOrientation event to obtain a compass heading when the device is held with the screen horizontal. This example shows how to determine the compass heading that the user is facing when holding the device with the screen approximately vertical in front of them. An application of this is an augmented-reality system.
More precisely, we wish to determine the compass heading of the horizontal component of a vector which is orthogonal to the device’s screen and pointing out of the back of the screen.
If v represents this vector in the rotated device body frame xyz, then v is as follows.
- +The transformation of v due to the rotation about the z axis can be represented by the following rotation matrix.
The transformation of v due to the rotation about the x axis can be represented by the following rotation matrix.
@@ -1849,7 +1919,7 @@A.1 Calcul
The compass heading θ is given by
- +provided that β and γ are not both zero.
- +Index
Terms defined by this specification
@@ -2262,7 +2332,7 @@
[GENERIC-SENSOR] defines the following terms:
- can provide readings flag -
- parse xyz reading +
- Parse XYZ reading
- per-type virtual sensor metadata
- reading parsing algorithm
- sensor reading @@ -2284,12 +2354,12 @@
active document
- active window
- allowed to use -
- associated document +
- associated Document
- child navigable
- current global object
- event handler
- event handler event type -
- event handler idl attribute +
- event handler IDL attribute
- in parallel
- navigable
- navigable (for Window) @@ -2323,7 +2393,7 @@
[ORIENTATION-SENSOR] defines the following terms:
-
- earth's reference coordinate system +
- Earth's reference coordinate system
- [PERMISSIONS] defines the following terms: @@ -2351,7 +2421,7 @@
[W3C-PROCESS] defines the following terms:
-
- at risk +
- at risk
- [WEBDRIVER2] defines the following terms: @@ -2401,7 +2471,7 @@
N
- [RFC2119]
- S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
- [W3C-PROCESS] -
- Elika J. Etemad (fantasai); Florian Rivoal. W3C Process Document. 2 November 2021. URL: https://www.w3.org/Consortium/Process/ +
- Elika J. Etemad (fantasai); Florian Rivoal. W3C Process Document. 3 November 2023. URL: https://www.w3.org/policies/process/
- [WEBDRIVER2]
- Simon Stewart; David Burns. WebDriver. URL: https://w3c.github.io/webdriver/
- [WEBIDL] @@ -2455,10 +2525,10 @@
I };
dictionary :
DeviceOrientationEventInit EventInit { -double ?=
alpha null ; -double ?=
beta null ; -double ?=
gamma null ; -boolean =
absolute false ; +double ?=
alpha null ; +double ?=
beta null ; +double ?=
gamma null ; +boolean =
absolute false ; };partial interface Window { @@ -2495,22 +2565,22 @@I };
dictionary { -
DeviceMotionEventAccelerationInit double ?=
x null ; -double ?=
y null ; -double ?=
z null ; +double ?=
x null ; +double ?=
y null ; +double ?=
z null ; };dictionary { -
DeviceMotionEventRotationRateInit double ?=
alpha null ; -double ?=
beta null ; -double ?=
gamma null ; +double ?=
alpha null ; +double ?=
beta null ; +double ?=
gamma null ; };dictionary :
DeviceMotionEventInit EventInit { -DeviceMotionEventAccelerationInit ; -
acceleration DeviceMotionEventAccelerationInit ; -
accelerationIncludingGravity DeviceMotionEventRotationRateInit ; -
rotationRate double = 0; +
interval DeviceMotionEventAccelerationInit ; +
acceleration DeviceMotionEventAccelerationInit ; +
accelerationIncludingGravity DeviceMotionEventRotationRateInit ; +
rotationRate double = 0; }; @@ -2905,455 +2975,8 @@
interval I