环境光传感器

1. 引言

Ambient Light Sensor 扩展了 Generic Sensor API [GENERIC-SENSOR]， 以按 lux 单位提供由设备主光检测器检测到的 环境光级别信息。

1.1. 范围

本文档规定了一个 API，其设计面向用例， 这些用例需要细粒度的照度数据、低延迟，并且可能 以高频率采样。

依赖少量照度值的常见用例，例如根据对比度级别或首选配色方案 对网页进行样式设置，而这些可能受设备测得的环境光级别影响， 最好由 prefers-contrast 和 prefers-color-scheme CSS 媒体特性 [MEDIAQUERIES-5] 以及随附的 matchMedia API [CSSOM-VIEW-1] 提供， 并且不属于本 API 的范围。

注：[MEDIAQUERIES-5] 规范曾经 包含一个 light-level 媒体特性，它与环境光读数更直接相关。后来它已从该规范中 移除， 转而采用更高层级的 prefers-color-scheme 和 prefers-contrast 媒体特性。

2. 示例

const sensor = new AmbientLightSensor();
sensor.onreading = () => console.log(sensor.illuminance);
sensor.onerror = event => console.log(event.error.name, event.error.message);
sensor.start();

navigator.permissions.query({ name: 'ambient-light-sensor' }).then(result => {
    if (result.state === 'denied') {
        console.log('Permission to use ambient light sensor is denied.');
        return;
    }

    const als = new AmbientLightSensor({frequency: 20});
    als.addEventListener('activate', () => console.log('Ready to measure EV.'));
    als.addEventListener('error', event => console.log(`Error: ${event.error.name}`));
    als.addEventListener('reading', () => {
        // Defaut ISO value.
        const ISO = 100;
        // Incident-light calibration constant.
        const C = 250;

        let EV = Math.round(Math.log2((als.illuminance * ISO) / C));
        console.log(`Exposure Value (EV) is: ${EV}`);
    });

    als.start();
});

const als = new AmbientLightSensor();

als.onreading = () => {
    let str = luxToWorkplaceLevel(als.illuminance);
    if (str) {
        console.log(`Light level is suitable for: ${str}.`);
    }
};

als.start();

function luxToWorkplaceLevel(lux) {
    if (lux > 20 && lux < 100) {
        return 'public areas, short visits';
    } else if (lux > 100 && lux < 150) {
        return 'occasionally performed visual tasks';
    } else if (lux > 150 && lux < 250) {
        return 'easy office work, classes, homes, theaters';
    } else if (lux > 250 && lux < 500) {
        return 'normal office work, groceries, laboratories';
    } else if (lux > 500 && lux < 1000) {
        return 'mechanical workshops, drawing, supermarkets';
    } else if (lux > 1000 && lux < 5000) {
        return 'detailed drawing work, visual tasks of low contrast';
    }

    return;
}

3. 安全与隐私考量

Ambient Light Sensor 提供关于设备环境附近 照明条件的信息。潜在隐私风险包括：

• 画像分析。Ambient Light Sensor 可能泄露有关用户使用 模式和周边环境的信息。这些信息可用于增强用户 画像分析和行为分析。

• 跨设备关联。两个设备可以访问包含相同第三方脚本的 网站，该脚本会随时间关联照明级别。

• 跨设备通信。一种简单的广播通信方法可以 使用设备屏幕或相机 LED 闪烁来广播消息，并由附近设备中的 Ambient Light Sensor 读取。

• 跨源泄露。屏幕发出的光可从附近反射表面反射回 传感器。恶意站点可以嵌入来自不同源的 资源，并缩放内容以显示特定像素， 从而逐像素地区分内容。

• 劫持浏览历史。对已访问链接设置样式，以便区分 与已访问和未访问链接相关联的光照级别，即将已访问 链接样式设置为一块黑色屏幕；未访问则为白色。

[ALSPRIVACYANALYSIS]、[PINSKIMMINGVIASENSOR]、 [STEALINGSENSITIVEDATA]、 [VIDEORECOGNITIONAMBIENTLIGHT] 和 [IMAGINGPRIVACY] 等工作进一步深入讨论了 这些问题。

为了缓解 Ambient Light Sensor 特有的这些威胁，用户代理必须 降低传感器读数的精度。用户代理还可以限制 最大采样频率。

这些缓解策略补充了 Generic Sensor API [GENERIC-SENSOR] 中定义的通用 缓解措施。

3.1. 降低传感器读数精度

为降低传感器读数的精度，本规范定义了 一个阈值检查算法（环境光阈值检查算法）以及一个 读数量化算法（环境光读数量化 算法）。

这些算法使用照度舍入倍数和 照度阈值。实现必须遵守 以下有关其值的 要求：

• 照度舍入倍数必须至少为 50 lux。

