API датчиков

API датчиков — это набор интерфейсов, разработанных по общему принципу, которые предоставляют доступ к датчикам устройства на веб-платформе согласованным образом.

Хотя спецификация API общих датчиков определяет интерфейс Sensor, как разработчик веб-приложений вы никогда его не будете использовать. Вместо этого вы будете использовать один из его подклассов для получения данных конкретных типов датчиков. Например, интерфейс Accelerometer возвращает ускорение устройства по всем трём осям в момент считывания.

Датчики могут или не могут точно соответствовать физическим датчикам устройства. Например, интерфейс Gyroscope точно соответствует физическому интерфейсу устройства. В качестве альтернативы, интерфейс AbsoluteOrientationSensor предоставляет информацию, алгоритмически агрегированную из двух или более датчиков устройства. Эти типы датчиков называются соответственно низкоуровневыми и высокоуровневыми. Последний тип датчика также называется датчиком слияния (или виртуальным или синтетическим датчиком).

Интерфейсы датчиков являются лишь прокси-серверами для базовых датчиков устройства. Следовательно, обнаружение возможностей для датчиков сложнее, чем для других API. Наличие API датчика не говорит вам, подключён ли этот API к реальному датчику аппаратного обеспечения, работает ли этот датчик, подключён ли он по-прежнему или даже предоставил ли пользователь к нему доступ. Предоставление всей этой информации в согласованном виде затратно с точки зрения производительности и заряда батареи.

Поэтому обнаружение возможностей для API датчиков должно включать как обнаружение самих API, так и стратегии защитного программирования (см. ниже).

В примерах ниже показаны три метода обнаружения API датчиков. Кроме того, вы можете поместить создание объекта внутри блока try...catch. Обратите внимание, что обнаружение через интерфейс Navigator не является одним из доступных вариантов.

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

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

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

Как указано в разделе Обнаружение возможностей, проверка наличия определённого API датчика недостаточна для обнаружения возможностей. Необходимо также подтвердить существование фактического датчика. Именно здесь требуется защитное программирование. Защитное программирование требует трёх стратегий.

• Проверка наличия сгенерированных ошибок при создании объекта датчика.
• Прослушивание ошибок, возникающих во время его использования.
• Обработка ошибок таким образом, чтобы опыт пользователя улучшался, а не ухудшался.

Пример кода ниже иллюстрирует эти принципы. Блок try...catch перехватывает ошибки, возникающие во время создания объекта датчика. Он прослушивает события error, чтобы перехватывать ошибки, возникающие во время использования. Единственное, что отображается пользователю, — это запрос разрешений и информация о том, что тип датчика не поддерживается устройством.

Кроме того, эта функция может быть заблокирована политикой разрешений, установленной на вашем сервере.

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;
  }
}

Считывание данных датчика невозможно без предоставления пользователем разрешения на определённый тип датчика с использованием API разрешений и/или если доступ заблокирован сервером Permissions-Policy.

Пример ниже демонстрирует запрос разрешения пользователя перед попыткой использования датчика.

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

Альтернативный подход заключается в попытке использовать датчик и прослушивании события SecurityError.

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

В следующей таблице описаны для каждого типа датчика требуемое имя для API разрешений, атрибут allow элемента <iframe> и директива Permissions-Policy.

Считывания датчиков принимаются через обработчик событий reading, который унаследован всеми типами датчиков. Частота считывания определяется вами с помощью параметра, передаваемого в конструктор датчика. Этот параметр — число, указывающее количество считываний в секунду. Можно использовать целое число или десятичную дробь, последнюю для частот менее одной секунды. Фактическая частота считывания зависит от оборудования устройства и, следовательно, может быть меньше запрашиваемой.

Следующий пример иллюстрирует это, используя датчик Magnetometer.

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

Описывает физическое направление устройства относительно эталонной системы координат Земли.

Accelerometer

Предоставляет ускорение, приложенное к устройству вдоль всех трёх осей.

AmbientLightSensor

Возвращает текущий уровень освещённости или освещённость окружающего света вокруг устройства.

GravitySensor

Предоставляет силу тяжести, приложенную к устройству вдоль всех трёх осей.

Gyroscope

Предоставляет угловую скорость устройства вдоль всех трёх осей.

LinearAccelerationSensor

Предоставляет ускорение, приложенное к устройству вдоль всех трёх осей, но без учёта влияния силы тяжести.

Magnetometer

Предоставляет информацию о магнитном поле, обнаруженном основным датчиком компаса устройства.

OrientationSensor

Базовый класс для AbsoluteOrientationSensor. Этот интерфейс нельзя использовать напрямую, вместо этого он предоставляет свойства и методы, к которым обращаются интерфейсы, наследующие от него.

RelativeOrientationSensor

Описывает физическое направление устройства без учёта эталонной системы координат Земли.

Sensor

Базовый класс для всех других интерфейсов датчиков. Этот интерфейс нельзя использовать напрямую. Вместо этого он предоставляет свойства, обработчики событий и методы, к которым обращаются интерфейсы, наследующие от него.

SensorErrorEvent

Предоставляет информацию об ошибках, сгенерированных интерфейсом Sensor или родственным ему интерфейсом.