{"id":32477013,"url":"https://github.com/cap-go/capacitor-ibeacon","last_synced_at":"2026-02-23T09:12:17.680Z","repository":{"id":320919593,"uuid":"1083768524","full_name":"Cap-go/capacitor-ibeacon","owner":"Cap-go","description":"Capacitor plugin for iBeacon ","archived":false,"fork":false,"pushed_at":"2026-01-25T04:50:26.000Z","size":515,"stargazers_count":4,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-25T19:07:53.060Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cap-go.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Cap-go","patreon":null,"open_collective":"capgo","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2025-10-26T17:19:54.000Z","updated_at":"2026-01-25T04:50:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"f082de9e-1a9a-404b-8777-6102abe1d4a9","html_url":"https://github.com/Cap-go/capacitor-ibeacon","commit_stats":null,"previous_names":["cap-go/capacitor-ibeacon"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/Cap-go/capacitor-ibeacon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-ibeacon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-ibeacon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-ibeacon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-ibeacon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cap-go","download_url":"https://codeload.github.com/Cap-go/capacitor-ibeacon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-ibeacon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28816321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T12:25:15.069Z","status":"ssl_error","status_checked_at":"2026-01-27T12:25:05.297Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-26T22:49:05.433Z","updated_at":"2026-02-23T09:12:17.673Z","avatar_url":"https://github.com/Cap-go.png","language":"Java","funding_links":["https://github.com/sponsors/Cap-go","https://opencollective.com/capgo"],"categories":[],"sub_categories":[],"readme":"# capacitor-ibeacon\n  \u003ca href=\"https://capgo.app/\"\u003e\u003cimg src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/\u003e\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch2\u003e\u003ca href=\"https://capgo.app/?ref=plugin_ibeacon\"\u003e ➡️ Get Instant updates for your App with Capgo\u003c/a\u003e\u003c/h2\u003e\n  \u003ch2\u003e\u003ca href=\"https://capgo.app/consulting/?ref=plugin_ibeacon\"\u003e Missing a feature? We'll build the plugin for you 💪\u003c/a\u003e\u003c/h2\u003e\n\u003c/div\u003e\n\niBeacon plugin for Capacitor - proximity detection and beacon region monitoring.\n\n## Documentation\n\nThe most complete doc is available here: https://capgo.app/docs/plugins/ibeacon/\n\n## Compatibility\n\n| Plugin version | Capacitor compatibility | Maintained |\n| -------------- | ----------------------- | ---------- |\n| v8.\\*.\\*       | v8.\\*.\\*                | ✅          |\n| v7.\\*.\\*       | v7.\\*.\\*                | On demand   |\n| v6.\\*.\\*       | v6.\\*.\\*                | ❌          |\n| v5.\\*.\\*       | v5.\\*.\\*                | ❌          |\n\n\u003e **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.\n\n## Install\n\n```bash\nnpm install @capgo/capacitor-ibeacon\nnpx cap sync\n```\n\n## Configuration\n\n### iOS\n\n#### Step 1: Configure Info.plist\n\nAdd the following keys to your `ios/App/App/Info.plist` file:\n\n```xml\n\u003c!-- Required: Location permission for beacon detection --\u003e\n\u003ckey\u003eNSLocationWhenInUseUsageDescription\u003c/key\u003e\n\u003cstring\u003eThis app needs location access to detect nearby beacons\u003c/string\u003e\n\n\u003c!-- Required for background monitoring: Always authorization --\u003e\n\u003ckey\u003eNSLocationAlwaysAndWhenInUseUsageDescription\u003c/key\u003e\n\u003cstring\u003eThis app needs location access to monitor beacons in the background\u003c/string\u003e\n\n\u003c!-- Required: Bluetooth usage (iOS 13+) --\u003e\n\u003ckey\u003eNSBluetoothAlwaysUsageDescription\u003c/key\u003e\n\u003cstring\u003eThis app uses Bluetooth to detect nearby beacons\u003c/string\u003e\n\n\u003c!-- Required for iOS 12 and earlier --\u003e\n\u003ckey\u003eNSBluetoothPeripheralUsageDescription\u003c/key\u003e\n\u003cstring\u003eThis app uses Bluetooth to detect and advertise as beacons\u003c/string\u003e\n\n\u003c!-- Required for background beacon monitoring --\u003e\n\u003ckey\u003eUIBackgroundModes\u003c/key\u003e\n\u003carray\u003e\n  \u003cstring\u003elocation\u003c/string\u003e\n  \u003cstring\u003ebluetooth-central\u003c/string\u003e\n\u003c/array\u003e\n```\n\n#### Step 2: Enable Capabilities in Xcode\n\n1. Open your project in Xcode: `ios/App/App.xcworkspace`\n2. Select your app target\n3. Go to the \"Signing \u0026 Capabilities\" tab\n4. Click \"+ Capability\" and add \"Background Modes\"\n5. Check the following options:\n   - ✅ **Location updates** (required for background beacon monitoring)\n   - ✅ **Uses Bluetooth LE accessories** (required for beacon detection)\n\n#### Permissions Required\n\n- **When In Use**: For foreground beacon ranging and monitoring\n- **Always**: Required for background beacon monitoring (detecting beacons when app is not active)\n- **Bluetooth**: Automatically granted on iOS 13+ when using CoreLocation for beacons\n\n\u003e **Note**: The plugin uses CoreLocation for beacon detection, which handles Bluetooth scanning internally. Direct Bluetooth permissions are only needed if your app also uses CoreBluetooth for other purposes (e.g., advertising as a beacon).\n\n### Android\n\nThe plugin automatically includes all required permissions and dependencies. No manual configuration needed.\n\n**Permissions included:**\n- Location permissions (fine, coarse, background)\n- Bluetooth permissions (with proper legacy support for Android ≤11 and modern permissions for Android 12+)\n- Foreground service permissions for background beacon scanning\n- Boot completed permission for persistent monitoring\n\n**Dependencies included:**\n- AltBeacon Android Beacon Library (2.21.2)\n\n**Important:** You still need to request permissions at runtime using the plugin's authorization methods (see API section below).\n\n## API\n\nAll methods are available through the `CapacitorIbeacon` object:\n\n```typescript\nimport { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';\n```\n\n### startMonitoringForRegion(options: BeaconRegion)\n\nStart monitoring for a beacon region. Triggers events when entering/exiting the region.\n\n```typescript\nawait CapacitorIbeacon.startMonitoringForRegion({\n  identifier: 'MyBeaconRegion',\n  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',\n  major: 1,\n  minor: 2\n});\n```\n\n### stopMonitoringForRegion(options: BeaconRegion)\n\nStop monitoring for a beacon region.\n\n```typescript\nawait CapacitorIbeacon.stopMonitoringForRegion({\n  identifier: 'MyBeaconRegion',\n  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'\n});\n```\n\n### startRangingBeaconsInRegion(options: BeaconRegion)\n\nStart ranging beacons in a region. Provides continuous distance updates.\n\n```typescript\nawait CapacitorIbeacon.startRangingBeaconsInRegion({\n  identifier: 'MyBeaconRegion',\n  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'\n});\n```\n\n### stopRangingBeaconsInRegion(options: BeaconRegion)\n\nStop ranging beacons in a region.\n\n```typescript\nawait CapacitorIbeacon.stopRangingBeaconsInRegion({\n  identifier: 'MyBeaconRegion',\n  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'\n});\n```\n\n### startAdvertising(options: BeaconAdvertisingOptions)\n\nStart advertising the device as an iBeacon (iOS only).\n\n```typescript\nawait CapacitorIbeacon.startAdvertising({\n  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',\n  major: 1,\n  minor: 2,\n  identifier: 'MyBeacon'\n});\n```\n\n### stopAdvertising()\n\nStop advertising the device as an iBeacon (iOS only).\n\n```typescript\nawait CapacitorIbeacon.stopAdvertising();\n```\n\n### requestWhenInUseAuthorization()\n\nRequest \"When In Use\" location authorization.\n\n```typescript\nconst { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();\nconsole.log('Authorization status:', status);\n```\n\n### requestAlwaysAuthorization()\n\nRequest \"Always\" location authorization (required for background monitoring).\n\n```typescript\nconst { status } = await CapacitorIbeacon.requestAlwaysAuthorization();\nconsole.log('Authorization status:', status);\n```\n\n### getAuthorizationStatus()\n\nGet current location authorization status.\n\n```typescript\nconst { status } = await CapacitorIbeacon.getAuthorizationStatus();\n// status: 'not_determined' | 'restricted' | 'denied' | 'authorized_always' | 'authorized_when_in_use'\n```\n\n### isBluetoothEnabled()\n\nCheck if Bluetooth is enabled on the device.\n\n```typescript\nconst { enabled } = await CapacitorIbeacon.isBluetoothEnabled();\nif (!enabled) {\n  console.log('Please enable Bluetooth');\n}\n```\n\n### isRangingAvailable()\n\nCheck if ranging is available on the device.\n\n```typescript\nconst { available } = await CapacitorIbeacon.isRangingAvailable();\n```\n\n### enableARMAFilter(options: { enabled: boolean })\n\nEnable ARMA filtering for distance calculations (Android only).\n\n```typescript\nawait CapacitorIbeacon.enableARMAFilter({ enabled: true });\n```\n\n### Android background scanning\n\nAndroid 8+ requires a foreground service to keep Bluetooth scanning alive in the background. You can opt in once and the plugin will automatically\ntoggle background scanning when the app moves between foreground and background.\n\n```typescript\n// Enable background scanning globally (Android only)\nawait CapacitorIbeacon.enableBackgroundMode({ enabled: true });\n\n// Or opt in per call\nawait CapacitorIbeacon.startMonitoringForRegion({\n  identifier: 'MyBeaconRegion',\n  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',\n  enableBackgroundMode: true,\n});\n```\n\nYou can also enable it via Capacitor config:\n\n```typescript\n// capacitor.config.ts\nplugins: {\n  CapacitorIbeacon: {\n    enableBackgroundMode: true,\n  },\n}\n```\n\n## Events\n\nListen to beacon events using Capacitor's event system:\n\n```typescript\nimport { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';\nimport { PluginListenerHandle } from '@capacitor/core';\n\n// Listen for ranging events\nconst rangingListener: PluginListenerHandle = await CapacitorIbeacon.addListener(\n  'didRangeBeacons',\n  (data) =\u003e {\n    console.log('Beacons detected:', data.beacons);\n    data.beacons.forEach(beacon =\u003e {\n      console.log(`Beacon: ${beacon.uuid}, Distance: ${beacon.accuracy}m, Proximity: ${beacon.proximity}`);\n    });\n  }\n);\n\n// Listen for region enter events\nconst enterListener: PluginListenerHandle = await CapacitorIbeacon.addListener(\n  'didEnterRegion',\n  (data) =\u003e {\n    console.log('Entered region:', data.region.identifier);\n  }\n);\n\n// Listen for region exit events\nconst exitListener: PluginListenerHandle = await CapacitorIbeacon.addListener(\n  'didExitRegion',\n  (data) =\u003e {\n    console.log('Exited region:', data.region.identifier);\n  }\n);\n\n// Listen for region state changes\nconst stateListener: PluginListenerHandle = await CapacitorIbeacon.addListener(\n  'didDetermineStateForRegion',\n  (data) =\u003e {\n    console.log(`Region ${data.region.identifier}: ${data.state}`);\n  }\n);\n\n// Clean up listeners when done\nrangingListener.remove();\nenterListener.remove();\nexitListener.remove();\nstateListener.remove();\n```\n\n## Complete Example\n\n```typescript\nimport { CapacitorIbeacon } from '@capgo/capacitor-ibeacon';\n\n// Define your beacon region\nconst beaconRegion = {\n  identifier: 'MyStore',\n  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',\n  major: 1\n};\n\nasync function setupBeaconMonitoring() {\n  try {\n    // Request permission\n    const { status } = await CapacitorIbeacon.requestWhenInUseAuthorization();\n    \n    if (status !== 'authorized_when_in_use' \u0026\u0026 status !== 'authorized_always') {\n      console.error('Location permission denied');\n      return;\n    }\n\n    // Check if Bluetooth is enabled\n    const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();\n    if (!enabled) {\n      console.error('Bluetooth is not enabled');\n      return;\n    }\n\n    // Set up event listeners\n    await CapacitorIbeacon.addListener('didEnterRegion', (data) =\u003e {\n      console.log('Welcome! You entered:', data.region.identifier);\n      // Show welcome notification or trigger action\n    });\n\n    await CapacitorIbeacon.addListener('didExitRegion', (data) =\u003e {\n      console.log('Goodbye! You left:', data.region.identifier);\n    });\n\n    await CapacitorIbeacon.addListener('didRangeBeacons', (data) =\u003e {\n      data.beacons.forEach(beacon =\u003e {\n        console.log(`Beacon ${beacon.minor}: ${beacon.proximity} (${beacon.accuracy.toFixed(2)}m)`);\n      });\n    });\n\n    // Start monitoring\n    await CapacitorIbeacon.startMonitoringForRegion(beaconRegion);\n    console.log('Started monitoring for beacons');\n\n    // Start ranging for distance updates\n    await CapacitorIbeacon.startRangingBeaconsInRegion(beaconRegion);\n    console.log('Started ranging beacons');\n\n  } catch (error) {\n    console.error('Error setting up beacon monitoring:', error);\n  }\n}\n\n// Call the setup function\nsetupBeaconMonitoring();\n```\n\n## TypeScript Types\n\n### BeaconRegion\n\n```typescript\ninterface BeaconRegion {\n  identifier: string;\n  uuid: string;\n  major?: number;\n  minor?: number;\n  notifyEntryStateOnDisplay?: boolean;\n}\n```\n\n### Beacon\n\n```typescript\ninterface Beacon {\n  uuid: string;\n  major: number;\n  minor: number;\n  rssi: number;\n  proximity: 'immediate' | 'near' | 'far' | 'unknown';\n  accuracy: number;\n}\n```\n\n### BeaconAdvertisingOptions\n\n```typescript\ninterface BeaconAdvertisingOptions {\n  uuid: string;\n  major: number;\n  minor: number;\n  identifier: string;\n  measuredPower?: number;\n}\n```\n\n## Proximity Values\n\n- **immediate**: Very close to the beacon (within a few centimeters)\n- **near**: Relatively close to the beacon (within a couple of meters)\n- **far**: Further away from the beacon (10+ meters)\n- **unknown**: Distance cannot be determined\n\n## Important Notes\n\n1. **iOS Background Monitoring**: To monitor beacons in the background, you need:\n   - \"Always\" location authorization (`requestAlwaysAuthorization()`)\n   - Background Modes capability enabled in Xcode\n   - `UIBackgroundModes` with both `location` and `bluetooth-central` in Info.plist\n\n2. **iOS Xcode Configuration**: Adding Info.plist keys alone is not enough. You **must** enable Background Modes capability in Xcode (see Configuration section above). This is the most common setup issue.\n\n3. **Android Library**: This plugin includes the AltBeacon Android Beacon Library (2.21.2) automatically.\n\n4. **Battery Usage**: Continuous beacon ranging can consume significant battery. Consider using monitoring (which is more battery-efficient) and only start ranging when needed.\n\n5. **UUID Format**: UUIDs must be in the standard format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`\n\n6. **Major/Minor Values**: These are optional 16-bit unsigned integers (0-65535) used to identify specific beacons within a UUID.\n\n7. **Permissions**: Always request and check permissions before starting beacon operations.\n\n## Troubleshooting\n\n### iOS Issues\n\n**\"Beacons not detected\" or \"Plugin not working\"**\n\n1. **Verify Info.plist configuration**:\n   - Ensure all required keys are present (see Configuration section above)\n   - Check that permission descriptions are meaningful and not empty\n\n2. **Enable Background Modes in Xcode**:\n   - This is a common issue - you MUST enable capabilities in Xcode, not just add Info.plist keys\n   - Open `ios/App/App.xcworkspace` in Xcode\n   - Select your target → \"Signing \u0026 Capabilities\"\n   - Add \"Background Modes\" capability\n   - Check \"Location updates\" and \"Uses Bluetooth LE accessories\"\n\n3. **Request proper authorization**:\n   ```typescript\n   // For foreground detection only\n   await CapacitorIbeacon.requestWhenInUseAuthorization();\n   \n   // For background monitoring (required for region enter/exit events when app is closed)\n   await CapacitorIbeacon.requestAlwaysAuthorization();\n   ```\n\n4. **Check Bluetooth is enabled**:\n   ```typescript\n   const { enabled } = await CapacitorIbeacon.isBluetoothEnabled();\n   if (!enabled) {\n     // Prompt user to enable Bluetooth in Settings\n   }\n   ```\n\n5. **Verify authorization status**:\n   ```typescript\n   const { status } = await CapacitorIbeacon.getAuthorizationStatus();\n   console.log('Auth status:', status);\n   // Should be 'authorized_when_in_use' or 'authorized_always'\n   ```\n\n6. **Check device compatibility**:\n   - iBeacon requires iOS 7.0+\n   - Some features require specific iOS versions (e.g., ranging in background)\n   - Use `isRangingAvailable()` to check device support\n\n**\"No events firing\" or \"addListener not working\"**\n\n- Ensure you set up listeners **before** starting monitoring/ranging:\n  ```typescript\n  // Set up listeners first\n  await CapacitorIbeacon.addListener('didEnterRegion', (data) =\u003e {\n    console.log('Entered:', data.region.identifier);\n  });\n  \n  // Then start monitoring\n  await CapacitorIbeacon.startMonitoringForRegion({\n    identifier: 'MyRegion',\n    uuid: 'YOUR-UUID-HERE'\n  });\n  ```\n\n**Background monitoring not working**\n\n- Requires \"Always\" authorization: `requestAlwaysAuthorization()`\n- Must have `UIBackgroundModes` with `location` and `bluetooth-central` in Info.plist\n- Must have Background Modes capability enabled in Xcode\n- iOS may throttle background scanning to preserve battery\n\n### Android Issues\n\nSee the Android permissions section in the Configuration above. Most Android issues relate to:\n- Not requesting runtime permissions\n- Missing foreground service on Android 8+\n- Bluetooth not enabled\n\nFor detailed Android troubleshooting, check the AltBeacon library documentation.\n\n## Credits\n\nThis plugin was inspired by [cordova-plugin-ibeacon](https://github.com/petermetz/cordova-plugin-ibeacon) and adapted for Capacitor.\n\n## License\n\nMIT\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this plugin.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-go%2Fcapacitor-ibeacon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcap-go%2Fcapacitor-ibeacon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-go%2Fcapacitor-ibeacon/lists"}