index.bs

<pre class="metadata">
Title: Proximity Sensor
Level: none
Status: ED
ED: https://w3c.github.io/proximity/
Shortname: proximity
TR: https://www.w3.org/TR/proximity/
Editor: Anssi Kostiainen 41974, Intel Corporation, https://intel.com/
Editor: Rijubrata Bhaumik 80407, Intel Corporation, https://intel.com/
Former Editor: Dzung D Tran, Intel Corporation, https://intel.com/
Group: dap
Abstract:
  This specification defines a concrete sensor interface to monitor
  the presence of nearby physical objects without physical contact.
Status Text:
  The Devices and Sensors Working Group will perform a round of self-review and
  revisions on the security and privacy aspects of the API before
  requesting horizontal review. Existing <a
  href="https://www.w3.org/PM/horizontal/review.html?shortname=proximity-sensor">security
  and privacy issues</a> are available.
Version History: https://github.com/w3c/proximity/commits/main/index.bs
!Bug Reports: <a href="https://www.github.com/w3c/proximity/issues/new">via the w3c/proximity repository on GitHub</a>
Indent: 2
Repository: w3c/proximity
Markup Shorthands: markdown on
Inline Github Issues: title
!Issue Tracking: <a href="https://github.com/w3c/proximity/issues">Issues</a>
!Test Suite: <a href="https://github.com/web-platform-tests/wpt/tree/master/proximity">web-platform-tests on GitHub</a>
Boilerplate: omit issues-index, omit conformance
Default Biblio Status: current
</pre>
<pre class="anchors">
urlPrefix: https://w3c.github.io/sensors; spec: GENERIC-SENSOR
  type: dfn
    text: high-level
    text: sensor
    text: latest reading
    text: default sensor
    text: construct a sensor object; url: construct-sensor-object
    text: initialize a sensor object; url: initialize-a-sensor-object
    text: sensor type
    text: check sensor policy-controlled features; url: check-sensor-policy-controlled-features
    text: fingerprinting; url: device-fingerprinting
    text: user identifying; url: user-identifying
    text: mitigation strategies; url: mitigation-strategies
urlPrefix: https://w3c.github.io/webdriver/; spec: WEBDRIVER2
  type: dfn
    text: get a property; url: dfn-getting-properties
</pre>
<pre class="link-defaults">
spec:infra;
  type:dfn;
    text:list
spec:generic-sensor-1;
  type:enum-value;
    text:"activated"
spec: webidl;
  type:dfn;
    text:identifier
</pre>

