1. Introduction
Increasingly, sensor data is used in application development to enable new use cases such as geolocation, counting steps or head-tracking. This is especially true on mobile devices where new sensors are added regularly.
Exposing sensor data to the Web has so far been both slow-paced and ad-hoc. Few sensors are already exposed to the Web. When they are, it is often in ways that limit their possible use cases (for example by exposing abstractions that are too high-level and which don’t perform well enough). APIs also vary greatly from one sensor to the next which increases the cognitive burden of Web application developers and slows development.
The goal of the Generic Sensor API is to promote consistency across sensor APIs, enable advanced use cases thanks to performant low-level APIs, and increase the pace at which new sensors can be exposed to the Web by simplifying the specification and implementation processes.
A comprehensive list of concrete sensors that are based on Generic Sensor API, applicable use cases, and code examples can be found in [GENERIC-SENSOR-USECASES] and [MOTION-SENSORS] explainer documents.
2. Scope
This section is non-normative .
The scope of this specification is currently limited to specifying primitives which enable exposing data from device sensors .
Exposing remote sensors or sensors found on personal area networks (e.g. Bluetooth) is out of scope. As work in these areas mature, it is possible that common, lower-level primitives be found, in which case this specification will be updated accordingly. This should have little to no effects on implementations, however.
This specification also does not currently expose a sensor discovery API. This is because the limited number of sensors currently available to user agents does not warrant such an API. Using feature detection, such as described in §3 A note on Feature Detection of Hardware Features , is good enough for now. A subsequent version of this specification might specify such an API, and the current API has been designed with this in mind.
3. A note on Feature Detection of Hardware Features
This section is non-normative.
Feature detection is an established Web development best practice. Resources on the topic are plentiful on and offline and the purpose of this section is not to discuss it further, but rather to put it in the context of detecting hardware-dependent features.
Consider the below feature detection examples:
if (typeof Gyroscope === "function") { // run in circles... } if ("ProximitySensor" in window) { // watch out! } if (window.AmbientLightSensor) { // go dark... } // etc.
All of these tell you something about the presence and possible characteristics of an API. They do not tell you anything, however, about whether that API is actually connected to a real hardware sensor, whether that sensor works, if its still connected, or even whether the user is going to allow you to access it. Note you can check the latter using the Permissions API [PERMISSIONS] .
In an ideal world, information about the underlying status would be available upfront. The problem with this is twofold. First, getting this information out of the hardware is costly, in both performance and battery time, and would sit in the critical path. Secondly, the status of the underlying hardware can evolve over time. The user can revoke permission, the connection to the sensor be severed, the operating system may decide to limit sensor usage below a certain battery threshold, etc.
Therefore, an effective strategy is to combine feature detection, which checks whether an API for the sought-after sensor actually exists, and defensive programming which includes:
-
checking for error thrown when instantiating a
Sensor
object, -
listening to errors emitted by it,
-
handling all of the above graciously so that the user’s experience is enhanced by the possible usage of a sensor, not degraded by its absence.
try { // No need to feature detect thanks to try..catch block. var sensor = new GeolocationSensor(); sensor.start(); sensor.onerror = error => gracefullyDegrade(error); sensor.onreading = _ => updatePosition(sensor.latitude, sensor.longitude); } catch(error) { gracefullyDegrade(error); }
4. Security and privacy considerations
Sensor readings are sensitive data and could become a subject of various attacks from malicious Web pages. Before discussing the mitigation strategies we briefly enumerate the main types of the sensor 's privacy and security threats. The [MOBILESENSORS] categorizes main threats into location tracking , eavesdropping , keystroke monitoring , device fingerprinting , and user identification . This categorization is a good fit for this specification.
The risk of successful attack can increase when sensors are used with each other, in combination with other functionality, or when used over time, specifically with the risk of correlation of data and user identification through fingerprinting. Web application developers using these JavaScript APIs should consider how this information might be correlated with other information and the privacy risks that might be created. The potential risks of collection of such data over a longer period of time should also be considered.
Variations in sensor readings as well as event firing rates offer the possibility of fingerprinting to identify users. User agents may reduce the risk by limiting event rates available to web application developers.
Minimizing the accuracy of a sensor’s readout generally decreases the risk of fingerprinting. User agents should not provide unnecessarily verbose readouts of sensors data. Each sensor type should be assessed individually.
If the same JavaScript code using the API can be used simultaneously in different window contexts on the same device it may be possible for that code to correlate the user across those two contexts, creating unanticipated tracking mechanisms.
User agents should consider providing the user an indication of when the sensor is used and allowing the user to disable it. Additionally, user agents may consider allowing the user to verify past and current sensor use patterns.
Web application developers that use sensors should perform a privacy impact assessment of their application taking all aspects of their application into consideration.
Ability to detect a full working set of sensors on a device can form an identifier and could be used for fingerprinting.
A combination of selected sensors can potentially be used to form an out of band communication channel between devices.
Sensors can potentially be used in cross-device linking and tracking of a user.
4.1. Types of privacy and security threats
This section is non-normative.
4.1.1. Location Tracking
Under this type of threat, the attacks use sensor readings to locate the device without using GPS or any other location sensors. For example, accelerometer data can be used to infer the location of smartphones by using statistical models to obtain estimated trajectory, then map matching algorithms can be used to obtain predicted location points (within a 200-m radius) [MOBILESENSORS] .
4.1.2. Eavesdropping
Recovering speech from gyroscope readings is an example of eavesdropping attack. See [GYROSPEECHRECOGNITION] .
4.1.3. Keystroke Monitoring
Many user inputs can be inferred from sensor readings , this includes a wide range of attacks on user PINs, passwords, and lock patterns (and even touch actions such as click, scroll, and zoom) using motion sensors. These attacks normally train a machine learning algorithm to discover such information about the users. See [STEALINGPINSVIASENSORS] .
4.1.4. Device Fingerprinting
Sensors can provide information that can uniquely identify the device using those sensors. Every concrete sensor model has minor manufacturing imperfections and differences that will be unique for this model. These manufacturing variations and imperfections can be used to fingerprint the device [MOBILESENSORS] .
4.1.5. User Identifying
Sensor readings can be used to identify the user, for example via inferring individual walking patterns from smartphone or wearable device motion sensors' data.
4.2. Mitigation Strategies
This section is non-normative.
This section gives a high-level presentation of some of the mitigation strategies specified in the normative sections of this specification.
4.2.1. Secure Context
Sensor readings are explicitly flagged by the Secure Contexts specification [POWERFUL-FEATURES] as a high-value target for network attackers. Thus all interfaces defined by this specification or extension specifications are only available within a secure context .
4.2.2. Feature Policy
To avoid the privacy risk of sharing sensor readings with contexts unfamiliar to the user, sensor readings are only available for the documents which are allowed to use the policy-controlled features for the given sensor type . See [FEATURE-POLICY] for more details.
4.2.3. Losing Focus
When the top-level browsing context loses focus, or when an element from the nested browsing context of a different origin gains focus (for example when the user carries out an in-game purchase using a third party payment service from within an iframe) the top-level browsing contexts suddenly becomes in a position to carry out a skimming attack against the browsing context whose element has gained focus .
To mitigate this risk sensor readings are only available to the browsing contexts of the same origin with the context containing the focused element.
4.2.4. Visibility State
Sensor readings are only available for the active documents whose visibility state is "visible".
4.2.5. Permissions API
Access to sensor readings are controlled by the Permissions API [PERMISSIONS] . User agents use a number of criteria to grant access to the readings . Note that access can be granted without prompting the user.
4.3. Mitigation strategies applied on a case by case basis
Each sensor type will need to be assessed individually, taking into account the use cases it enables and its particular threat profile. While some of the below mitigation strategies are effective for certain sensors, they might also hinder or altogether prevent certain use cases.
Note: These mitigation strategies can be applied constantly or temporarily, for example when the user is carrying out specific actions, when other APIs which are known to amplify the level of the threat are in use, etc.
4.3.1. Limit maximum sampling frequency
User agents may mitigate certain threats by limiting the maximum sampling frequency . What upper limit to choose depends on the sensor type , the kind of threats the user agent is trying to protect against, the expected resources of the attacker, etc.
Limiting the maximum sampling frequency prevents use cases which rely on low latency or high data density.
4.3.2. Stop the sensor altogether
This is obviously a last-resort solution, but it can be extremely effective if it’s temporal, for example to prevent password skimming attempts when the user is entering credentials on a different origin ( [rfc6454] ) or in a different application.
4.3.3. Limit number of delivered readings
An alternative to limiting the maximum sampling frequency is to limit the number of sensor readings delivered to Web application developer, regardless of what frequency the sensor is polled at. This allows use cases which have low latency requirement to increase sampling frequency without increasing the amount of data provided.
Discarding intermediary readings prevents certain use cases, such as those relying on certain kinds of filters.
4.3.4. Reduce accuracy
Reducing the accuracy of sensor readings or sensor reading timestamps might also help mitigate certain threats, thus user agents should not provide unnecessarily verbose readouts of sensors data.
Note: Inaccuracies will further increase for operations carried out on the sensor readings , or time deltas calculated from the timestamps . So, this mitigation strategy can affect certain use cases.
Note: while adding random bias to sensor readings has similar effects, it shouldn’t be used in practice as it is easy to filter out the added noise.
4.3.5. Keep the user informed about API use
User agents may choose to keep the user informed about current and past use of the API.
Note: this does not imply keeping a log of the actual sensor readings which would have issues of its own.
5. Concepts
5.1. Sensors
The term device sensor refers to a device’s underlying physical sensor instance.
The device sensors measure different physical quantities and provide corresponding raw sensor readings which are a source of information about the user and their environment.
Each reading is composed of the values of the different physical quantities measured by the sensor at time t n which is called the reading timestamp .
Known, predictable discrepancies between raw sensor readings and the corresponding physical quantities being measured are corrected through calibration .
Known but unpredictable discrepancies need to be addressed dynamically through a process called sensor fusion .
Calibrated raw sensor readings are referred to as sensor readings , whether or not they have undergone sensor fusion .
The term platform sensor refers to platform interfaces, with which the user agent ineracts to obtain sensor readings for a single sensor type originated from one or several device sensors .
Platform sensor can be defined by the underlying platform (e.g. in a native sensors framework) or by the user agent, if it has a direct access to device sensor .
From the implementation perspective platform sensor can be treated as a software proxy for the corresponding device sensor . It is possible to have multiple platform sensors simultaneously interacting with the same device sensor if the underlying platform suppports it.
In simple case a platform sensor corresponds to a single device sensor , but if the provided sensor readings are product of sensor fusion performed in software, the platform sensor corresponds to a set of device sensors involved in the sensor fusion process.
Note: platform sensors created through sensor fusion are sometimes called virtual or synthetic sensors. However, the specification doesn’t make any practical distinction between them.
5.2. Sensor Types
Different sensor types measure different physical quantities such as temperature, air pressure, heart-rate, or luminosity.
For the purpose of this specification we distinguish between high-level and low-level sensor types .
Sensor types which are characterized by their implementation are referred to as low-level sensors. For example a Gyroscope is a low-level sensor type .
Sensors
named
after
their
readings
,
regardless
of
the
implementation,
are
said
to
be
high-level
sensors.
For
instance,
geolocation
sensors
provide
information
about
the
user’s
location,
but
the
precise
means
by
which
this
data
is
obtained
is
purposefully
left
opaque
(it
could
come
from
a
GPS
chip,
network
cell
triangulation,
wifi
networks,
etc.
or
any
combination
of
the
above)
and
depends
on
various,
implementation-specific
heuristics.
High-level
sensors
are
generally
the
fruits
of
applying
algorithms
to
low-level
sensors—
That
said,
the
distinction
between
high-level
and
low-level
sensor
types
is
somewhat
arbitrary
and
the
line
between
the
two
is
often
blurred.
For
instance,
a
barometer,
which
measures
air
pressure,
would
be
considered
low-level
for
most
common
purposes,
even
though
it
is
the
product
of
the
sensor
fusion
of
resistive
piezo-electric
pressure
and
temperature
sensors.
Exposing
the
sensors
that
compose
it
would
serve
no
practical
purpose;
who
cares
about
the
temperature
of
a
piezo-electric
sensor?
A
pressure-altimeter
would
probably
fall
in
the
same
category,
while
a
nondescript
altimeter—
Because the distinction is somewhat blurry, extensions to this specification (see §9 Extensibility ) are encouraged to provide domain-specific definitions of high-level and low-level sensors for the given sensor types they are targeting.
Sensor readings from different sensor types can be combined together through a process called sensor fusion . This process provides higher-level or more accurate data (often at the cost of increased latency). For example, the readings of a three-axis magnetometer needs to be combined with the readings of an accelerometer to provide a correct bearing.
Smart sensors and sensor hubs have built-in compute resources which allow them to carry out calibration and sensor fusion at the hardware level, freeing up CPU resources and lowering battery consumption in the process.
Sensor fusion can also be carried out in software if it cannot be performed at the hardware level or if an application-specific fusion algorithm is required.
5.3. Default sensor
The Generic Sensor API is designed to make the most common use cases straightforward while still enabling more complex use cases.
Most of devices deployed today do not carry more than one device sensor providing sensor readings of the same type . The use cases which require a set of similar device sensors are rare and generally limited to specific sensor types , such as multiple accelerometers in 2-in-1 laptops.
The
API
therefore
makes
it
easy
to
interact
with
the
device’s
default
(and
often
unique)
sensor
for
each
type
simply
by
instantiating
the
corresponding
Sensor
subclass.
Indeed, without specific information identifying a particular sensor of a given type , the default sensor is chosen by the user agent.
If the underlying platform provides an interface to find the default sensor , the user agent must choose the sensor offered by the platform, otherwise the user agent itself defines which of the sensors present on the device is the default sensor .
let sensor = new Accelerometer({ frequency: 30 }); sensor.onreading = () => { ... } sensor.start();
Note: extension to this specification may choose not to define a default sensor when doing so wouldn’t make sense. For example, it does not make sense to explicitly define a default sensor for geolocation sensor type as the implementation of its interface can use multiple backends.
In cases where multiple device sensors corresponding to the same type may coexist on the same device, specification extension will have to define ways to uniquely identify each one.
var sensor = new DirectTirePressureSensor({ position: "rear", side: "left" }); sensor.onreading = _ => console.log(sensor.pressure); sensor.start();
5.4. Reading change threshold
A platform sensor reports readings to the user agent considering the reading change threshold .
The reading change threshold refers to a value which indicates whether or not the changes in the device sensor 's measurements were significant enough to update the corresponding sensor readings .
The threshold value depends on the surrounding software and hardware environment constraints, e.g., software power consumption optimizations or the underlying device sensor 's accuracy.
5.5. Sampling Frequency and Reporting Frequency
For the purpose of this specification, sampling frequency for a platform sensor is defined as a frequency at which the user agent obtains sensor readings from the underlying platform.
The user agent can request the underlying platform to deliver readings at a certain rate which is called requested sampling frequency .
The sampling frequency is equal to the requested sampling frequency if the underlying platform can support it.
The sampling frequency differs from the requested sampling frequency in the following cases:
-
the requested sampling frequency exceeds upper or lower sampling frequency bounds supported by the underlying platform.
-
the threshold value is significant so that some of the device sensor 's measurements are skipped and the sensor readings are not updated.
The
reporting
frequency
for
a
concrete
Sensor
object
is
defined
as
a
frequency
at
which
onreading
notification
the
"reading"
event
is
called.
fired
at
this
object.
A
Sensor
object
cannot
access
new
readings
at
a
higher
rate
than
the
user
agent
obtains
them
from
the
underlying
platform,
therefore
the
reporting
frequency
can
never
exceed
the
sampling
frequency
for
the
given
sensor
type
.
5.6. Conditions to expose sensor readings
The user agent must verify that all mandatory conditions are satisfied to ensure it can expose sensor readings to a given active document .
The mandatory conditions are the following:
-
Visibility state of the document is "visible".
-
The document is allowed to use all the policy-controlled features associated with the given sensor type .
-
Currently focused area belongs to a document whose origin is same origin-domain with the origin of the given active document .
-
Specific conditions : The extension specifications that add new conditions hook into this specification at this point.
Note: In order to release hardware resources, the user agent can request underlying platform sensor to suspend notifications about newly available readings until it can expose sensor readings .
6. Model
6.1. Sensor Type
A
sensor
type
has
an
associated
interface
whose
inherited
interfaces
contains
Sensor
.
A sensor type has a set of associated sensors .
A sensor type may have a default sensor .
A
sensor
type
has
a
nonempty
set
of
associated
PermissionNames
referred
as
sensor
permission
names
.
Note:
multiple
sensor
types
may
share
the
same
PermissionName
.
A sensor type has a permission revocation algorithm .
To
invoke
the
permission
revocation
algorithm
with
PermissionName
permission_name
,
run
the
following
steps:
-
For each sensor_type whose permission names contains permission_name :
-
For each sensor in sensor_type ’s set of associated sensors ,
-
Invoke revoke sensor permission with sensor as argument.
-
-
A sensor type has a nonempty set of associated feature names referred as sensor feature names .
6.2. Sensor
A platform sensor has an associated set of activated sensor objects . This set is initially empty .
The current browsing context 's platform sensor has an associated latest reading map which holds the latest available sensor readings .
Note: User agents can share latest reading map between different contexts only if the origins of these contexts' active documents are same origin-domain .
Any time a new sensor reading for a platform sensor is obtained and if the user agent can expose sensor readings to the current browsing context 's active document , update latest reading is invoked with the platform sensor and the sensor reading as arguments.
The latest reading map contains an entry whose key is "timestamp" and whose value is a high resolution timestamp that estimates the reading timestamp expressed in milliseconds since the time origin .
Note: The accuracy of the reading timestamp estimate depends on the underlying platform interfaces that expose it.
The latest reading ["timestamp"] is initially set to null, unless the latest reading map caches a previous reading .
The other entries of the latest reading map hold the values of the different quantities measured by the platform sensor . The keys of these entries must match the attribute identifier defined by the sensor type 's associated interface. The return value of the attribute getter is easily obtained by invoking get value from latest reading with the object implementing the sensor type 's associated interface and the attribute identifier as arguments.
The value of all latest reading entries is initially set to null.
A platform sensor has an associated requested sampling frequency which is initially null.
For
a
non
empty
set
of
activated
sensor
objects
the
requested
sampling
frequency
is
equal
to
optimal
sampling
frequency
,
which
is
estimated
by
the
user
agent
taking
into
account
provided
frequencies
of
activated
Sensors
and
sampling
frequency
bounds
defined
by
the
underlying
platform.
Note:
For
example,
the
user
agent
may
estimate
optimal
sampling
frequency
as
a
Least
Common
Denominator
(LCD)
for
a
set
of
provided
frequencies
capped
by
sampling
frequency
bounds
defined
by
the
underlying
platform.
This example illustrates a possible implementation of the described Model .
In
the
diagram
below
several
activated
Sensor
objects
from
two
different
browsing
contexts
interact
with
a
single
device
sensor
.
The
Sensor
object
in
"idle"
state
is
not
among
the
platform
sensor
's
activated
sensor
objects
and
thus
it
does
not
interact
with
the
device
sensor
.
In this example there is a platform sensor instance per browsing context .
The
latest
reading
map
is
shared
between
Sensor
objects
from
the
same
context
and
is
updated
at
rate
equal
to
requested
sampling
frequency
of
the
corresponding
platform
sensor
.
7. API
7.1. The Sensor Interface
[SecureContext, Exposed=Window] interfaceSensor
: EventTarget { readonly attribute booleanactivated
; readonly attribute booleanhasReading
; readonly attribute DOMHighResTimeStamp?timestamp
; voidstart
(); voidstop
(); attribute EventHandleronreading
; attribute EventHandleronactivate
; attribute EventHandleronerror
; }; dictionarySensorOptions
{ doublefrequency
; };
A
Sensor
object
has
an
associated
platform
sensor
.
The task source for the tasks mentioned in this specification is the sensor task source .
The event handler event types for the corresponding Sensor Interface 's event handler attributes are defined in Event handlers section.
navigator.permissions.query({ name: 'accelerometer' }).then(result => { if (result.state === 'denied') { console.log('Permission to use accelerometer sensor is denied.'); return; } let acl = new Accelerometer({frequency: 30}); let max_magnitude = 0; acl.addEventListener('activate', () => console.log('Ready to measure.')); acl.addEventListener('error', error => console.log(`Error: ${error.name}`)); acl.addEventListener('reading', () => { let magnitude = Math.hypot(acl.x, acl.y, acl.z); if (magnitude > max_magnitude) { max_magnitude = magnitude; console.log(`Max magnitude: ${max_magnitude} m/s2`); } }); acl.start(); });
7.1.1. Sensor lifecycle
Note:
the
nodes
in
the
diagram
above
represent
the
states
of
a
Sensor
object
and
they
should
not
be
confused
with
the
possible
states
of
the
underlying
platform
sensor
or
device
sensor
.
When
a
Sensor
object
is
eligible
for
garbage
collection,
the
user
agent
must
invoke
deactivate
a
sensor
object
with
this
object
as
argument.
7.1.2. Sensor internal slots
Instances
of
Sensor
are
created
with
the
internal
slots
described
in
the
following
table:
Internal Slot | Description (non-normative) |
---|---|
[[state]]
|
The
current
state
of
the
Sensor
object
which
is
one
of
"idle",
"activating",
or
"activated".
It
is
initially
"idle".
|
[[frequency]]
|
A
double
representing
frequency
in
Hz
that
is
used
to
calculate
the
requested
sampling
frequency
for
the
associated
platform
sensor
and
to
define
the
upper
bound
of
the
reporting
frequency
for
this
Sensor
object.
This
slot
holds
the
provided
|
[[lastEventFiredAt]]
|
The
high
resolution
timestamp
of
the
latest
sensor
reading
that
was
sent
to
observers
of
the
Sensor
object,
expressed
in
milliseconds
that
passed
since
the
time
origin
.
It
is
initially
null.
|
[[pendingReadingNotification]]
|
A boolean which indicates whether the observers need to be notified after a new sensor reading was reported. It is initially false. |
7.1.3. Sensor.activated
The
getter
of
the
activated
attribute
must
run
these
steps:
-
If this .
[[state]]
is "activated", return true. -
Otherwise, return false.
7.1.4. Sensor.hasReading
The
getter
of
the
hasReading
attribute
must
run
these
steps:
-
Let timestamp be the result of invoking get value from latest reading with this and "timestamp" as arguments.
-
If timestamp is not null, return true.
-
Otherwise, return false.
7.1.5. Sensor.timestamp
The
getter
of
the
timestamp
attribute
returns
the
result
of
invoking
get
value
from
latest
reading
with
this
and
"timestamp"
as
arguments.
7.1.6. Sensor.start()
The
start()
method
must
run
these
steps:
-
Let sensor_state be the value of sensor_instance .
[[state]]
. -
If sensor_state is either "activating" or "activated", then return.
-
Set sensor_instance .
[[state]]
to "activating". -
Run these sub-steps in parallel :
-
let connected be the result of invoking connect to sensor with sensor_instance as argument.
-
If connected is false, then
-
Let e be the result of creating a "
NotReadableError
"DOMException
. -
Queue a task to run notify error with e and sensor_instance as arguments.
-
Return.
-
-
Let permission_state be the result of invoking request sensor access with sensor_instance as argument.
-
If permission_state is "granted",
-
Invoke activate a sensor object with sensor_instance as argument.
-
-
Otherwise, if permission_state is "denied",
-
let e be the result of creating a "
NotAllowedError
"DOMException
. -
Queue a task to run notify error with e and sensor_instance as arguments.
-
-
7.1.7. Sensor.stop()
The
stop()
method
must
run
these
steps:
-
If sensor_instance .
[[state]]
is "idle", then return. -
Set sensor_instance .
[[state]]
to "idle". -
Run these sub-steps in parallel :
-
Invoke deactivate a sensor object with sensor_instance as argument.
-
7.1.8. Sensor.onreading
onreading
is
an
EventHandler
which
is
called
to
notify
that
new
reading
is
available.
7.1.9. Sensor.onactivate
onactivate
is
an
EventHandler
which
is
called
when
this
.
[[state]]
transitions
from
"activating"
to
"activated".
7.1.10. Sensor.onerror
onerror
is
an
EventHandler
which
is
called
whenever
an
exception
cannot
be
handled
synchronously.
7.1.11. Event handlers
The
following
are
the
event
handlers
(and
their
corresponding
event
handler
event
types
)
that
must
be
supported
as
attributes
by
the
objects
implementing
the
Sensor
interface:
event handler | event handler event type |
---|---|
onreading
|
reading
|
onactivate
|
activate
|
onerror
|
error
|
7.2. The SensorErrorEvent Interface
[Constructor
(DOMStringtype
, SensorErrorEventIniterrorEventInitDict
), SecureContext, Exposed=Window] interfaceSensorErrorEvent
: Event { readonly attribute DOMExceptionerror
; }; dictionarySensorErrorEventInit
: EventInit { required DOMExceptionerror
; };
7.2.1. SensorErrorEvent.error
Gets
the
DOMException
object
passed
to
SensorErrorEventInit
.
8. Abstract Operations
8.1. Construct sensor object
- input
-
options , a
SensorOptions
object. - output
-
A
Sensor
object.
-
For each feature_name of the associated sensor feature names ,
-
If active document is not allowed to use the policy-controlled feature named feature_name , then:
-
-
Let sensor_instance be a new
Sensor
object, -
If options .
frequency
is present , then-
Set sensor_instance .
[[frequency]]
to options .frequency
.
Note: there is not guarantee that the requested options .
frequency
can be respected. The actual sampling frequency can be calculated usingSensor
timestamp
attributes. -
-
Set sensor_instance .
[[state]]
to "idle". -
Return sensor_instance .
8.2. Connect to sensor
- input
-
sensor_instance , a
Sensor
object. - output
-
True if sensor instance was associated with a platform sensor , false otherwise.
-
Let type be the sensor type of sensor_instance .
-
If the device has a single device sensor which can provide readings for type , then
-
Associate sensor_instance with a platform sensor corresponding to this device sensor .
-
Return true.
-
-
If the device has multiple device sensors which can provide readings for type , then
-
If type has an associated default sensor , then
-
Associate sensor_instance with a platform sensor corresponding to default sensor .
-
Return true.
-
-
-
Return false.
8.3. Activate a sensor object
- input
-
sensor_instance , a
Sensor
object. - output
-
None
-
Let sensor be the platform sensor associated with sensor_instance .
-
Append sensor_instance to sensor ’s set of activated sensor objects .
-
Invoke set sensor settings with sensor as argument.
-
Queue a task to run notify activated state with sensor_instance as an argument.
8.4. Deactivate a sensor object
- input
-
sensor_instance , a
Sensor
object. - output
-
None
-
Remove all tasks associated with sensor_instance from the task queue associated with sensor task source .
-
Let sensor be the platform sensor associated with sensor_instance .
-
If sensor ’s set of activated sensor objects contains sensor_instance ,
-
Remove sensor_instance from sensor ’s set of activated sensor objects .
-
Invoke set sensor settings with sensor as argument.
-
Set sensor_instance .
[[pendingReadingNotification]]
to false. -
Set sensor_instance .
[[lastEventFiredAt]]
to null.
-
8.5. Revoke sensor permission
- input
-
sensor , a platform sensor .
- output
-
None
-
Let activated_sensors be sensor ’s associated set of activated sensor objects .
-
For each s of activated_sensors ,
-
Invoke deactivate a sensor object with s as argument.
-
Let e be the result of creating a "
NotAllowedError
"DOMException
. -
Queue a task to run notify error with e and s as arguments.
-
8.6. Set sensor settings
- input
-
sensor , a platform sensor .
- output
-
None
-
If sensor ’s set of activated sensor objects is empty ,
-
Set requested sampling frequency to null.
-
For each key → value of latest reading .
-
Set latest reading [ key ] to null.
-
-
Update the user-agent-specific way in which sensor readings are obtained from sensor to no longer provide readings .
-
Return.
-
-
Set requested sampling frequency to optimal sampling frequency .
8.7. Update latest reading
- input
-
sensor , a platform sensor .
-
reading , a sensor reading .
- output
-
None
-
For each key → value of latest reading .
-
Set latest reading [ key ] to the corresponding value of reading .
-
-
Let activated_sensors be sensor ’s associated set of activated sensor objects .
-
Run these sub-steps in parallel :
-
For each s in activated_sensors ,
-
Invoke report latest reading updated with s as an argument.
-
-
8.8. Find the reporting frequency of a sensor object
- input
-
sensor_instance , a
Sensor
object. - output
-
reporting frequency in Hz.
-
Let frequency be null.
-
Let f be sensor_instance .
[[frequency]]
.-
if f is set,
-
set frequency to f capped by the upper and lower sampling frequency bounds for the associated platform sensor .
-
-
Otherwise,
-
user agent can assign frequency to an appropriate value.
-
-
-
return frequency .
8.9. Report latest reading updated
- input
-
sensor_instance , a
Sensor
object. - output
-
None
-
If sensor_instance .
[[pendingReadingNotification]]
is true,-
Return.
-
-
Set sensor_instance .
[[pendingReadingNotification]]
to true. -
Let lastReportedTimestamp be the value of sensor_instance .
[[lastEventFiredAt]]
. -
If lastReportedTimestamp is not set
-
Queue a task to run notify new reading with sensor_instance as an argument.
-
Return.
-
-
Let reportingFrequency be result of invoking Find the reporting frequency of a sensor object .
-
If reportingFrequency is null
-
Queue a task to run notify new reading with sensor_instance as an argument.
-
Return.
-
-
Let reportingInterval be the result of 1 / reportingFrequency .
-
Let timestampDelta be the result of latest reading ["timestamp"] - lastReportedTimestamp .
-
If timestampDelta is greater than or equal to reportingInterval
-
Queue a task to run notify new reading with sensor_instance as an argument.
-
Return.
-
-
Let deferUpdateTime be the result of reportingInterval - timestampDelta .
-
Spin the event loop for a period of time equal to deferUpdateTime .
-
If sensor_instance .
[[pendingReadingNotification]]
is true,-
Queue a task to run notify new reading with sensor_instance as an argument.
-
8.10. Notify new reading
- input
-
sensor_instance , a
Sensor
object. - output
-
None
-
Set sensor_instance .
[[pendingReadingNotification]]
to false. -
Set sensor_instance .
[[lastEventFiredAt]]
to latest reading ["timestamp"]. -
Fire an event named "reading" at sensor_instance .
8.11. Notify activated state
- input
-
sensor_instance , a
Sensor
object. - output
-
None
-
Set sensor_instance .
[[state]]
to "activated". -
Fire an event named "activate" at sensor_instance .
-
Let sensor be the platform sensor associated with sensor_instance .
-
If sensor ’s latest reading ["timestamp"] is not null,
-
Queue a task to run notify new reading with sensor_instance as an argument.
-
8.12. Notify error
- input
-
sensor_instance , a
Sensor
object. -
error , a
DOMException
. - output
-
None
-
Set sensor_instance .
[[state]]
to "idle". -
Fire an event named "error" at sensor_instance using
SensorErrorEvent
with itserror
attribute initialized to error .
8.13. Get value from latest reading
- input
-
sensor_instance , a
Sensor
object. -
key , a string representing the name of the value.
- output
-
A sensor reading value or null.
-
If sensor_instance .
[[state]]
is "activated",-
Let readings be the latest reading of sensor_instance ’s related platform sensor .
-
Return readings [ key ].
-
-
Otherwise, return null.
8.14. Request sensor access
- input
-
sensor_instance , a
Sensor
object. - output
-
A permission state .
-
Let sensor be the platform sensor associated with sensor_instance .
-
Let sensor_permissions be sensor ’s associated set of permission names .
-
Run these sub-steps in parallel :
-
For each permission_name in sensor_permissions ,
-
Let state be the result of requesting permission to use permission_name .
-
If state is "denied"
-
Return "denied".
-
-
-
Otherwise, return "granted".
-
9. Extensibility
This section is non-normative.
This section describes how this specification can be extended to specify APIs for different sensor types .
Such extension specifications are encouraged to focus on a single sensor type , exposing both high and low level as appropriate.
For an up-to-date list of extension specifications , please refer to [GENERIC-SENSOR-USECASES] and [MOTION-SENSORS] documents.
9.1. Security and Privacy
Extension specifications are expected to:
-
conform with the generic mitigation strategies ,
-
consider mitigation strategies applied on a case by case basis ,
-
be evaluated against the Self-Review Questionnaire on Security and Privacy [SECURITY-PRIVACY-QUESTIONNAIRE] ,
-
and in particular, be evaluated against the same-origin policy violations that can arise if sensors expose a new communication channel not governed by the same-origin policy.
9.2. Naming
Sensor
interfaces
for
low-level
sensors
should
be
named
after
their
associated
platform
sensor
.
So
for
example,
the
interface
associated
with
a
gyroscope
should
be
simply
named
Gyroscope
.
Sensor
interfaces
for
high-level
sensors
should
be
named
by
combining
the
physical
quantity
the
platform
sensor
measures
with
the
"Sensor"
suffix.
For
example,
a
platform
sensor
measuring
the
distance
at
which
an
object
is
from
it
may
see
its
associated
interface
called
ProximitySensor
.
Attributes
of
the
Sensor
subclass
that
hold
sensor
readings
values
should
be
named
after
the
full
name
of
these
values.
For
example,
the
Thermometer
interface
should
hold
the
sensor
reading
's
value
in
a
temperature
attribute
(and
not
a
value
or
temp
attribute).
A
good
starting
point
for
naming
are
the
Quantities,
Units,
Dimensions
and
Data
Types
Ontologies
[QUDT]
.
9.3. Unit
Extension specifications must specify the unit of sensor readings .
As per the Technical Architecture Group’s (TAG) API Design Principles [API-DESIGN-PRINCIPLES] , all time measurement should be in milliseconds. All other units should be specified using, in order of preference, and with the exception of temperature (for which Celsius should be favored over Kelvin), the International System of Units (SI), SI derived units, and Non-SI units accepted for use with the SI, as described in the SI Brochure [SI] .
9.4. Exposing High-Level vs. Low-Level Sensors
So far, specifications exposing sensors to the Web platform have focused on high-level sensors APIs. [GEOLOCATION-API] [ORIENTATION-EVENT]
This was a reasonable approach for a number of reasons. Indeed, high-level sensors:
-
convey developer intent clearly,
-
do not require intimate knowledge of how the underlying hardware sensors functions,
-
are easy to use,
-
may enable the User Agent to make significant performance and battery life improvements,
-
help avoid certain privacy and security issues by decreasing the amount and type of information exposed.
However, an increasing number of use cases such as virtual and augmented reality require low-level access to sensors, most notably for performance reasons.
Providing low-level access enables Web application developers to leverage domain-specific constraints and design more performant systems.
Following the precepts of the Extensible Web Manifesto [EXTENNNNSIBLE] , extension specifications should focus primarily on exposing low-level sensor APIs, but should also expose high-level APIs when they are clear benefits in doing so.
9.5. When is Enabling Multiple Sensors of the Same Type Not the Right Choice?
It
is
not
advisable
to
construct
multiple
Sensor
instances
of
the
same
sensor
type
with
equal
construction
parameters,
as
it
can
lead
to
unnecessary
hardware
resources
consumption.
In
cases
when
multiple
observers
are
interested
in
notifications
of
a
newly
available
sensor
reading
,
an
event
listener
can
be
added
on
a
single
Sensor
instance
instead
of
creating
multiple
instances
of
the
same
sensor
type
and
using
simple
onreading
event
handler.
Conversely,
multiple
Sensors
of
the
same
sensor
type
can
be
created
when
they
are
intended
to
be
used
with
different
settings,
such
as:
requested
sampling
frequency
,
accuracy
or
other
settings
defined
in
extension
specifications
.
9.6. Definition Requirements
The following definitions must be specified for each sensor type in extension specifications :
-
An interface whose inherited interfaces contains
Sensor
. This interface must be constructible. Its [Constructor
] must take, as an argument, an optional dictionary whose inherited dictionaries containsSensorOptions
. Its attributes which expose sensor readings are read only and their getters must return the result of invoking get value from latest reading with this and attribute identifier as arguments. -
A
PermissionName
, if the sensor type is not representing sensor fusion (otherwise,PermissionNames
associated with the fusion source sensor types must be used).
An extension specification may specify the following definitions for each sensor types :
-
A dictionary whose inherited dictionaries contains
SensorOptions
. -
A default sensor . Generally, devices are equipped with a single platform sensor of each type , so defining a default sensor should be straightforward. For sensor types where multiple sensors are common, extension specifications may choose not to define a default sensor , especially when doing so would not make sense.
9.7. Extending the Permission API
An
implementation
of
the
Sensor
interface
for
each
sensor
type
must
protect
its
reading
by
associated
PermissionName
or
PermissionDescriptor
.
A
Low-level
sensor
may
use
its
interface
name
as
a
PermissionName
,
for
instance,
"gyroscope"
or
"accelerometer".
Fusion
sensors
must
request
permission
to
access
each
of
the
sensors
that
are
used
as
a
source
of
fusion.
Even though, it might be difficult to reconstruct low-level sensor readings from fused data, some of the original information might be inferred. For example, it is easy to deduce user’s orientation in space if absolute or geomagnetic orientation sensors are used, therefore, these sensors must request permission to use magnetometer as it provides information about orientation of device in relation to Earth’s magnetic field. In contrast, relative orientation sensor does not expose such information, thus, it does not need to request permission to use magnetometer.
Permission
descriptors
can
also
be
used
to
set
maximum
allowed
limits
for
accuracy
or
sampling
frequency
.
An
example
for
a
possible
extension
of
the
Permission
API
for
accelerometer
sensor
is
given
below.
dictionary AccelerometerPermissionDescriptor : PermissionDescriptor { boolean highAccuracy = false; boolean highFrequency = false; };
9.8. Extending the Feature Policy API
An
implementation
of
the
Sensor
interface
for
each
sensor
type
has
one
(if
sensor
fusion
is
not
performed)
or
several
policy-controlled
features
that
control
whether
or
not
this
implementation
can
be
used
in
a
document.
The
features
'
default
allowlist
is
["self"]
.
Note:
The
default
allowlist
of
["self"]
allows
Sensor
interface
implementation
usage
in
same-origin
nested
frames
but
prevents
third-party
content
from
sensor
readings
access.
The sensor feature names set must contain feature names of every associated feature .
A
Low-level
sensor
may
use
its
interface
name
as
a
feature
name
,
for
instance,
"gyroscope"
or
"accelerometer".
Unless
the
extension
specification
tells
otherwise,
the
sensor
feature
names
matches
the
same
type
-associated
sensor
permission
names
.
<iframe src="https://third-party.com" allow="accelerometer"/></iframe>
Feature-Policy: {"accelerometer": []}
Fusion sensors must use sensor feature names of the sensors that are used as a source of fusion.
<iframe src="https://third-party.com" allow="accelerometer; magnetometer; gyroscope"/>
9.9. Example WebIDL
Here’s example WebIDL for a possible extension of this specification for proximity sensors .
[Constructor(optional ProximitySensorOptions proximitySensorOptions), SecureContext, Exposed=Window] interface ProximitySensor : Sensor { readonly attribute double? distance; }; dictionary ProximitySensorOptions : SensorOptions { double min; double max; ProximitySensorPosition position; ProximitySensorDirection direction; }; enum ProximitySensorPosition { "top-left", "top", "top-right", "middle-left", "middle", "middle-right", "bottom-left", "bottom", "bottom-right" }; enum ProximitySensorDirection { "front", "rear", "left", "right", "top", "bottom" };
10. Acknowledgements
First and foremost, I would like to thank Anssi Kostiainen for his continuous and dedicated support and input throughout the development of this specification, as well as Mikhail Pozdnyakov, Alexander Shalamov, Rijubrata Bhaumik, and Kenneth Rohde Christiansen for their invaluable implementation feedback, suggestions, and research that have helped inform the specification work.
Special thanks to Rick Waldron for driving the discussion around a generic sensor API design for the Web, sketching the original API on which this is based, providing implementation feedback from his work on Johnny-Five, and continuous input during the development of this specification.
Special thanks to Boris Smus, Tim Volodine, and Rich Tibbett for their initial work on exposing sensors to the web with consistency.
Thanks to Anne van Kesteren for his tireless help both in person and through IRC.
Thanks to Domenic Denicola and Jake Archibald for their help.
Thanks also to Frederick Hirsch and Dominique Hazaël-Massieux (via the HTML5Apps project) for both their administrative help and technical input.
Thanks to Tab Atkins for making Bikeshed and taking the time to explain its subtleties.
Thanks to Lukasz Olejnik and Maryam Mehrnezhad for their contributions around privacy and security.
The following people have greatly contributed to this specification through extensive discussions on GitHub: Anssi Kostiainen, Boris Smus, chaals, Claes Nilsson, Dave Raggett, David Mark Clements, Domenic Denicola, Dominique Hazaël-Massieux (via the HTML5Apps project), Francesco Iovine, Frederick Hirsch, gmandyam, Jafar Husain, Johannes Hund, Kris Kowal, Lukasz Olejnik, Marcos Caceres, Marijn Kruisselbrink, Mark Foltz, Mats Wichmann, Matthew Podwysocki, Olli Pettay, pablochacin, Remy Sharp, Rich Tibbett, Rick Waldron, Rijubrata Bhaumik, robman, Sean T. McBeth, Tab Atkins Jr., Virginie Galindo, zenparsing, and Zoltan Kis.
We’d also like to thank Anssi Kostiainen, Dominique Hazaël-Massieux, Erik Wilde, and Michael[tm] Smith for their editorial input.
Conformance
Document conventions
Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.
All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples
in
this
specification
are
introduced
with
the
words
"for
example"
or
are
set
apart
from
the
normative
text
with
class="example"
,
like
this:
Because
this
document
doesn’t
itself
define
APIs
for
specific
sensor
types
—
Informative
notes
begin
with
the
word
"Note"
and
are
set
apart
from
the
normative
text
with
class="note"
,
like
this:
Note, this is an informative note.
Conformant Algorithms
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent . In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.
Conformance Classes
A conformant user agent must implement all the requirements listed in this specification that are applicable to user agents.