Sensor APIs

Obwohl die Generic Sensor API-Spezifikation eine Sensor-Schnittstelle definiert, werden Sie als Webentwickler diese nie direkt verwenden. Stattdessen verwenden Sie eine ihrer Unterklassen, um bestimmte Arten von Sensordaten abzurufen. Zum Beispiel gibt die Accelerometer-Schnittstelle die Beschleunigung des Geräts entlang aller drei Achsen zum Zeitpunkt der Abfrage zurück.

Sensoren stimmen möglicherweise nicht genau mit einem physischen Gerätesensor überein. Zum Beispiel entspricht die Gyroscope-Schnittstelle genau einer physischen Geräte-Schnittstelle. Alternativ bietet die AbsoluteOrientationSensor-Schnittstelle Informationen, die algorithmisch aus zwei oder mehr Gerätesensoren aggregiert werden. Diese Sensortypen werden jeweils als niedrigstufig und höherstufig bezeichnet. Der letztere Sensortyp wird auch als Fusion-Sensor (alternativ virtuelle oder synthetische Sensoren) bezeichnet.

Sensor-Schnittstellen sind nur Stellvertreter für die zugrunde liegenden Gerätesensoren. Folglich ist die Funktionsüberprüfung bei Sensoren komplizierter als bei anderen APIs. Die Anwesenheit einer Sensor-API sagt nicht aus, ob diese API mit einem echten Hardwaresensor verbunden ist, ob dieser Sensor funktioniert, ob er immer noch verbunden ist oder ob der Benutzer Zugriff darauf gewährt hat. All diese Informationen konsistent verfügbar zu machen, ist kostenintensiv in Bezug auf Leistung und Batterielebensdauer.

Daher muss die Funktionsüberprüfung für Sensor-APIs sowohl die Erkennung der APIs selbst als auch defensive Programmierstrategien (siehe unten) beinhalten.

Die folgenden Beispiele zeigen drei Methoden zur Erkennung von Sensor-APIs. Zusätzlich können Sie die Objektinstanziierung in einen try...catch-Block einfügen. Beachten Sie, dass die Erkennung über die Navigator-Schnittstelle nicht zu den verfügbaren Optionen gehört.

if (typeof Gyroscope === "function") {
  // run in circles…
}

if ("ProximitySensor" in window) {
  // watch out!
}

if (window.AmbientLightSensor) {
  // go dark…
}

Wie in der Funktionsüberprüfung beschrieben, reicht es nicht aus, nur für eine bestimmte Sensor-API zu prüfen. Das Vorhandensein eines tatsächlichen Sensors muss ebenfalls bestätigt werden. Hier wird defensive Programmierung benötigt. Defensive Programmierung erfordert drei Strategien.

• Überprüfen auf auftretende Fehler bei der Instanziierung eines Sensorobjekts.
• Überwachen auf Fehler, die während der Nutzung auftreten.
• Fehler so behandeln, dass die Benutzererfahrung verbessert und nicht verschlechtert wird.

Das folgende Codebeispiel veranschaulicht diese Prinzipien. Der try...catch-Block fängt während der Sensor-Instanzierung auftretende Fehler ab. Er lauscht auf error-Ereignisse, um Fehler bei der Nutzung abzufangen. Der Benutzer wird nur informiert, wenn Berechtigungen angefordert werden müssen und wenn der Sensortyp vom Gerät nicht unterstützt wird.

Zusätzlich kann diese Funktion durch eine auf Ihrem Server festgelegte Berechtigungsrichtlinie blockiert werden.

let accelerometer = null;
try {
  accelerometer = new Accelerometer({ referenceFrame: "device" });
  accelerometer.addEventListener("error", (event) => {
    // Handle runtime errors.
    if (event.error.name === "NotAllowedError") {
      // Branch to code for requesting permission.
    } else if (event.error.name === "NotReadableError") {
      console.log("Cannot connect to the sensor.");
    }
  });
  accelerometer.addEventListener("reading", () => reloadOnShake(accelerometer));
  accelerometer.start();
} catch (error) {
  // Handle construction errors.
  if (error.name === "SecurityError") {
    // See the note above about permissions policy.
    console.log("Sensor construction was blocked by a permissions policy.");
  } else if (error.name === "ReferenceError") {
    console.log("Sensor is not supported by the User Agent.");
  } else {
    throw error;
  }
}

