Something that’s very nice with bringing the web to the mobile platform with Firefox OS and WebAPIs is the ability to connect more into the physical world. One part there is the Proximity API, which is also a W3C Working Draft – Proximity Events.

What it is

The API is about detecting how close the device is to any other physical object, by accessing the proximity sensor. There are two ways of working with proximity

• Device proximity
• User proximity

From the spec:

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.

Using it

Working with proximity is as easy as adding a couple of event handlers, depending on what you want to do. The deviceproximity event works with the metric system, and you will get back the distance in centimeters (these examples take for granted that you have an existing proximityDisplay element to present the values in). You are also able to check the minimum and maximum distance the sensor in your device supports.

window.ondeviceproximity = function (event) {
    // Check proximity, in centimeters
    var prox = "Proximity: " + event.value + " cm
";
        prox += "Min value supported: " + event.min + " cm
";
        prox += "Max value supported: " + event.max + " cm";
    proximityDisplay.innerHTML = prox;
};

It should be noted that the values sensors currently can return a quite small value, ranging from 0 up to 5 or 10 centimeters. In general, I believe the use case has been to detect if the user is holding the device up to the ear or not, but my personal opinion is that this could provide to be even more exciting if it supported, say, up to a meter!

With userproximity, the value you get back is a near property on the event object, which is a boolean returning whether the user is near to the sensor or not.

window.onuserproximity = function (event) {
    // Check user proximity
    var userProx = "User proximity - near: " + event.near + "
";
    userProximityDisplay.innerHTML = userProx;
};

I’ve also added device and proximity code and testing to the Firefox OS Boilerplate App so feel free to get the latest code there and play around with it.

Web browser support

The Proximity API is currently supported in:

• Firefox OS
• Firefox on Android

Conclusion

Working with proximity is yet another example of crossing the gap between software and real physical context, and showing just how powerful the web can be. We hope to see you creating many interesting things based on it!