Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines a means to receive events that correspond to a proximity sensor detecting the presence of a physical object.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
The functionality described in this specification was initially specified as part of the Sensor API but has been extracted in order to be more straightforward to implement, and in order to produce a specification that could be implemented on its own merits without interference with other features.
Changes since Last Call include addition of a new security considerations section, clarifications related to attribute values and initialization, updated references and the addition of a WebIDL reference. These changes include updates to address Last Call comments that were received (disposition of comments). A diff showing changes since the Last Call publication is available (diff).
The CR exit criterion is two interoperable deployed implementations of each feature, with no features marked as 'at-risk'. The group will create an Implementation Report.
This document was published by the Device APIs Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 21 November 2013. All comments are welcome.
Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
The DeviceProximityEvent
interface provides web developers
information about the distance between the hosting device and a
nearby object.
The UserProximityEvent
interface provides web developers
a user-agent- and platform-specific approximation that the hosting
device has sensed a nearby object.
This is achieved by interrogating a proximity sensor of a device, which is a sensor that can detect the presence of a physical object without physical contact. Not all devices contain a proximity sensor, and when there is no proximity sensor, this API is still exposed to the scripting environment but it does nothing.
Because 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 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 an object is somewhere in the distance between the minimum sensing distance and the maximum sensing distance with some degree of certainty.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.
The
EventHandler
interface represents a callback used for event
handlers as defined in [HTML5].
The concepts queue a task, fires a simple event, and top-level browsing context are defined in [HTML5].
Event constructor behavior is defined in constructing events chapter in [DOM4].
The terms event handlers and event handler event types are defined in [HTML5].
The concepts create an event and fire an event are defined in [DOM4].
The current device proximity is a value that represents the proximity of the hosting device to a physical object (i.e., some value between the maximum sensing distance and the minimum sensing distance), in centimeters.
The minimum sensing distance at which the sensor can detect a physical object, in centimeters.
The maximum sensing distance at which the sensor can detect a physical object, in centimeters.
The current user proximity state, a boolean state, is a user-agent- and platform-specific approximation of the closeness of a physical object with the hosting device.
This section is non-normative.
Privacy risks can arise when this specification is used 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 implementation limits of minimum and maximum sensing distance as well as event firing rates offer the possibility of fingerprinting to identify users. Browser implementations may reduce the risk by limiting the granularity and event rates available to web application developers.
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.
Browser implementations should consider providing the user an indication of when the sensor is used and allowing the user to disable sensing.
Web application developers that use this specification should perform a privacy assessment of their application taking all aspects of their application into consideration.
The events defined in this specification are only fired in the top-level browsing context to avoid the privacy risk of sharing the information defined in this specification with contexts unfamiliar to the user. For example, a mobile device will only fire these events on the active tab, and not on the background tabs or within iframes.
The HTML5 specification [HTML5] defines a Window
interface,
which this specification extends:
partial interface Window {
attribute EventHandler ondeviceproximity;
};
The ondeviceproximity
event handler and its corresponding
event handler event type deviceproximity
MUST be supported
as an IDL attribute by all objects implementing the Window
interface.
DeviceProximityEvent
Interfacedictionary DeviceProximityEventInit : EventInit {
double value;
double min;
double max;
};
[Constructor (DOMString type, optional DeviceProximityEventInit eventInitDict)]
interface DeviceProximityEvent : Event {
readonly attribute unrestricted double value;
readonly attribute unrestricted double min;
readonly attribute unrestricted double max;
};
The value
attribute of the
DeviceProximityEvent
interface MUST return the value it was initialized to. When the
object is created, this attribute MUST be initialized to positive
Infinity. It represents the current device proximity.
The min
attribute of the
DeviceProximityEvent
interface MUST return the value it was initialized to. When the
object is created, this attribute MUST be initialized to negative
Infinity. It represents the minimum sensing distance.
The max
attribute of the
DeviceProximityEvent
interface MUST return the value it was initialized to. When the
object is created, this attribute MUST be initialized to positive
Infinity. It represents the maximum sensing distance.
When a user agent is required to fire a device proximity event, the user agent MUST run the following steps:
DeviceProximityEvent
interface, with the name deviceproximity
, which
bubbles, is not cancelable, and has no default action, that also
meets the following conditions:
value
attribute to positive Infinity, otherwise initialize the
attribute to the current device proximity.
min
attribute to negative Infinity, otherwise initialize the
attribute to the minimum sensing distance.
max
attribute to positive Infinity, otherwise initialize the
attribute to the maximum sensing distance.
When the current device proximity changes, the user
agent MUST queue a task to fire a device proximity event
at the top-level browsing context's Window
object.
UserProximityEvent
interface if they are only interested in finding out if the user is
near or far.
The following are the event handlers (and their corresponding
event handler event types) that MUST be supported as
attributes by the Window
object:
event handler | event handler event type |
---|---|
ondeviceproximity |
deviceproximity |
The HTML5 specification [HTML5] defines a Window
interface,
which this specification extends:
partial interface Window {
attribute EventHandler onuserproximity;
};
The onuserproximity
event handler and its corresponding
event handler event type userproximity
MUST be supported
as an IDL attribute by all objects implementing the Window
interface.
UserProximityEvent
Interfacedictionary UserProximityEventInit : EventInit {
boolean near;
};
[Constructor (DOMString type, optional UserProximityEventInit eventInitDict)]
interface UserProximityEvent : Event {
readonly attribute boolean near;
};
The near
attribute of the
UserProximityEvent
interface MUST return the value it was initialized to. When the
object is created, this attribute MUST be initialized to false.
It represents the current user proximity state.
When a user agent is required to fire a user proximity event, the user agent MUST run the following steps:
UserProximityEvent
interface, with the name userproximity
, which bubbles,
is not cancelable, and has no default action, that also meets the
following conditions:
near
attribute
to false, otherwise initialize the attribute to the current
user proximity state.
When the current user proximity state changes, the user
agent MUST queue a task to fire a user proximity event
at the top-level browsing context's Window
object.
The following are the event handlers (and their corresponding
event handler event types) that MUST be supported as
attributes by the Window
object:
event handler | event handler event type |
---|---|
onuserproximity |
userproximity |
Doug Turner for the initial prototype. All Device APIs working group participants who have sent helpful feedback. Marcos Caceres for his excellent work on the test suite.