From 0c4d44d6892822a75f5d7eb7dd0d3aaba9aa59c6 Mon Sep 17 00:00:00 2001 From: Abdullah <89297042+AzazelSensei@users.noreply.github.com> Date: Thu, 17 Sep 2026 18:21:56 +0000 Subject: [PATCH 1/3] docs: document Shorebird with long-running Android background processes FAQ and troubleshooting for apps whose foreground service keeps the process alive after a Recents swipe, so a patch never applies. See shorebirdtech/shorebird#2396 --- src/content/docs/code-push/faq.mdx | 23 +++++++++++++++++++ .../docs/code-push/troubleshooting.mdx | 8 +++++++ 2 files changed, 31 insertions(+) diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index bff3460c..d2e642bf 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -545,6 +545,29 @@ push notification. See [Update Strategies](/code-push/update-strategies) for more information about how to configure this behavior. +### How do you use Shorebird with a long-running Android background process? + +Shorebird applies a downloaded patch the next time the process starts, not when +an Activity is recreated. + +A foreground service (for example +[flutter_background_geolocation](https://github.com/transistorsoft/flutter_background_geolocation)) +keeps the process alive after the user swipes the app out of the recent-apps +list. That swipe is not a process restart, so bringing the UI back still runs +the previous Dart code. + +To receive patches while the process stays alive: + +1. Check for and download patches while the process is running with + [package:shorebird_code_push](https://pub.dev/packages/shorebird_code_push). + Default automatic updates only run on process start. +2. Apply the patch with a real process restart: Settings → Apps → Force stop, + stop the foreground service and then swipe the app away, or wait until the + OS kills the process. + +Recreating the Flutter engine without killing the process is not a supported +way to apply a patch. See [Update Strategies](/code-push/update-strategies). + ### What information is sent to Shorebird servers? Although Shorebird connects to the network, it does not send any personally diff --git a/src/content/docs/code-push/troubleshooting.mdx b/src/content/docs/code-push/troubleshooting.mdx index ffa2381b..2af918f7 100644 --- a/src/content/docs/code-push/troubleshooting.mdx +++ b/src/content/docs/code-push/troubleshooting.mdx @@ -98,6 +98,14 @@ Sending patch check request: PatchCheckRequest { Only patches created for this release version will be compatible with your app. +**You swiped the app away on Android but the patch did not apply.** + +If the app runs a foreground service or other long-running background work, +swiping it from the recent-apps list does not kill the process. Shorebird loads +the patch on the next process start. Force-stop the app, or stop the service +first, then relaunch. See +[How do you use Shorebird with a long-running Android background process?](/code-push/faq/#how-do-you-use-shorebird-with-a-long-running-android-background-process). + ## `Your app contains asset changes` warning when creating a patch The `shorebird patch` command will print a warning if it detects changes to From 37a1958008407998915111ca5e3d7e779e50057a Mon Sep 17 00:00:00 2001 From: Abdullah <89297042+AzazelSensei@users.noreply.github.com> Date: Fri, 18 Sep 2026 09:33:45 +0000 Subject: [PATCH 2/3] docs: address review on Android background process FAQ Use restartRequired and readNextPatch to detect a staged patch, keep Force stop as a testing note, phrase the troubleshooting item as a cause, and say process restart in When do updates happen. --- src/content/docs/code-push/faq.mdx | 22 +++++++++++++------ .../docs/code-push/troubleshooting.mdx | 11 +++++++--- 2 files changed, 23 insertions(+), 10 deletions(-) diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index d2e642bf..95cb124e 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -535,7 +535,9 @@ in `--target-platform` is skipped, not treated as an error. See By default, the Shorebird updater checks for updates on app startup. It runs on a background thread and does not block the UI thread. Any updates will be installed while the user is using the app and will be applied the next time the -app is restarted. +process restarts. See +[How do you use Shorebird with a long-running Android background process?](#how-do-you-use-shorebird-with-a-long-running-android-background-process) +if a background process keeps the app alive. It is also possible to run the Shorebird updater manually using [package:shorebird_code_push](https://pub.dev/packages/shorebird_code_push), @@ -561,12 +563,18 @@ To receive patches while the process stays alive: 1. Check for and download patches while the process is running with [package:shorebird_code_push](https://pub.dev/packages/shorebird_code_push). Default automatic updates only run on process start. -2. Apply the patch with a real process restart: Settings → Apps → Force stop, - stop the foreground service and then swipe the app away, or wait until the - OS kills the process. - -Recreating the Flutter engine without killing the process is not a supported -way to apply a patch. See [Update Strategies](/code-push/update-strategies). +2. Detect the staged patch. `checkForUpdate()` returns + `UpdateStatus.restartRequired` once a patch is downloaded and waiting, and + `readNextPatch()` returns it. Use that to prompt the user to restart at a + point that suits your app. +3. Apply the patch with a real process restart. Stopping the foreground service + and then swiping the app away is enough, as is waiting until the OS kills the + process. + +While testing, you can force a restart with **Settings → Apps → Force stop**. + +Recreating the Flutter engine without killing the process is not a supported way +to apply a patch. See [Update Strategies](/code-push/update-strategies). ### What information is sent to Shorebird servers? diff --git a/src/content/docs/code-push/troubleshooting.mdx b/src/content/docs/code-push/troubleshooting.mdx index 2af918f7..a67ee7dc 100644 --- a/src/content/docs/code-push/troubleshooting.mdx +++ b/src/content/docs/code-push/troubleshooting.mdx @@ -98,12 +98,17 @@ Sending patch check request: PatchCheckRequest { Only patches created for this release version will be compatible with your app. -**You swiped the app away on Android but the patch did not apply.** +**The app's process is still running because of a foreground service.** If the app runs a foreground service or other long-running background work, swiping it from the recent-apps list does not kill the process. Shorebird loads -the patch on the next process start. Force-stop the app, or stop the service -first, then relaunch. See +the patch on the next process start. + +A patch check request in the logs with `Shorebird updater: no active patch` +after a swipe-away, plus `adb shell ps | grep ` still showing the +process, is how you tell. + +Force-stop the app, or stop the service first, then relaunch. See [How do you use Shorebird with a long-running Android background process?](/code-push/faq/#how-do-you-use-shorebird-with-a-long-running-android-background-process). ## `Your app contains asset changes` warning when creating a patch From 305e56061b86fb90419ae06a11f2bb2a6b46a960 Mon Sep 17 00:00:00 2001 From: Abdullah <89297042+AzazelSensei@users.noreply.github.com> Date: Fri, 18 Sep 2026 10:08:03 +0000 Subject: [PATCH 3/3] docs: fix background-process how-to-tell diagnostic Use pidof and restartRequired/readNextPatch so the check is not the same log line as the version-mismatch cause, and so it works on modern Android. --- src/content/docs/code-push/troubleshooting.mdx | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/content/docs/code-push/troubleshooting.mdx b/src/content/docs/code-push/troubleshooting.mdx index a67ee7dc..d77ebe4e 100644 --- a/src/content/docs/code-push/troubleshooting.mdx +++ b/src/content/docs/code-push/troubleshooting.mdx @@ -104,9 +104,17 @@ If the app runs a foreground service or other long-running background work, swiping it from the recent-apps list does not kill the process. Shorebird loads the patch on the next process start. -A patch check request in the logs with `Shorebird updater: no active patch` -after a swipe-away, plus `adb shell ps | grep ` still showing the -process, is how you tell. +**How to tell if this is the problem** + +The process ID does not change when you swipe the app away. Run +`adb shell pidof ` before and after swiping: if it prints the +same PID both times, the process never died and no patch will be applied. + +From Dart, the equivalent signal is `checkForUpdate()` returning +`UpdateStatus.restartRequired`, or `readNextPatch()` reporting a higher patch +number than `readCurrentPatch()`. + +**How to fix it** Force-stop the app, or stop the service first, then relaunch. See [How do you use Shorebird with a long-running Android background process?](/code-push/faq/#how-do-you-use-shorebird-with-a-long-running-android-background-process).