Abstract

This specification defines a means to receive events that correspond to a light sensor detecting the presence of a light.

Status of This Document

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, clarification of lux level light values, clarifications to the text and processing description and 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.

Table of Contents

1. Introduction

This section is non-normative.

This specification defines events that provide information about the ambient light level, as measured by a device's light sensor. A LightLevelEvent describes the light level as one of three simple categories - "dim", "normal", and "bright" - while a DeviceLightEvent provides a more granular answer by describing the light level in terms of lux units.

2. Conformance

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.

3. Terminology

The EventHandler interface represents a callback function 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].

The terms event handlers and event handler event types are defined in [HTML5].

Event constructor behavior is defined in constructing events chapter in [DOM4].

The concepts create an event and fire an event are defined in [DOM4].

The current light level is a value that represents the ambient light levels around the hosting device in lux units.

The current light level state represents the ambient light level around the hosting device as a human-readable string.

4. Security and privacy considerations

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 light level values as well as event firing rates offer the possibility of fingerprinting to identify users. Browser implementations may reduce the risk by only using the less precise LightLevelState of 'dim', 'normal', and 'bright' and limiting 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.

5. Device Light

The DeviceLightEvent interface provides information about the ambient light levels, as detected by the device's light detector, in terms of lux units.

The HTML5 specification [HTML5] defines a Window interface, which this specification extends:

partial interface Window {
                attribute EventHandler ondevicelight;
};

The ondevicelight event handler and its corresponding event handler event type devicelight MUST be supported as an IDL attribute by all objects implementing the Window interface.

5.1 DeviceLightEvent Interface

dictionary DeviceLightEventInit : EventInit {
    unrestricted double value;
};

[Constructor (DOMString type, optional DeviceLightEventInit eventInitDict)] interface DeviceLightEvent : Event { readonly attribute unrestricted double value; };

The value attribute of the DeviceLightEvent 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 light level.

Note
The precise lux value reported by different devices in the same light can be different, due to differences in detection method, sensor construction etc.

When a user agent is required to fire a device light event, the user agent MUST run the following steps:

  1. Create an event that uses the DeviceLightEvent interface, with the name devicelight, which bubbles, is not cancelable, and has no default action, that also meets the following conditions:
    1. If the implementation is unable to report the current light level, initialize the value attribute to positive Infinity, otherwise initialize the attribute to the current light level.

When the current light level changes, the user agent MUST queue a task to fire a device light event at the top-level browsing context's Window object.

Note
The definition of granularity i.e. how often the event is fired is left to the implementation. Implementations can fire the event if they have reason to believe that the page does not have sufficiently fresh data.

5.1.1 Event handlers

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
ondevicelight devicelight

6. Light Level

The LightLevelEvent interface provides information about the ambient light levels, as detected by the device's light detector, in terms of three general range: "dim", "normal", or "bright".

The HTML5 specification [HTML5] defines a Window interface, which this specification extends:

partial interface Window {
                attribute EventHandler onlightlevel;
};

The onlightlevel event handler and its corresponding event handler event type lightlevel MUST be supported as an IDL attribute by all objects implementing the Window interface.

6.1 LightLevelEvent Interface

enum LightLevelState {
    "",
    "dim",
    "normal",
    "bright"
};

dictionary LightLevelEventInit : EventInit { LightLevelState value; };

[Constructor (DOMString type, optional LightLevelEventInit eventInitDict)] interface LightLevelEvent : Event { readonly attribute LightLevelState value; };

The value attribute of the LightLevelEvent interface MUST return the value it was initialized to. When the object is created, this attribute MUST be initialized to an empty string. It represents the current light level state.

When a user agent is required to fire a light level event, the user agent MUST run the following steps:

  1. Create an event that uses the LightLevelEvent interface, with the name lightlevel, which bubbles, is not cancelable, and has no default action, that also meets the following conditions:
    1. If the implementation is unable to report the current light level state, initialize the value attribute to an empty string, otherwise initialize the attribute to the current light level state, which MUST be one of the following values:
      • dim
      • normal
      • bright
      Note
      The lux ranges that map to the current light level states are left to the implementation, as devices with different sensitivities could map them slightly differently. However, it is recommended that "dim" correspond to ambient light below 50 lux (dark enough that the light produced by a white background is eye-straining or distracting), "normal" correspond to light between 50 lux and 10000 lux (office building hallway, very dark overcast day, office lighting, sunrise or sunset on a clear day, overcast day, or similar), and "bright" correspond to light above 10000 lux (direct sunlight, or similarly bright conditions that make it hard to see things that aren't high-contrast).

When the current light level state changes, the user agent MUST queue a task to fire a user proximity event at the top-level browsing context's Window object.

Note
The definition of granularity i.e. how often the event is fired is left to the implementation. Implementations can fire the event if they have reason to believe that the page does not have sufficiently fresh data.

6.1.1 Event handlers

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
onlightlevel lightlevel

A. Acknowledgements

Doug Turner for the initial prototype and Marcos Caceres for the test suite.

B. References

B.1 Normative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Lachlan Hunt; Ms2ger. DOM4. 6 December 2012. W3C Working Draft. URL: http://www.w3.org/TR/dom/
[HTML5]
Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 6 August 2013. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/