Skip to content

Add android.noNotification for silent uploads - #28

Merged
elliottkember merged 1 commit into
masterfrom
elliott/optional-upload-notification
Aug 13, 2026
Merged

Add android.noNotification for silent uploads#28
elliottkember merged 1 commit into
masterfrom
elliott/optional-upload-notification

Conversation

@elliottkember

@elliottkember elliottkember commented Aug 12, 2026

Copy link
Copy Markdown

Adds an Android option: android: { noNotification: true }. The file uploads, and no progress notification appears.

Why

Today every upload shows a notification and there is no way to turn it off. The notification is what puts the upload worker in foreground mode, so the worker always posts one.

That hurts an app that uploads two kinds of file: big ones the user is waiting for, and small ones they never asked about. The OpenSpace app has this problem. A field note syncs when the app opens, and the phone says "Uploading Captures…" when no capture is uploading.

The catch

A silent upload cannot use foreground mode, because foreground mode is what needs the notification. It runs as a normal background worker instead, so Android can delay it, or stop it and run it again later.

Nothing breaks when that happens. The library already treats a stop by Android as "still in flight" and lets WorkManager retry, so the app never sees a false failure. But it does mean you should only use this for small files. Anything that takes a while to upload should keep its notification. The option's doc comment, the README and the changelog all say so.

Why it is an opt-out and not showNotification

WorkManager saves each upload as JSON, so an upload queued by 8.0.0 can run under 8.1.0 after an app update. That old JSON has no key for the new option, and Gson reads a missing boolean as false. With noNotification, false means "show the notification", so an old upload behaves as it did before. With showNotification it would have gone silent by accident, and lost foreground mode with it. There is a test for this.

The worker reads upload.showsNotification, so the double negative stops at the data class.

One more thing

Progress is still added up across all uploads, silent ones included. A visible notification's progress bar covers everything the device is uploading. That is unchanged.

Testing

All green locally: yarn typecheck, yarn lint:ci (0 errors, plus 3 warnings that were already there in the example app), yarn test (7 tests), and ./gradlew :react-native-background-upload:testDebugUnitTest. Three of the Kotlin tests are new and cover the option's default and its JSON round trip.

I have not run this on a phone or an emulator, so nobody has watched a silent upload happen. Worth checking:

  1. Upload with android: { noNotification: true }. There should be no notification, but progress events should still arrive, then completed.
  2. Upload without the flag at the same time. The normal notification should appear, and its percentage should move for both uploads.
  3. Send the app to the background during a silent upload. It should still finish.

A consumer whose queue carries both user-visible media and housekeeping
payloads had no way to keep the housekeeping ones out of the notification
shade: every upload posts a progress notification, because posting one is
how the worker enters foreground mode.

noNotification skips the channel registration, the foreground promotion and
the notify calls. Such an upload runs as an ordinary background worker, so
the OS may defer or stop it — a path the worker already handles by letting
WorkManager re-run it.

Phrased as an opt-out because WorkManager persists the upload as JSON: a job
enqueued by 8.0.0 and replayed by 8.1.0 has no such key, and an absent Gson
Boolean is false, so it keeps its notification.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@elliottkember
elliottkember marked this pull request as ready for review August 12, 2026 05:51
@elliottkember
elliottkember requested review from arnonate, dhruv-dangi-openspace and dmurphy5 and a lite review from Copilot and removed request for Copilot August 12, 2026 07:12

@arnonate arnonate left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good

@elliottkember
elliottkember merged commit e3641cc into master Aug 13, 2026
2 checks passed
@elliottkember
elliottkember deleted the elliott/optional-upload-notification branch August 13, 2026 01:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants