ClashMetaForAndroid icon indicating copy to clipboard operation
ClashMetaForAndroid copied to clipboard

feat: Add BroadcastReceiver with KeepAliveService for reliable automation

Open whjstc opened this issue 1 month ago โ€ข 4 comments

๐ŸŽฏ 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

  1. Auto-stop on home WiFi: Disable proxy when connected to trusted network
  2. Auto-start on mobile data: Enable proxy when leaving home WiFi
  3. Time-based control: Disable proxy during specific hours
  4. 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

whjstc avatar Dec 11 '25 09:12 whjstc