feat: Add BroadcastReceiver with KeepAliveService for reliable automation
๐ฏ Problem
ExternalControlActivity causes screen flash/popup on some ROMs (especially Flyme, MIUI, ColorOS) when triggered by automation tools like Tasker, breaking the "background automation" experience.
โ Solution
This PR adds two components for reliable background automation:
1. ExternalControlReceiver (BroadcastReceiver)
- Receives broadcasts from Tasker/automation tools
- Completely background operation - no UI triggered
- Supports START/STOP/TOGGLE actions
2. KeepAliveService (Foreground Service)
Why this is needed: During testing, I discovered that BroadcastReceiver fails when the app enters deep sleep (CACHED_EMPTY state, procState=19). The system freezes the app and blocks broadcasts from third-party apps.
Solution: A lightweight foreground service that:
- Keeps the app alive to reliably receive broadcasts
- Uses IMPORTANCE_MIN notification channel (minimal user disturbance)
- Idle service with near-zero battery impact
- Automatically starts with the app
๐งช Testing
Tested extensively on Flyme with Tasker:
- โ 100% reliable after hours in background
- โ No screen flash or popup
- โ App remains responsive to broadcasts even in deep background
- โ Process not frozen (procState improved from 19โ4, oom_adj from 955โ50)
- โ Minimal battery impact (idle foreground service)
๐ฑ Usage
Tasker Configuration
Action: Send Intent
-
Action:
com.github.metacubex.clash.meta.action.START_CLASH(or STOP/TOGGLE) - Target: Broadcast Receiver
-
Package:
com.github.metacubex.clash.meta - Class: (leave empty)
Example Automation Scenarios
- Auto-stop on home WiFi: Disable proxy when connected to trusted network
- Auto-start on mobile data: Enable proxy when leaving home WiFi
- Time-based control: Disable proxy during specific hours
- Charging state: Enable proxy only when charging
๐ Files Changed
-
app/src/main/java/.../ExternalControlReceiver.kt- BroadcastReceiver implementation -
app/src/main/java/.../KeepAliveService.kt- Foreground service for reliability -
app/src/main/java/.../MainApplication.kt- Auto-start KeepAliveService -
app/src/main/AndroidManifest.xml- Register receiver and service -
TASKER_GUIDE.md- Complete user guide with examples -
app/src/main/res/values/strings.xml- Notification strings
๐ง Technical Details
Why Foreground Service instead of battery optimization whitelist?
- Battery optimization is unreliable and ROM-dependent
- Foreground Service is the Android-official way to keep apps alive
- Used by all apps needing background reliability (music players, navigation, etc.)
Resource usage:
- CPU: 0% (idle service)
- Network: 0
- Battery: Negligible (no active operations)
- Memory: ~10-20MB (process kept in memory)
๐ Documentation
Complete Tasker setup guide included in TASKER_GUIDE.md with:
- Step-by-step configuration
- Common automation scenarios
- Troubleshooting tips
- FAQ