• 照度阈值应至少为 照度舍入倍数的一半。

注：选择照度舍入 倍数需要在避免暴露过于精确的读数与同时提供 对 API 用户仍然有用的读数之间取得平衡。50 lux 作为 照度舍入倍数最小值，是在 GitHub issue #13 中确定的，当时在不同照明条件下的不同环境光级别测量值被收集 ，并显示可阻止 [STEALINGSENSITIVEDATA] 中描述的攻击。 50 lux 也高于使使用环境光传感器读数进行视频识别（[VIDEORECOGNITIONAMBIENTLIGHT]）不可行所需的 5 lux。

注：照度阈值用于防止泄露 读数在某一特定值附近徘徊但被量化为 不同值这一事实。例如，如果照度舍入倍数为 50， 这可防止当原始读数在 24 和 26 之间切换时， 照度值在 0 和 50 之间切换。阈值检查算法作为 辅助指纹缓解策略的有效性尚未得到数学证明， 但基于实现经验已将其加入本规范。Chromium bug 1332536 和 Chromium review 3666917 包含更多 相关信息。

4. 模型

Ambient Light Sensor 传感器类型的关联 Sensor 子类是 AmbientLightSensor 类。

Ambient Light Sensor 具有一个默认传感器， 即设备的主光检测器。

Ambient Light Sensor 是一个由 名称 "ambient-light-sensor" 标识的强大特性， 这也是其关联的传感器权限名称。其 权限撤销算法是使用 "ambient-light-sensor" 调用 通用传感器权限撤销 算法所得的结果。

Ambient Light Sensor 是一个由字符串 "ambient-light-sensor" 标识的策略控制特性。其默认允许列表为 'self'。

Ambient Light Sensor 具有一个虚拟传感器类型，即 "ambient-light"。

当前光照 级别或 照度 是表示托管设备周围环境光级别的值。 其单位为 lux（lx）[SI]。

注：不同设备在相同光照下报告的 精确 lux 值可能不同， 这是由于检测方法、传感器构造等方面的差异。

Ambient Light Sensor 具有一个以 lux 为单位测量的照度舍入 倍数，它表示照度读数将向其倍数 舍入的一个数。

Ambient Light Sensor 具有一个以 lux 为单位测量的照度阈值， 它用于环境光阈值检查算法。

注：见 § 3.1 降低传感器读数精度，了解上述值的最低要求。

5. API

5.1. AmbientLightSensor 接口

[SecureContext, Exposed=Window]
interface AmbientLightSensor : Sensor {
  constructor(optional SensorOptions sensorOptions = {});
  readonly attribute double? illuminance;
};

为构造一个 AmbientLightSensor 对象，用户代理必须调用 构造环境光传感器对象 抽象操作。

5.1.1. illuminance 属性

illuminance getter 步骤为：

1. 令 illuminance 为以 this 和 "illuminance" 为参数调用 从最新读数获取值所得的结果。

2. 返回 illuminance。

6. 抽象操作

6.1. 构造环境光传感器对象

6.2. 环境 光阈值检查算法

Ambient Light Sensor 传感器类型定义了以下阈值检查算法：

注：此算法调用环境光读数量化 算法，以确保舍入到相同值的读数不会在主更新 最新读数算法中 触发更新。不这样做将向用户表明 原始照度读数处于某个范围内，在该范围中它们的差异 至少达到照度阈值，但并不会 舍入到不同的照度舍入倍数。

6.3. 环境光读数量化算法

Ambient Light Sensor 传感器类型定义了以下读数量化算法：

7. 自动化

本节通过提供 Ambient Light Sensor 特定的虚拟传感器元数据， 扩展了 Generic Sensor API § 9 自动化。

按类型虚拟传感器元数据映射 必须具有以下条目：

键

"ambient-light"

值

一个虚拟传感器元数据，其读数解析算法为 照度读数解析算法。

8. 用例和需求

• Web 应用为智能家居系统控制照明提供输入。

• Web 应用检查工作空间的光照级别是否充足。

• Web 应用为带有手动控制（光圈、快门速度、 ISO）的相机计算设置。

• Web 应用检查当前光照级别，以确定 相机流是否会包含足够准确的数据来满足其目的 （例如，人体存在验证）。

虽然某些用例可能受益于获取精确的环境光测量值，但 将环境光级别波动转换为用户输入事件的用例将受益于 更高的采样频率。

9. 致谢

感谢 Doug Turner 提供初始原型， 感谢 Marcos Caceres 提供测试套件。

感谢 Paul Bakaus 提出 LightLevelSensor 构想。

感谢 Mikhail Pozdnyakov 和 Alexander Shalamov 提供用例和需求。

感谢 Lukasz Olejnik 进行隐私风险评估。