Automatically enable background mode for Android beacon monitoring

[Copilot]

Android beacon monitoring stopped working when the app moved to background. Android 8+ requires a foreground service for background Bluetooth scanning, but the existing enableBackgroundMode() method required manual invocation.

Changes

Merge with main branch (v8.1.11)

• Resolved merge conflicts with main branch that already included background scanning infrastructure from PR Enable Android background beacon scanning #20
• Integrated with existing setBackgroundModeEnabled(), applyBackgroundMode(), enableForegroundServiceIfNeeded(), and disableForegroundServiceIfNeeded() methods
• Updated to use main branch constants (FOREGROUND_CHANNEL_ID, FOREGROUND_NOTIFICATION_ID)
• Updated plugin version to 8.1.11

Automatic lifecycle management

• startMonitoringForRegion() and startRangingBeaconsInRegion() now automatically enable background mode when enableBackgroundMode parameter is not provided
• stopMonitoringForRegion() and stopRangingBeaconsInRegion() automatically disable background mode when no regions remain
• Works seamlessly with the existing background mode infrastructure that tracks app background state

Documentation

• Leverages existing documentation updates from main branch
• Background mode is now opt-out instead of opt-in

Backward compatibility

Existing code that explicitly passes enableBackgroundMode: true or enableBackgroundMode: false continues to work unchanged. The automatic behavior only activates when the parameter is omitted, making this a non-breaking enhancement.

Example

// Background monitoring now works automatically without extra parameters
await CapacitorIbeacon.startMonitoringForRegion({
  identifier: 'MyBeacon',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D'
});
// Background mode automatically enabled
// Foreground service with notification shown when app goes to background
// didEnterRegion/didExitRegion events fire in background

// Can still explicitly control background mode if needed
await CapacitorIbeacon.startMonitoringForRegion({
  identifier: 'MyBeacon',
  uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
  enableBackgroundMode: false  // Explicitly disable if desired
});

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Android Background Beacon Monitoring - Two Critical Issues</issue_title>
<issue_description>

🐛 Problem Description

There are two critical issues with Android beacon monitoring that have been tested on both the latest version and version 8.0.2 (most stable). Both issues work perfectly on iOS.

🚨 Issue #1: No Background Beacon Detection

When the Android app goes to background, beacon region monitoring completely stops working. The app appears to be running in background, but the monitoring functionality is non-functional.

🚨 Issue #2: Permission Prompts Don't Work

When requesting permissions using capgo methods (requestWhenInUseAuthorization(), requestAlwaysAuthorization()), Android Studio shows repeated "Location not available" errors. This appears to be a missing callback implementation in the Android native code.

📱 Environment

• Plugin Version: @capgo/capacitor-ibeacon@8.0.2 (also tested on latest version)
• Capacitor Version: ^7.4.1
• Target Platform: Android (iOS works correctly)
• Framework: Angular + Ionic + NX Monorepo

🔧 Current Setup

Plugins Used for Android Background Support

• Background Service: @capacitor-community/background-geolocation@1.2.26 (for maintaining background execution)
• Location Permissions: @capacitor/geolocation@7.1.5 (native Capacitor plugin)
• Bluetooth Permissions: @capacitor-community/bluetooth-le@7.2.0 (for nearby device permissions)
• Beacon Monitoring: @capgo/capacitor-ibeacon@8.0.2

🚀 Reproduction Steps

For Issue #1 (Background Detection):

1. Initialize beacon monitoring
2. Call startMonitoringForRegion() for beacon region
3. Put the Android app in background
4. Move device within range of beacon transmitter
5. Result: No didEnterRegion events fired (works perfectly on iOS)

For Issue #2 (Permission Prompts):

1. Call CapacitorIbeacon.requestWhenInUseAuthorization() or requestAlwaysAuthorization()
2. Observe Android Studio logcat
3. Result: "Location not available" errors appear (works perfectly on iOS)

Expected (iOS behavior):

• Background beacon detection works
• Permission prompts appear correctly
• No location-related errors

Actual (Android behavior):

• Background beacon monitoring non-functional
• Permission prompts fail with location errors
• Missing callback implementation causes errors

🔍 Error Details

The error "Location not available" appears to be triggered by a missing callback implementation in the Android native layer of the plugin. This suggests that the Android code is expecting a location callback that is not properly implemented or handled.

❓ Questions

1. Are these known Android-specific issues that are being worked on?

2. Is there a workaround for the missing callback implementation that causes permission prompt failures?

3. Why does background monitoring stop working on Android when it works perfectly on iOS?

4. Should we avoid using capgo permission methods on Android and use alternative approaches?

🔍 Additional Context

• iOS works perfectly: Both background detection and permission prompts function as expected
• Android permissions can be granted manually but capgo methods fail
• Foreground beacon detection works on Android
• Tested on both latest version and 8.0.2 with same results
• Physical beacon hardware confirmed working (detected by other apps and iOS)

💡 Impact

These issues make the plugin unusable for production Android apps that require:

• Background beacon detection (critical for most beacon use cases)
• Programmatic permission requests (essential for user experience)

The Android implementation appears to need significant work to match iOS functionality.</issue_description>

<agent_instructions>When I call startMonitoringForRegion() on Android, it should continue monitoring in background just like it does on iOS, triggering didEnterRegion/didExitRegion events even when the app is not in foreground.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@riderx Hello thanks for sending this issues, the number 2 is something we can fix, but the first one is not expected, i dont event know how we can do it as the background geoloc is on is own process. We could make something if you use the background-geoloc we made as we control both @riderx Hey @ifrolyak can you test latest and tell us if that fix your issue ?

• Fixes Android Background Beacon Monitoring - Two Critical Issues #11

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[riderx]

@copilot fix conflict

[Copilot]

@copilot fix conflict

Conflicts resolved in commit 898ab57. Merged main branch changes and adapted the automatic background mode feature to work with the new implementation structure from PR #20.