https://github.com/Cap-go/capacitor-ibeacon
Capacitor plugin for iBeacon
https://github.com/Cap-go/capacitor-ibeacon
Last synced: about 1 month ago
JSON representation
Capacitor plugin for iBeacon
- Host: GitHub
- URL: https://github.com/Cap-go/capacitor-ibeacon
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-10-26T17:19:54.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-05T00:26:20.000Z (about 1 month ago)
- Last Synced: 2026-02-05T11:00:07.843Z (about 1 month ago)
- Language: Java
- Size: 557 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-capacitor - iBeacon - Proximity detection and beacon region monitoring. ([Capgo plugins](https://capgo.app/) / Communication & Messaging)
README
# capacitor-ibeacon
iBeacon plugin for Capacitor - proximity detection and beacon region monitoring.
## Documentation
The most complete doc is available here: https://capgo.app/docs/plugins/ibeacon/
## Compatibility
| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\*.\* | v8.\*.\* | ✅ |
| v7.\*.\* | v7.\*.\* | On demand |
| v6.\*.\* | v6.\*.\* | ❌ |
| v5.\*.\* | v5.\*.\* | ❌ |
> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
## Install
```bash
npm install @capgo/capacitor-ibeacon
npx cap sync
```
## Configuration
### iOS
Add the following to your `Info.plist`:
```xml
NSLocationWhenInUseUsageDescription
This app needs location access to detect nearby beacons
NSLocationAlwaysAndWhenInUseUsageDescription
This app needs location access to monitor beacons in the background
NSBluetoothAlwaysUsageDescription
This app uses Bluetooth to detect nearby beacons
UIBackgroundModes
location
```
### Android
The plugin automatically includes all required permissions and dependencies. No manual configuration needed.
**Permissions included:**
- Location permissions (fine, coarse, background)
- Bluetooth permissions (with proper legacy support for Android ≤11 and modern permissions for Android 12+)
- Foreground service permissions for background beacon scanning
- Boot completed permission for persistent monitoring
**Dependencies included:**
- AltBeacon Android Beacon Library (2.21.2)
**Important:** You still need to request permissions at runtime using the plugin's authorization methods (see API section below).
## API
All methods are available through the `CapacitorIbeacon` object:
```typescript
import { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';
```
### startMonitoringForRegion(options: BeaconRegion)
Start monitoring for a beacon region. Triggers events when entering/exiting the region.
```typescript
await CapacitorIbeacon.startMonitoringForRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
major: 1,
minor: 2
});
```
### stopMonitoringForRegion(options: BeaconRegion)
Stop monitoring for a beacon region.
```typescript
await CapacitorIbeacon.stopMonitoringForRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});
```
### startRangingBeaconsInRegion(options: BeaconRegion)
Start ranging beacons in a region. Provides continuous distance updates.
```typescript
await CapacitorIbeacon.startRangingBeaconsInRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});
```
### stopRangingBeaconsInRegion(options: BeaconRegion)
Stop ranging beacons in a region.
```typescript
await CapacitorIbeacon.stopRangingBeaconsInRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});
```
### startAdvertising(options: BeaconAdvertisingOptions)
Start advertising the device as an iBeacon (iOS only).
```typescript
await CapacitorIbeacon.startAdvertising({
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
major: 1,
minor: 2,
identifier: 'MyBeacon'
});
```
### stopAdvertising()
Stop advertising the device as an iBeacon (iOS only).
```typescript
await CapacitorIbeacon.stopAdvertising();
```
### requestWhenInUseAuthorization()
Request "When In Use" location authorization.
```typescript
const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();
console.log('Authorization status:', status);
```
### requestAlwaysAuthorization()
Request "Always" location authorization (required for background monitoring).
```typescript
const { status } = await CapacitorIbeacon.requestAlwaysAuthorization();
console.log('Authorization status:', status);
```
### getAuthorizationStatus()
Get current location authorization status.
```typescript
const { status } = await CapacitorIbeacon.getAuthorizationStatus();
// status: 'not_determined' | 'restricted' | 'denied' | 'authorized_always' | 'authorized_when_in_use'
```
### isBluetoothEnabled()
Check if Bluetooth is enabled on the device.
```typescript
const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();
if (!enabled) {
console.log('Please enable Bluetooth');
}
```
### isRangingAvailable()
Check if ranging is available on the device.
```typescript
const { available } = await CapacitorIbeacon.isRangingAvailable();
```
### enableARMAFilter(options: { enabled: boolean })
Enable ARMA filtering for distance calculations (Android only).
```typescript
await CapacitorIbeacon.enableARMAFilter({ enabled: true });
```
### Android background scanning
Android 8+ requires a foreground service to keep Bluetooth scanning alive in the background. You can opt in once and the plugin will automatically
toggle background scanning when the app moves between foreground and background.
```typescript
// Enable background scanning globally (Android only)
await CapacitorIbeacon.enableBackgroundMode({ enabled: true });
// Or opt in per call
await CapacitorIbeacon.startMonitoringForRegion({
identifier: 'MyBeaconRegion',
uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
enableBackgroundMode: true,
});
```
You can also enable it via Capacitor config:
```typescript
// capacitor.config.ts
plugins: {
CapacitorIbeacon: {
enableBackgroundMode: true,
},
}
```
## Events
Listen to beacon events using Capacitor's event system:
```typescript
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();
```
## Complete Example
```typescript
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();
```
## TypeScript Types
### BeaconRegion
```typescript
interface BeaconRegion {
identifier: string;
uuid: string;
major?: number;
minor?: number;
notifyEntryStateOnDisplay?: boolean;
}
```
### Beacon
```typescript
interface Beacon {
uuid: string;
major: number;
minor: number;
rssi: number;
proximity: 'immediate' | 'near' | 'far' | 'unknown';
accuracy: number;
}
```
### BeaconAdvertisingOptions
```typescript
interface BeaconAdvertisingOptions {
uuid: string;
major: number;
minor: number;
identifier: string;
measuredPower?: number;
}
```
## Proximity Values
- **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
## Important Notes
1. **iOS Background Monitoring**: To monitor beacons in the background, you need "Always" location permission and the `location` background mode in Info.plist.
2. **Android Library**: Android implementation requires the AltBeacon library to be integrated into your project.
3. **Battery Usage**: Continuous beacon ranging can consume significant battery. Consider using monitoring (which is more battery-efficient) and only start ranging when needed.
4. **UUID Format**: UUIDs must be in the standard format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`
5. **Major/Minor Values**: These are optional 16-bit unsigned integers (0-65535) used to identify specific beacons within a UUID.
6. **Permissions**: Always request and check permissions before starting beacon operations.
## Credits
This plugin was inspired by [cordova-plugin-ibeacon](https://github.com/petermetz/cordova-plugin-ibeacon) and adapted for Capacitor.
## License
MIT
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this plugin.