iBeacon plugin for Capacitor - proximity detection and beacon region monitoring.
The most complete doc is available here: https://capgo.app/docs/plugins/ibeacon/
npm install @capgo/capacitor-ibeacon
npx cap syncAdd the following to your Info.plist:
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to detect nearby beacons</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs location access to monitor beacons in the background</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to detect nearby beacons</string>
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>Add the following to your AndroidManifest.xml:
<manifest>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>Important: For Android, you need to integrate the AltBeacon library into your project for beacon detection to work.
Add to your app's build.gradle:
dependencies {
implementation 'org.altbeacon:android-beacon-library:2.20+'
}All methods are available through the CapacitorIbeacon object:
import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';Start monitoring for a beacon region. Triggers events when entering/exiting the region.
await CapacitorIbeacon.startMonitoringForRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
major: 1,
minor: 2
});Stop monitoring for a beacon region.
await CapacitorIbeacon.stopMonitoringForRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});Start ranging beacons in a region. Provides continuous distance updates.
await CapacitorIbeacon.startRangingBeaconsInRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});Stop ranging beacons in a region.
await CapacitorIbeacon.stopRangingBeaconsInRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});Start advertising the device as an iBeacon (iOS only).
await CapacitorIbeacon.startAdvertising({
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
major: 1,
minor: 2,
identifier: 'MyBeacon'
});Stop advertising the device as an iBeacon (iOS only).
await CapacitorIbeacon.stopAdvertising();Request "When In Use" location authorization.
const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
console.log('Authorization status:', status);Request "Always" location authorization (required for background monitoring).
const { status } = await CapacitorIbeacon.requestAlwaysAuthorization();
console.log('Authorization status:', status);Get current location authorization status.
const { status } = await CapacitorIbeacon.getAuthorizationStatus();
// status: 'not_determined' | 'restricted' | 'denied' | 'authorized_always' | 'authorized_when_in_use'Check if Bluetooth is enabled on the device.
const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
if (!enabled) {
console.log('Please enable Bluetooth');
}Check if ranging is available on the device.
const { available } = await CapacitorIbeacon.isRangingAvailable();Enable ARMA filtering for distance calculations (Android only).
await CapacitorIbeacon.enableARMAFilter({ enabled: true });Listen to beacon events using Capacitor's event system:
import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
import { PluginListenerHandle } from '@capacitor/core';
// Listen for ranging events
const rangingListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
'didRangeBeacons',
(data) => {
console.log('Beacons detected:', data.beacons);
data.beacons.forEach(beacon => {
console.log(`Beacon: ${beacon.uuid}, Distance: ${beacon.accuracy}m, Proximity: ${beacon.proximity}`);
});
}
);
// Listen for region enter events
const enterListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
'didEnterRegion',
(data) => {
console.log('Entered region:', data.region.identifier);
}
);
// Listen for region exit events
const exitListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
'didExitRegion',
(data) => {
console.log('Exited region:', data.region.identifier);
}
);
// Listen for region state changes
const stateListener: PluginListenerHandle = await CapacitorIbeacon.addListener(
'didDetermineStateForRegion',
(data) => {
console.log(`Region ${data.region.identifier}: ${data.state}`);
}
);
// Clean up listeners when done
rangingListener.remove();
enterListener.remove();
exitListener.remove();
stateListener.remove();import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
// Define your beacon region
const beaconRegion = {
identifier: 'MyStore',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
major: 1
};
async function setupBeaconMonitoring() {
try {
// Request permission
const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
if (status !== 'authorized_when_in_use' && status !== 'authorized_always') {
console.error('Location permission denied');
return;
}
// Check if Bluetooth is enabled
const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
if (!enabled) {
console.error('Bluetooth is not enabled');
return;
}
// Set up event listeners
await CapacitorIbeacon.addListener('didEnterRegion', (data) => {
console.log('Welcome! You entered:', data.region.identifier);
// Show welcome notification or trigger action
});
await CapacitorIbeacon.addListener('didExitRegion', (data) => {
console.log('Goodbye! You left:', data.region.identifier);
});
await CapacitorIbeacon.addListener('didRangeBeacons', (data) => {
data.beacons.forEach(beacon => {
console.log(`Beacon ${beacon.minor}: ${beacon.proximity} (${beacon.accuracy.toFixed(2)}m)`);
});
});
// Start monitoring
await CapacitorIbeacon.startMonitoringForRegion(beaconRegion);
console.log('Started monitoring for beacons');
// Start ranging for distance updates
await CapacitorIbeacon.startRangingBeaconsInRegion(beaconRegion);
console.log('Started ranging beacons');
} catch (error) {
console.error('Error setting up beacon monitoring:', error);
}
}
// Call the setup function
setupBeaconMonitoring();interface BeaconRegion {
identifier: string;
uuid: string;
major?: number;
minor?: number;
notifyEntryStateOnDisplay?: boolean;
}interface Beacon {
uuid: string;
major: number;
minor: number;
rssi: number;
proximity: 'immediate' | 'near' | 'far' | 'unknown';
accuracy: number;
}interface BeaconAdvertisingOptions {
uuid: string;
major: number;
minor: number;
identifier: string;
measuredPower?: number;
}- immediate: Very close to the beacon (within a few centimeters)
- near: Relatively close to the beacon (within a couple of meters)
- far: Further away from the beacon (10+ meters)
- unknown: Distance cannot be determined
-
iOS Background Monitoring: To monitor beacons in the background, you need "Always" location permission and the
locationbackground mode in Info.plist. -
Android Library: Android implementation requires the AltBeacon library to be integrated into your project.
-
Battery Usage: Continuous beacon ranging can consume significant battery. Consider using monitoring (which is more battery-efficient) and only start ranging when needed.
-
UUID Format: UUIDs must be in the standard format:
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -
Major/Minor Values: These are optional 16-bit unsigned integers (0-65535) used to identify specific beacons within a UUID.
-
Permissions: Always request and check permissions before starting beacon operations.
This plugin was inspired by cordova-plugin-ibeacon and adapted for Capacitor.
MIT
See CONTRIBUTING.md for details on how to contribute to this plugin.
