Overview

Ambient Light Sensor Plugin provides OutSystems 11 mobile applications with access to the device's built-in ambient light sensor on Android devices.

The component acts as a lightweight bridge between OutSystems and the native Android light sensor, allowing applications to check sensor availability and retrieve the current ambient light intensity in lux (lx).

This component is useful for applications that need to react to or monitor the lighting conditions around the mobile device.

Features

• Check whether an ambient light sensor is available on the device.
• Retrieve the current ambient light intensity in lux (lx).
• Access the native sensor through simple OutSystems Client Actions.
• Handle unavailable sensors and reading errors through output parameters.
• No custom native Android code is required in the consuming OutSystems application.

Requirements

• OutSystems 11
• Mobile / Phone application
• Android device
• Device with a supported ambient light sensor
• Cordova-based mobile application

Important: This component currently supports Android only. Sensor availability depends on the hardware capabilities of the device.

Client Actions

1. CheckAmbientLightAvailability

Checks whether the device has an accessible ambient light sensor.

Inputs

None.

Outputs

Example

CheckAmbientLightAvailability
        ↓
IsAvailable
        ↓
If True → Continue using the light sensor
If False → Handle unavailable sensor

2. GetCurrentLight

Retrieves the current ambient light intensity measured by the device's built-in light sensor.

Inputs

None.

Outputs

Example

GetCurrentLight
      ↓
Lux = 245.50

The returned value represents the ambient light intensity detected by the device at the time of the request.

Basic Usage

A typical implementation can follow this flow:

Screen Initialize
       ↓
CheckAmbientLightAvailability
       ↓
IsAvailable?
   ┌───┴────┐
  Yes       No
   ↓         ↓
GetCurrentLight
             ↓
           Handle
          unavailable

After successfully retrieving the reading:

GetCurrentLight.Lux

can be displayed in the application or used in application logic.

Example Use Cases

The ambient light reading can be used for scenarios such as:

Context-aware applications

Change application behavior based on the surrounding light level.

Adaptive user experiences

Use the current light conditions as an input for adjusting application behavior or presentation.

Environment monitoring

Capture light-level information as part of a larger mobile workflow.

Sensor-driven applications

Combine the ambient light sensor with other device capabilities to create context-aware experiences.

Understanding Lux

Lux (lx) is the unit used to represent illuminance, or the amount of visible light reaching a surface.

The value returned by the component is obtained from the device's native ambient light sensor.

Actual readings can vary depending on:

• Device hardware
• Sensor placement
• Device orientation
• Distance from a light source
• Surrounding environment

Therefore, applications should generally use the reading as a sensor measurement rather than assuming an identical value across all devices.

Error Handling

Both Client Actions provide error information so that applications can handle unsupported or unavailable sensors gracefully.

Recommended pattern:

GetCurrentLight
      ↓
IsSuccess?
   ┌──┴──┐
  Yes    No
   ↓      ↓
Use Lux  Show/handle
         ErrorMessage

For example:

If GetCurrentLight.IsSuccess
    → Use GetCurrentLight.Lux
Else
    → Handle GetCurrentLight.ErrorMessage

Device Compatibility

The component relies on the native Android ambient light sensor.

Some Android devices may not contain an ambient light sensor. In such cases:

• CheckAmbientLightAvailability returns IsAvailable = False.
• GetCurrentLight returns IsSuccess = False and provides an appropriate error message.

Always check availability when the sensor is an optional capability for your application.

Third-Party Dependency

This component uses the open-source:

cordova-plugin-ambient-light

Repository:

https://github.com/murali838/cordova-plugin-ambient-light.git

The dependency is an Android Cordova plugin that provides access to the native ambient light sensor.

The original plugin is distributed under the MIT License. The original license and attribution are retained in the dependency repository.

License

The Ambient Light Sensor Plugin OutSystems component is distributed under the BSD-3-Clause License.

The bundled/used third-party dependency remains subject to its original MIT License.

Notes

• Android only.
• Requires a physical device with an ambient light sensor.
• Sensor readings are hardware-dependent and may vary between devices.
• The component retrieves the current light reading on demand through GetCurrentLight.
• This V1 does not expose continuous sensor-watch functionality.