环境光传感器

1. 简介

环境光传感器扩展了通用传感器 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. 安全与隐私注意事项

环境光传感器提供有关设备环境光照条件的信息。潜在的隐私风险包括：

• 用户画像。环境光传感器可能泄露用户的使用模式和周围环境信息。这些信息可用于增强用户画像和行为分析。

• 跨设备链接。两个设备可以访问包含相同第三方脚本的网站，该脚本会随着时间关联光照水平。

• 跨设备通信。一种简单的广播通信方法可以使用设备屏幕或摄像头 LED 闪光灯向附近设备的环境光传感器广播消息。

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

• 劫持浏览历史。通过样式化已访问链接来区分与已访问和未访问链接相关的光照水平，例如将已访问链接样式化为黑屏块；未访问链接样式化为白屏。

如 [ALSPRIVACYANALYSIS]、[PINSKIMMINGVIASENSOR]、[STEALINGSENSITIVEDATA]、[VIDEORECOGNITIONAMBIENTLIGHT] 和 [IMAGINGPRIVACY] 等作品进一步探讨了这些问题。

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

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

3.1. 降低传感器读数精度

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

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

• 照度舍入倍数必须至少为 50 勒克斯。

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

注意： 选择照度舍入倍数需要在不暴露过于精确的读数与为 API 用户提供仍然有用的读数之间取得平衡。50 勒克斯作为照度舍入倍数的最低值是在GitHub 问题 #13中确定的，此前在不同光照条件下收集了不同的环境光水平测量值（表格链接），并证明可以阻止[STEALINGSENSITIVEDATA]中描述的攻击。此外，50 勒克斯也高于使用环境光传感器读数进行视频识别所需的 5 勒克斯（[VIDEORECOGNITIONAMBIENTLIGHT]）。

注意： 照度阈值用于防止泄露读数围绕某个特定值但被量化为不同值的事实。例如，如果照度舍入倍数为 50，这可以防止原始读数在 24 和 26 之间切换时，照度值在 0 和 50 之间切换。阈值检查算法作为辅助指纹缓解策略的有效性尚未得到数学证明，但基于实现经验已被添加到本规范中。更多信息请参见Chromium 问题 1332536和Chromium 审查 3666917。

4. 模型

环境光传感器的传感器类型的关联传感器子类是AmbientLightSensor类。

环境光传感器有一个默认传感器，即设备的主要光检测器。

环境光传感器是一个强大功能，其标识由名称 "ambient-light-sensor" 提供，同时也是其关联的传感器权限名称。其权限撤销算法是调用通用传感器权限撤销算法并传入 "ambient-light-sensor" 的结果。

环境光传感器是一个由字符串 "ambient-light-sensor" 标识的策略控制功能。其默认允许列表为'self'。

环境光传感器有一个虚拟传感器类型，即 "ambient-light"。

当前光照水平或照度是一个表示设备周围环境光水平的值。其单位为勒克斯（lx）[SI]。

注意： 不同设备在相同光线下报告的精确勒克斯值可能不同，这取决于检测方法、传感器结构等差异。

环境光传感器有一个以勒克斯为单位的照度舍入倍数，表示照度读数将舍入到的倍数。

环境光传感器有一个以勒克斯为单位的照度阈值，用于环境光阈值检查算法。

注意： 请参阅§ 3.1 降低传感器读数精度以了解上述值的最低要求。

5. API

5.1. 环境光传感器接口

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

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

5.1.1. 照度属性

illuminance的 getter 步骤如下：

1. 令illuminance为调用从最新读数获取值并传入this和"illuminance"作为参数的结果。

2. 返回illuminance。

6. 抽象操作

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

6.2. 环境光阈值检查算法

环境光传感器的传感器类型定义了以下阈值检查算法：

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

6.3. 环境光读数量化算法

环境光传感器的传感器类型定义了以下读数量化算法：

7. 自动化

本节通过提供环境光传感器特定的虚拟传感器元数据扩展了通用传感器 API § 9 自动化。

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

键

"ambient-light"

值

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

8. 用例与需求

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

• 一个 Web 应用检查工作空间的光照水平是否足够。

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

• 一个 Web 应用检查当前光照水平以确定相机流是否包含足够准确的数据（例如，人类存在验证）。

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

9. 致谢

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

感谢 Paul Bakaus 提出的 LightLevelSensor 想法。

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

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