Light

pub package

A Flutter plugin for collecting ambient light data on Android and iOS.

Android uses the Environment Sensors API. iOS uses SensorKit ambient light sensor.

Install

Add light as a dependency in pubspec.yaml.

iOS requirements

Caution

Not all devices have SensorKit. Requires iOS 14 or higher. Reading sensory data from iOS requires research entitlements and previous approval from Apple for reading sensory data. Please see the documentations at Configuring your project for sensor reading.

SensorKit requires more setup than Android.

  1. Enable the SensorKit entitlement and include ambient light in your app entitlements:
<key>com.apple.developer.sensorkit.reader.allow</key>
<array>
  <string>ambient-light-sensor</string>
</array>

SensorKit access is entitlement-gated by Apple. Without approved entitlement provisioning, iOS returns an invalid-entitlement error.

  1. Add SensorKit purpose text in Info.plist:
<key>NSSensorKitUsageDetail</key>
<dict>
  <key>SRSensorUsageAmbientLightSensor</key>
  <string>Explain why your app needs ambient light sensor data.</string>
</dict>
  1. Request authorization before or while starting the stream:
final LightAuthorizationStatus status =
    await Light().requestAuthorization();

On Android, requestAuthorization() returns LightAuthorizationStatus.unavailable and no runtime permission prompt is required.

If iOS setup is incomplete, the stream emits a PlatformException (for example, missing entitlement or usage description).

Usage

StreamSubscription<int>? _lightEvents;

Future<void> startListening() async {
  await Light().requestAuthorization(); // no-op on Android
  _lightEvents = Light().lightSensorStream.listen((int luxValue) {
    // Do something with lux.
  });
}

void stopListening() {
  _lightEvents?.cancel();
}

Libraries

light