Getting Started

Install

bun add @capgo/capacitor-light-sensor
bunx cap sync

Import

import { LightSensor } from '@capgo/capacitor-light-sensor';

API Overview

isAvailable

Check if the light sensor is available on the current device. You should always check sensor availability before attempting to use it.

import { LightSensor } from '@capgo/capacitor-light-sensor';

const { available } = await LightSensor.isAvailable();

start

Start listening to light sensor updates. This will begin sensor measurements at the specified interval. Use addListener to receive the sensor data.

import { LightSensor } from '@capgo/capacitor-light-sensor';

await LightSensor.start({ updateInterval: 500 });

stop

Stop listening to light sensor updates. This will stop the sensor and conserve battery.

import { LightSensor } from '@capgo/capacitor-light-sensor';

await LightSensor.stop();

checkPermissions

Check the current permission status for high sampling rate sensors. On Android 12+, the HIGH_SAMPLING_RATE_SENSORS permission is required for sensor update intervals below 200ms.

import { LightSensor } from '@capgo/capacitor-light-sensor';

const status = await LightSensor.checkPermissions();

requestPermissions

Request permission for high sampling rate sensors. On Android 12+, this requests the HIGH_SAMPLING_RATE_SENSORS permission.

import { LightSensor } from '@capgo/capacitor-light-sensor';

const status = await LightSensor.requestPermissions();

Type Reference

IsAvailableResult

Result indicating whether the sensor is available.

export interface IsAvailableResult {
  /**
   * Whether the light sensor is available on this device.
   * Always false on iOS as the light sensor API is not available.
   *
   * @since 0.0.1
   */
  available: boolean;
}

StartOptions

Options for starting the light sensor listener.

export interface StartOptions {
  /**
   * The desired interval between sensor updates in milliseconds.
   * On Android 12+, there's a minimum interval of 200ms unless the app
   * has the HIGH_SAMPLING_RATE_SENSORS permission.
   *
   * @default 200
   * @since 0.0.1
   */
  updateInterval?: number;
}

LightSensorCallback

Callback function for light sensor updates.

export type LightSensorCallback = (measurement: LightSensorMeasurement) => void;

PermissionStatus

Result of a permission request or check.

export interface PermissionStatus {
  /**
   * Whether the high sampling rate sensor permission is granted.
   * On Android 12+, this permission is required for update intervals below 200ms.
   *
   * @since 0.0.1
   */
  highSamplingRate: 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';
}

VersionResult

Plugin version information.

export interface VersionResult {
  /**
   * The current version of the plugin.
   *
   * @since 0.0.1
   */
  version: string;
}

LightSensorMeasurement

A single light sensor measurement.

export interface LightSensorMeasurement {
  /**
   * Ambient light level in lux (lx).
   *
   * @since 0.0.1
   */
  illuminance: number;

  /**
   * Timestamp of the measurement in seconds since epoch.
   *
   * @since 0.0.1
   */
  timestamp: number;
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Keep going from Getting Started

If you are using Getting Started to plan dashboard and API operations, connect it with Using @capgo/capacitor-light-sensor for the native capability in Using @capgo/capacitor-light-sensor, API Overview for the implementation detail in API Overview, Introduction for the implementation detail in Introduction, API Keys for the implementation detail in API Keys, and Devices for the implementation detail in Devices.