SensoR-abfragen dürfen erst durchgeführt werden, wenn der Benutzer einer bestimmten Art von Sensor durch die Berechtigungs-API die Genehmigung erteilt hat und/oder der Zugriff nicht durch den Server über die Permissions-Policy-Richtlinie blockiert wird.

Das folgende Beispiel zeigt, wie Benutzerberechtigungen angefordert werden, bevor versucht wird, den Sensor zu verwenden.

navigator.permissions.query({ name: "accelerometer" }).then((result) => {
  if (result.state === "denied") {
    console.log("Permission to use accelerometer sensor is denied.");
    return;
  }
  // Use the sensor.
});

Ein alternativer Ansatz besteht darin, zu versuchen, den Sensor zu verwenden und auf den SecurityError zu lauschen.

const sensor = new AbsoluteOrientationSensor();
sensor.start();
sensor.addEventListener("error", (error) => {
  if (event.error.name === "SecurityError")
    console.log("No permissions to use AbsoluteOrientationSensor.");
});

Die folgende Tabelle beschreibt für jeden Sensortyp, den erforderlichen Namen für die Berechtigungs-API, das allow-Attribut des <iframe>-Elements und die Permissions-Policy-Direktive.

Sensor-Messwerte werden durch den reading-Ereignis-Callback empfangen, das von allen Sensortypen geerbt wird. Die Abfragerate wird von Ihnen entschieden und mit einer Option, die dem Konstruktor eines Sensors übergeben wird, erreicht. Die Option ist eine Zahl, die die Anzahl der Abfragen pro Sekunde angibt. Eine Ganz- oder Dezimalzahl kann verwendet werden, letztere für Frequenzen unter einer Sekunde. Die tatsächliche Abfragerate hängt von der Gerätehardware ab und kann daher geringer ausfallen als angefordert.

Das folgende Beispiel veranschaulicht dies anhand des Magnetometer-Sensors.

let magSensor = new Magnetometer({ frequency: 60 });

magSensor.addEventListener("reading", (e) => {
  console.log(`Magnetic field along the X-axis ${magSensor.x}`);
  console.log(`Magnetic field along the Y-axis ${magSensor.y}`);
  console.log(`Magnetic field along the Z-axis ${magSensor.z}`);
});
magSensor.addEventListener("error", (event) => {
  console.log(event.error.name, event.error.message);
});
magSensor.start();

AbsoluteOrientationSensor

Beschreibt die physische Ausrichtung des Geräts in Relation zum geographischen Koordinatensystem der Erde.

Accelerometer

Stellt die auf das Gerät entlang aller drei Achsen wirkende Beschleunigung bereit.

AmbientLightSensor

Gibt das aktuelle Umgebungslichtniveau oder die Beleuchtungsstärke um das gastgebende Gerät herum zurück.

GravitySensor

Stellt die auf das Gerät entlang aller drei Achsen wirkende Gravitation bereit.

Gyroscope

Liefert die Winkelgeschwindigkeit des Geräts entlang aller drei Achsen.

LinearAccelerationSensor

Stellt die auf das Gerät entlang aller drei Achsen wirkende Beschleunigung bereit, jedoch ohne den Einfluss der Gravitation.

Magnetometer

Liefert Informationen über das Magnetfeld, wie es vom primären Magnetsensor des Geräts erkannt wird.

OrientationSensor

Die Basisklasse für den AbsoluteOrientationSensor. Diese Schnittstelle kann nicht direkt verwendet werden, sondern bietet Eigenschaften und Methoden, die von abgeleiteten Schnittstellen abgerufen werden.

RelativeOrientationSensor

Beschreibt die physische Ausrichtung des Geräts ohne Bezug auf das geographische Koordinatensystem der Erde.

Sensor

Die Basisklasse für alle anderen Sensor-Schnittstellen. Diese Schnittstelle kann nicht direkt verwendet werden. Stattdessen bietet sie Eigenschaften, Ereignishandler und Methoden, die von abgeleiteten Schnittstellen abgerufen werden.

SensorErrorEvent

Liefert Informationen über Fehler, die von einer Sensor oder verwandten Schnittstelle aufgetreten sind.