Introduction {#intro}
============

The Proximity Sensor extends the Generic Sensor API [[GENERIC-SENSOR]]
to provide information about proximity level, as detected by the device's primary
proximity sensor. The proximity level is reported as the distance (in centimeter)
from the sensor to the closest visible surface. [[#limitations-proximity-sensors]]
describes more about the potential limitations, why the precise distance value
reported by different devices can be different, due to differences in detection
method, sensor construction, etc.  Moreover some proximity sensors might be only
able to provide just a boolean to indicate if there is a physical object which is near,
more like presence detection, than an absolute value for the distance.


Examples {#examples}
========

<div class="example">
    <pre highlight="js">
    let sensor = new ProximitySensor();
    sensor.start();

    sensor.onreading = () => console.log(sensor.distance);

    sensor.onerror = event => console.log(event.error.name, event.error.message);

    </pre>
</div>

Security and Privacy Considerations {#security-and-privacy}
===================================

Proximity sensor provides information about closeness of the sensor to nearby objects,
thus, may expose privacy sensitive information for [=user identifying=] and/or
[=fingerprinting=] attacks.

To mitigate these, user agents should use one or both of the following [=mitigation strategies=]:
  - [=reduce accuracy=] of a [=sensor reading=]
  - [=limit maximum sampling frequency=]

These mitigation strategies complement the [=mitigation strategies|generic mitigations=]
defined in the Generic Sensor API [[!GENERIC-SENSOR]].

Permissions Policy integration {#permissions-policy-integration}
==============================

This specification defines a [=policy-controlled feature=] identified by the string "<code><dfn data-lt="proximity-sensor-feature" export>proximity-sensor</dfn></code>". Its [=default allowlist=] is "`self`".

Model {#model}
=====

The <dfn id="proximity-sensor-sensor-type">Proximity Sensor</dfn> <a>sensor type</a> has the following associated data:

 : [=Extension sensor interface=]
 :: {{ProximitySensor}}
 : [=Sensor permission names=]
 :: "<code><dfn permission export>proximity</dfn></code>"
 : [=Sensor feature names=]
 :: "[=proximity-sensor-feature|proximity-sensor=]"
 : [=powerful feature/Permission revocation algorithm=]
 :: Invoke the [=generic sensor permission revocation algorithm=] with "<code><a permission>proximity</a></code>".
 : [=Default sensor=]
 :: The device's main proximity detector.
 : [=Virtual sensor type=]
 :: "<code><dfn data-lt="proximity virtual sensor type">proximity</dfn></code>"

A [=latest reading=] for a {{Sensor}} of <a>Proximity Sensor</a> <a>sensor type</a> includes three [=map/entries=]
whose [=map/keys=] are "distance", "max", "near" and whose [=map/values=] contain [=distance=],
[=max=] and [=near=] values.

The <dfn>distance</dfn> is a value that represents the distance between a device and
the closest visible surface of the physical object within the <dfn>sensing range</dfn>.
Its unit is the centimeter (cm).

The <dfn>max</dfn> is a value that represents the maximum <a>sensing range</a> of the
main proximity detector, in centimeters.

The <dfn>near</dfn> is a value that represent the presence of a visible surface
in the vicinity of the main proximity detector.

API {#api}
===

The ProximitySensor Interface {#proximity-sensor-interface}
--------------------------------

<pre class="idl">
  [SecureContext, Exposed=Window]
  interface ProximitySensor : Sensor {
    constructor(optional SensorOptions sensorOptions = {});
    readonly attribute double? distance;
    readonly attribute double? max;
    readonly attribute boolean? near;
  };
</pre>

To construct a {{ProximitySensor}} object the user agent must invoke the
[=construct a proximity sensor object=] abstract operation.


### The distance attribute ### {#proximity-sensor-distance}

The {{ProximitySensor/distance!!attribute}} attribute of the {{ProximitySensor}}
interface returns the result of invoking [=get value from latest reading=] with
<emu-val>this</emu-val> and "distance" as arguments.

If the physical object is outside the <a>sensing range</a>, the attribute must return null.

### The max attribute ### {#proximity-sensor-max}

The {{ProximitySensor/max!!attribute}} attribute of the {{ProximitySensor}}
interface returns the result of invoking [=get value from latest reading=] with
<emu-val>this</emu-val> and "max" as arguments.

### The near attribute ### {#proximity-sensor-near}

The {{ProximitySensor/near!!attribute}} attribute of the {{ProximitySensor}}
interface returns the result of invoking [=get value from latest reading=] with
<emu-val>this</emu-val> and "near" as arguments.

If the physical object is outside the <a>sensing range</a>, the attribute must return null.

Note: If the implementation is unable to provide the [=near=] value, it could infer the [=near=]
value from the value of [=distance=]. For example, if [=distance=] is not equal to [=max=], it
could imply there is a physical object in the <a>sensing range</a>.


Abstract Operations {#abstract-operations}
===================

<h3 dfn export>Construct a proximity sensor object</h3>

<div algorithm="construct a proximity sensor object">

    : input
    :: |options|, a {{SensorOptions}} object.
    : output
    :: A {{ProximitySensor}} object.

    1.  Let |allowed| be the result of invoking [=check sensor policy-controlled features=]
        with {{ProximitySensor}}.
    1.  If |allowed| is false, then:
        1.  [=Throw=] a {{SecurityError}} {{DOMException}}.
    1.  Let |proximity_sensor| be the new {{ProximitySensor}} object.
    1.  Invoke [=initialize a sensor object=] with |proximity_sensor| and |options|.
    1.  Return |proximity_sensor|.
</div>

Automation {#automation}
==========

This section extends [[GENERIC-SENSOR#automation]] by providing [=Proximity Sensor=]-specific virtual sensor metadata.

The [=per-type virtual sensor metadata=] [=map=] must have the following [=map/entry=]:
: [=map/key=]
:: "<code>[=proximity virtual sensor type|proximity=]</code>"
: [=map/value=]
:: A [=virtual sensor metadata=] whose [=virtual sensor metadata/reading parsing algorithm=] is the [=proximity reading parsing algorithm=].

<h3 dfn>Proximity reading parsing algorithm</h3>
<div algorithm="proximity reading parsing algorithm">
    : input
    :: |parameters|, a JSON {{Object}}
    : output
    :: A [=sensor reading=] or **undefined**

    1.  Let |reading| be a new [=sensor reading=].
    1.  Let |keys| be the [=/list=] « "`distance`", "`max`" ».
    1.  [=list/For each=] |key| of |keys|
        1.  Let |value| be the result of invoking [=parse single-value number reading=] with |parameters| and |key|.
            1.  If |value| is **undefined**.
                1.  Return **undefined**.
        1.  [=map/Set=] |reading|[|key|] to |value|[|key|].
    1.  Let |near| be the result of invoking [=get a property=] from |parameters| with "`near`".
        1. If |near|'s type is not Boolean
            1.  Return **undefined**.
        1.  [=map/Set=] |reading|["`near`"] to |near|.
    1.  Return |reading|.
</div>

Limitations of Proximity Sensors {#limitations-proximity-sensors}
========================

Since most proximity sensors detect electromagnetic radiation (e.g., an infrared light
or a magnetic field), certain material properties can interfere with the sensor's
ability to sense the presence of a physical object. Things that can interfere with
a sensor include, but are not limited to, the material's translucency, reflectiveness,
color, temperature, chemical composition, and even the angle at which the physical object
is reflecting the radiation back at the sensor. As such, proximity sensors
should not be relied on as a means to measure distance. The only thing that can
be deduced from a proximity sensor is that a physical object is somewhere in the
distance between the minimum sensing distance and the maximum sensing distance
with some degree of certainty.


Acknowledgements {#acknowledgements}
================

Tobie Langel for the work on Generic Sensor API and inputs on this specification.
Doug Turner for the initial prototype and
Marcos Caceres for the test suite.

Conformance {#conformance}
===========

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]]

A <dfn>conformant user agent</dfn> must implement all the requirements
listed in this specification that are applicable to user agents.

The IDL fragments in this specification must be interpreted as required for
conforming IDL fragments, as described in the Web IDL specification. [[!WEBIDL]]