paint-brush
Proximity Events Specification: How To Receive Events From Device Proximity Sensorsby@mozilla
210 reads

Proximity Events Specification: How To Receive Events From Device Proximity Sensors

by Mozilla ContributorsJune 10th, 2020
Read on Terminal Reader
Read this story w/o Javascript
tldt arrow

Too Long; Didn't Read

Proximity events are a handy way to know when a user is close to a device. These events make it possible to react to such a change, for example by shutting down the screen of a smartphone when the user is having a phone call with the device close to their ear. The API requires the device to have a proximity sensor, which are mostly available only on mobile devices. This is an experimental technology. Check the Browser compatibility table carefully before using this in production before using it in production.

Company Mentioned

Mention Thumbnail
featured image - Proximity Events Specification: How To Receive Events From Device Proximity Sensors
Mozilla Contributors HackerNoon profile picture
This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The proximity events are a handy way to know when a user is close to a device. These events make it possible to react to such a change, for example by shutting down the screen of a smartphone when the user is having a phone call with the device close to their ear.

Note: Obviously, the API requires the device to have a proximity sensor, which are mostly available only on mobile devices. Devices without such a sensor may support those events but will never fire them.

Proximity Events

When the device proximity sensor detects a change between the device and an object, it notifies the browser of that change. When the browser
gets such a notification, it fires a

DeviceProximityEvent
for any change, and a
UserProximityEvent
event in the case of a more rough change.

This event can be captured at the

window
object level by using the
addEventListener
method (using the
deviceproximity
or
userproximity
event name) or by attaching an event handler to the
window.ondeviceproximity
or
window.onuserproximity
properties.

Once captured, the event object gives access to different kinds of information:

  • The
    DeviceProximityEvent
    event provides an exact match for the distance between the device and the object through its
    value
    property. It also provides the closest and farthest distance the device is able to detect something through its
    min
    and
    max
    properties.
  • The
    UserProximityEvent
    event provides a rough approximation of the distance, expressed through a boolean. The
    UserProximityEvent.near
    property is
    true
    if the object is close or
    false
    if the object is far.

Example

window.addEventListener('userproximity', function(event) {
  if (event.near) {
    // let's power off the screen
    navigator.mozPower.screenEnabled = false;
  } else {
    // Otherwise, let's power on the screen
    navigator.mozPower.screenEnabled = true;
  }
});

Specifications

Browser compatibility

DeviceProximityEvent

UserProximityEvent

See also

    Credits