From e1f82a367d2ce9a3eedbd3c17bf93e0d2917956b Mon Sep 17 00:00:00 2001 From: Sebastian Roth Date: Tue, 4 Aug 2026 22:41:44 +0100 Subject: [PATCH 1/2] docs: split Android/iOS debugging into subpages debugging.mdx was 400+ lines; move the platform deep-dives into debugging-android.mdx and debugging-ios.mdx, keep the shared content (debug handlers, custom handlers, general tips) on the main page with links, and register the subpages in the docs.json sidebar. Also fixes trailing-whitespace lint and links the new FGS opt-in troubleshooting section from the Android page. --- docs/debugging-android.mdx | 70 +++++++++++++++++++ docs/debugging-ios.mdx | 84 ++++++++++++++++++++++ docs/debugging.mdx | 139 ++----------------------------------- 3 files changed, 158 insertions(+), 135 deletions(-) create mode 100644 docs/debugging-android.mdx create mode 100644 docs/debugging-ios.mdx diff --git a/docs/debugging-android.mdx b/docs/debugging-android.mdx new file mode 100644 index 00000000..0d74e99f --- /dev/null +++ b/docs/debugging-android.mdx @@ -0,0 +1,70 @@ +--- +title: Android Debugging +description: Debug background tasks on Android — job scheduler inspection, adb commands, common issues +--- + +Deep-dive debugging for Android. For the debug handlers (logging / notification) +and custom handlers, see [Debugging Background Tasks](debugging). For tasks not +running at all, see the [Troubleshooting guide](troubleshooting) first — it is +almost always OEM battery optimization or OS scheduling policy. + +## Job Scheduler Inspection + +Use ADB to inspect Android's job scheduler: + +```bash +# View scheduled jobs +adb shell dumpsys jobscheduler | grep yourapp + +# View detailed job info +adb shell dumpsys jobscheduler yourapp + +# Force run job (debug only) +adb shell cmd jobscheduler run -f yourapp JOB_ID +``` + +## Monitor Job Execution + +```bash +# Monitor WorkManager logs +adb logcat | grep WorkManager + +# Monitor app background execution +adb logcat | grep "yourapp" +``` + +## Common Android Issues + +**Tasks not running:** +- Check battery optimization settings +- Verify app is not in "App Standby" mode +- Ensure device isn't in Doze mode +- Check if constraints are too restrictive + +Tasks stopping after the app is closed is almost always OEM battery +optimization or OS scheduling policy — see the +[Troubleshooting guide](troubleshooting) for per-vendor instructions and +verification steps. + +**Tasks running too often:** +- Android enforces minimum 15-minute intervals for periodic tasks +- Use appropriate constraints to limit execution + +**Play Console asks for a FOREGROUND_SERVICE_DATA_SYNC declaration/video:** +- See the [Troubleshooting guide](troubleshooting) — the permission is opt-in + since 0.10.6 (`workmanager.enableDataSyncForegroundService=true` in + `gradle.properties`), and using the `dataSync` type without it throws at + registration instead of failing silently. + +## Debug Commands + +```bash +# Check if your app is whitelisted from battery optimization +adb shell dumpsys deviceidle whitelist + +# Check battery optimization status +adb shell settings get global battery_saver_constants + +# Force device into idle mode (testing) +adb shell dumpsys deviceidle force-idle +``` diff --git a/docs/debugging-ios.mdx b/docs/debugging-ios.mdx new file mode 100644 index 00000000..8aa3aaef --- /dev/null +++ b/docs/debugging-ios.mdx @@ -0,0 +1,84 @@ +--- +title: iOS Debugging +description: Debug background tasks on iOS — console logging, Xcode, BGTaskScheduler, common issues +--- + +Deep-dive debugging for iOS/macOS. For the debug handlers (logging / notification) +and custom handlers, see [Debugging Background Tasks](debugging). + +## Console Logging + +iOS background tasks have limited execution time. Add detailed logging: + +```dart +@pragma('vm:entry-point') +void callbackDispatcher() { + Workmanager().executeTask((task, inputData) async { + print('[iOS BG] Task started: $task at ${DateTime.now()}'); + + try { + // Your task logic + final result = await performTask(); + print('[iOS BG] Task completed successfully'); + return true; + } catch (e) { + print('[iOS BG] Task failed: $e'); + return false; + } + }); +} +``` + +## Xcode Debugging + +**For Background Fetch tasks:** +Use **Debug → Perform Fetch** from the Xcode run menu while your app is running. + +**For BGTaskScheduler tasks (processing/periodic):** +Use Xcode's console to trigger tasks manually: + +```objc +// Trigger specific BGTaskScheduler task +e -l objc -- (void)[[BGTaskScheduler sharedScheduler] + _simulateLaunchForTaskWithIdentifier:@"com.yourapp.task.identifier"] +``` + +## Monitor Scheduled Tasks + +Check what tasks iOS has scheduled: + +```dart +// iOS 13+ only +if (Platform.isIOS) { + final tasks = await Workmanager().printScheduledTasks(); + print('Scheduled tasks: $tasks'); +} +``` + +This prints output like: +``` +[BGTaskScheduler] Task Identifier: your.task.id earliestBeginDate: 2023.10.10 PM 11:10:12 +[BGTaskScheduler] There are no scheduled tasks +``` + +## Common iOS Issues + +**Background App Refresh disabled:** +- Check iOS Settings → General → Background App Refresh +- See [Apple's Background App Refresh Guide](https://support.apple.com/en-us/102425) + +**Tasks never run:** +- App hasn't been used recently (iOS learning algorithm) — [iOS Power Management](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/PrioritizeWorkAtTheTaskLevel.html) +- Task identifiers don't match between Info.plist and AppDelegate — [check iOS setup](quickstart#option-b-processing-tasks-for-complex-operations) +- Missing BGTaskSchedulerPermittedIdentifiers in Info.plist — [review iOS configuration](quickstart#ios) + +**Tasks stop working:** +- iOS battery optimization kicked in — [WWDC 2020: Background execution demystified](https://developer.apple.com/videos/play/wwdc2020/10063/) +- App removed from recent apps too often +- User disabled background refresh — [check Background Fetch setup](quickstart#option-a-periodic-tasks-recommended-for-most-use-cases) +- Task taking longer than 30 seconds — [BGTaskScheduler Documentation](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler) + +**Tasks run but don't complete:** +- Hitting 30-second execution limit — [Background Tasks Best Practices](https://developer.apple.com/documentation/backgroundtasks/bgtask) +- Network requests timing out +- Heavy processing blocking the thread — [WWDC 2019: Advances in App Background Execution](https://developer.apple.com/videos/play/wwdc2019/707/) diff --git a/docs/debugging.mdx b/docs/debugging.mdx index 57ba4ef9..42a58505 100644 --- a/docs/debugging.mdx +++ b/docs/debugging.mdx @@ -173,141 +173,10 @@ WorkmanagerDebug.setCurrent(CustomDebugHandler()) For detailed information about task statuses, lifecycle, and notification formats, see the [Task Status Tracking](task-status) guide. -## Android Debugging +## Platform deep-dives -### Job Scheduler Inspection - -Use ADB to inspect Android's job scheduler: - -```bash -# View scheduled jobs -adb shell dumpsys jobscheduler | grep yourapp - -# View detailed job info -adb shell dumpsys jobscheduler yourapp - -# Force run job (debug only) -adb shell cmd jobscheduler run -f yourapp JOB_ID -``` - -### Monitor Job Execution - -```bash -# Monitor WorkManager logs -adb logcat | grep WorkManager - -# Monitor app background execution -adb logcat | grep "yourapp" -``` - -### Common Android Issues - -**Tasks not running:** -- Check battery optimization settings -- Verify app is not in "App Standby" mode -- Ensure device isn't in Doze mode -- Check if constraints are too restrictive - -Tasks stopping after the app is closed is almost always OEM battery -optimization or OS scheduling policy - see the -[Troubleshooting guide](troubleshooting) for per-vendor instructions and -verification steps. - -**Tasks running too often:** -- Android enforces minimum 15-minute intervals for periodic tasks -- Use appropriate constraints to limit execution - -### Debug Commands - -```bash -# Check if your app is whitelisted from battery optimization -adb shell dumpsys deviceidle whitelist - -# Check battery optimization status -adb shell settings get global battery_saver_constants - -# Force device into idle mode (testing) -adb shell dumpsys deviceidle force-idle -``` - -## iOS Debugging - -### Console Logging - -iOS background tasks have limited execution time. Add detailed logging: - -```dart -@pragma('vm:entry-point') -void callbackDispatcher() { - Workmanager().executeTask((task, inputData) async { - print('[iOS BG] Task started: $task at ${DateTime.now()}'); - - try { - // Your task logic - final result = await performTask(); - print('[iOS BG] Task completed successfully'); - return true; - } catch (e) { - print('[iOS BG] Task failed: $e'); - return false; - } - }); -} -``` - -### Xcode Debugging - -**For Background Fetch tasks:** -Use **Debug → Perform Fetch** from the Xcode run menu while your app is running. - -**For BGTaskScheduler tasks (processing/periodic):** -Use Xcode's console to trigger tasks manually: - -```objc -// Trigger specific BGTaskScheduler task -e -l objc -- (void)[[BGTaskScheduler sharedScheduler] - _simulateLaunchForTaskWithIdentifier:@"com.yourapp.task.identifier"] -``` - -### Monitor Scheduled Tasks - -Check what tasks iOS has scheduled: - -```dart -// iOS 13+ only -if (Platform.isIOS) { - final tasks = await Workmanager().printScheduledTasks(); - print('Scheduled tasks: $tasks'); -} -``` - -This prints output like: -``` -[BGTaskScheduler] Task Identifier: your.task.id earliestBeginDate: 2023.10.10 PM 11:10:12 -[BGTaskScheduler] There are no scheduled tasks -``` - -### Common iOS Issues - -**Background App Refresh disabled:** -- Check iOS Settings → General → Background App Refresh -- See [Apple's Background App Refresh Guide](https://support.apple.com/en-us/102425) - -**Tasks never run:** -- App hasn't been used recently (iOS learning algorithm) - [iOS Power Management](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/PrioritizeWorkAtTheTaskLevel.html) -- Task identifiers don't match between Info.plist and AppDelegate - [check iOS setup](quickstart#option-b-processing-tasks-for-complex-operations) -- Missing BGTaskSchedulerPermittedIdentifiers in Info.plist - [review iOS configuration](quickstart#ios) - -**Tasks stop working:** -- iOS battery optimization kicked in - [WWDC 2020: Background execution demystified](https://developer.apple.com/videos/play/wwdc2020/10063/) -- App removed from recent apps too often -- User disabled background refresh - [check Background Fetch setup](quickstart#option-a-periodic-tasks-recommended-for-most-use-cases) -- Task taking longer than 30 seconds - [BGTaskScheduler Documentation](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler) - -**Tasks run but don't complete:** -- Hitting 30-second execution limit - [Background Tasks Best Practices](https://developer.apple.com/documentation/backgroundtasks/bgtask) -- Network requests timing out -- Heavy processing blocking the thread - [WWDC 2019: Advances in App Background Execution](https://developer.apple.com/videos/play/wwdc2019/707/) +- [Android Debugging](debugging-android) — job scheduler inspection, adb commands, common Android issues. +- [iOS Debugging](debugging-ios) — console logging, Xcode simulation, BGTaskScheduler, common iOS issues. ## General Debugging Tips @@ -389,7 +258,7 @@ Future isTaskHealthy(String taskName, Duration maxAge) async { 4. **Check debug notifications** to confirm execution 5. **Use ADB commands** to force execution if needed -### iOS Testing Workflow +### iOS Testing Workflow 1. **Test on physical device** (simulator doesn't support background tasks) 2. **Enable Background App Refresh** in iOS Settings From 5395324c46132be0eb31ad5542d7cd70d162afb0 Mon Sep 17 00:00:00 2001 From: Sebastian Roth Date: Tue, 4 Aug 2026 23:04:40 +0100 Subject: [PATCH 2/2] docs: register debugging subpages in the sidebar --- docs.json | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 192d9bd0..4da2c92f 100644 --- a/docs.json +++ b/docs.json @@ -41,6 +41,14 @@ "title": "Debugging", "href": "/debugging" }, + { + "title": "Debugging (Android)", + "href": "/debugging-android" + }, + { + "title": "Debugging (iOS)", + "href": "/debugging-ios" + }, { "title": "Web (experimental)", "href": "/web" @@ -56,4 +64,4 @@ ] } ] -} +} \ No newline at end of file