Unlock Next-Level Web Experiences: A Guide to the Generic Sensor API

Want to create immersive web games, fitness trackers, or AR/VR experiences directly in the browser? The Generic Sensor API is the key! Discover how to tap into device sensors like accelerometers and gyroscopes for powerful, interactive web applications.

Alex Shalamov

Mikhail Pozdnyakov

Thomas Steiner

What is the Generic Sensor API and Why Should You Care?

The Generic Sensor API provides a standardized way for web applications to access device sensors. This unlocks a world of possibilities, bridging the gap between native apps and the web. No more limitations!

Standardized Sensor Access for the Web

The Generic Sensor API offers a consistent interface for interacting with various sensor types. This simplifies development and ensures cross-browser compatibility. Build once, deploy everywhere!

Key Advantages Over Legacy Sensor APIs

The Generic Sensor API is a modern solution with several key improvements:

• Extensible Framework: Easily add new sensor classes while maintaining a consistent interface.
• Configurable Sensors: Fine-tune sensor behavior, like setting the sampling frequency.
• Sensor Availability Detection: Determine if a specific sensor is present on the device.
• High-Precision Timestamps: Precisely synchronize sensor data with other application activities.
• Clearly Defined Data Models: Ensures interoperable solutions across different browser vendors.
• Not Bound to the DOM: Enables use within service workers or headless JavaScript environments.
• Enhanced Security & Privacy: Integrates with the Permissions API for better user control.
• Automatic Synchronization: Seamlessly aligns sensor data with screen coordinates.

Dive into Available Generic Sensor APIs

Explore the range of sensors you can start using today:

Motion Sensors:

• Accelerometer: Measures device acceleration.
• Gyroscope: Measures angular velocity.
• LinearAccelerationSensor: Measures acceleration excluding gravity.
• AbsoluteOrientationSensor: Measures device rotation relative to Earth.
• RelativeOrientationSensor: Measures device rotation relative to a stationary reference.
• GravitySensor: Returns the effect of acceleration due to gravity.

Environmental Sensors:

• AmbientLightSensor: (Behind a flag in Chromium)
• Magnetometer: (Behind a flag in Chromium)

Feature Detection: Ensuring Sensor Availability

Before using a sensor, verify that both the browser and the device support it. Here’s how:

if ('Accelerometer' in window) {
 // The `Accelerometer` interface is supported by the browser.
 // Does the device have an accelerometer, though?
}

To confirm actual sensor availability, attempt to connect to it:

let accelerometer = null;
try {
 accelerometer = new Accelerometer({ frequency: 10 });
 accelerometer.onerror = (event) => {
 // Handle runtime errors.
 if (event.error.name === 'NotAllowedError') {
 console.log('Permission to access sensor was denied.');
 } else if (event.error.name === 'NotReadableError') {
 console.log('Cannot connect to the sensor.');
 }
 };
 accelerometer.onreading = (e) => {
 console.log(e);
 };
 accelerometer.start();
} catch (error) {
 // Handle construction errors.
 if (error.name === 'SecurityError') {
 console.log('Sensor construction was blocked by the Permissions Policy.');
 } else if (error.name === 'ReferenceError') {
 console.log('Sensor is not supported by the User Agent.');
 } else {
 throw error;
 }
}

Polyfills: Supporting Older Browsers

Use a polyfill to provide Generic Sensor API functionality in browsers that don't natively support it. This ensures broader compatibility for your web applications.

// Import the objects you need.
import { Gyroscope, AbsoluteOrientationSensor } from './src/motion-sensors.js';

// And they're ready for use!
const gyroscope = new Gyroscope({ frequency: 15 });
const orientation = new AbsoluteOrientationSensor({ frequency: 60 });

Understanding Different Sensor Types

Let’s explore the specifics of each sensor and its potential applications:

Accelerometer and Linear Acceleration Sensor

• Accelerometer: Measures a device's acceleration on three axes (X, Y, Z), including gravity. Ideal for step counting, motion detection, and basic orientation.
• LinearAccelerationSensor: Measures acceleration excluding gravity. Perfect for detecting pure movement without gravitational influence.

Gravity Sensor

The GravitySensor returns the acceleration along the device's X, Y, and Z axes due to gravity. This provides accurate and computationally efficient gravity readings compared to manual calculations.

Gyroscope

The Gyroscope measures angular velocity around a device's X, Y, and Z axes. Essential for applications requiring precise rotational data.

Orientation Sensors

• AbsoluteOrientationSensor: Measures device rotation relative to the Earth's coordinate system.
• RelativeOrientationSensor: Measures device rotation relative to a stationary reference.

These sensors are crucial for immersive gaming, augmented reality (AR), and virtual reality (VR) experiences.

Code Example (three.js):

let torusGeometry = new THREE.TorusGeometry(7, 1.6, 4, 3, 6.3);
let material = new THREE.MeshBasicMaterial({ color: 0x0071c5 });
let torus = new THREE.Mesh(torusGeometry, material);
scene.add(torus);

// Update mesh rotation using quaternion.
const sensorAbs = new AbsoluteOrientationSensor();
sensorAbs.onreading = () => torus.quaternion.fromArray(sensorAbs.quaternion);
sensorAbs.start();

// Update mesh rotation using rotation matrix.
const sensorRel = new RelativeOrientationSensor();
let rotationMatrix = new Float32Array(16);
sensor_rel.onreading = () => {
 sensorRel.populateMatrix(rotationMatrix);
 torus.matrix.fromArray(rotationMatrix);
};
sensorRel.start();

Synchronizing with Screen Coordinates: A Simplified Approach

The Generic Sensor API allows you to specify whether sensor readings should be interpreted relative to the device or the screen. This eliminates manual remapping, streamlining development for screen-oriented applications.

Device coordinate system

Screen coordinate system

// Sensor readings are resolved in the Device coordinate system by default.
// Alternatively, could be RelativeOrientationSensor({referenceFrame: "device"}).
const sensorRelDevice = new RelativeOrientationSensor();

// Sensor readings are resolved in the Screen coordinate system. No manual remapping is required!
const sensorRelScreen = new RelativeOrientationSensor({ referenceFrame: 'screen' });

Hands-On Coding: Getting Started with the Generic Sensor API

Using the Generic Sensor API is straightforward. The Sensor interface provides start() and stop() methods for controlling sensor activity, along with event handlers for managing sensor events.

Development Environment