fix(push): report restricted background usage as best effort

[abnegate]

Summary

When the user sets an Android app's battery usage to Restricted, Android may hold its alarms, jobs and foreground service while it is closed, so pushes wait until the app is opened. backgroundStatus() didn't see this and reported bestEffort=false. It now reports backgroundRestricted (native Android, React Native bridge, Flutter channel), and bestEffort accounts for it.

@ArnabChatterjee20k could you review?

Root cause

backgroundStatus() only looked at exact alarms, battery-optimisation exemption and foreground mode. It never checked ActivityManager.isBackgroundRestricted() (the RUN_ANY_IN_BACKGROUND app-op).

Repro (device testing)

Found while running the Android device scenarios, plus new edge cases, on Android emulators (native Android and React Native SDKs) against a real Appwrite main instance:

1. adb shell appops set <pkg> RUN_ANY_IN_BACKGROUND ignore (Settings > Apps > app > Battery > Restricted), and remove the battery exemption.
2. Close the app and send pushes: nothing arrives until the app is opened.
3. backgroundStatus() reported exact=true battery=false bestEffort=false on both SDKs.

Fix

• PushBackgroundStatus.backgroundRestricted is isBackgroundRestricted() on Android 9+ and false below. It is appended last with a false default, and the constructor is @JvmOverloads for Java callers.
• The bridge JSON key is "backgroundRestricted". It is also in the React Native PushBackgroundStatus type and the Flutter model (fromMap treats a missing key as false).
• bestEffort is true when the app is restricted and not battery-exempt, and foreground mode stops counting while the app is restricted:
  • AOSP AppStateTrackerImpl runs alarms and jobs of power-allowlisted apps before checking the app-op, and requestIgnoreBatteryOptimizations allowlists the app without resetting the op, so the exemption lifts the hold on wake-ups.
  • AOSP ActiveServices stops a restricted app's foreground service once it leaves the screen, exempt or not.
  • So a restricted, exempt app's bestEffort follows exact alarms alone.
• The READMEs and API docs (Android, React Native, Flutter) tell apps to ask the user to choose Unrestricted in the app's battery settings, or to request the exemption.

Tests

• Android Tests.kt: new Push background restricted line (the lanes run at API 23, so it checks the guard), and PushBackgroundRestrictedTest at sdk = P covering restricted, exempt and foreground-mode cases against an unrestricted baseline. Fails on main (compile) and with a getter that ignores the exemption or foreground mode.
• React Native android-test: PushBridgeBackgroundStatusTest checks the bridge JSON key and bestEffort. Fails on main.
• Flutter: new test/src/push_background_status_test.dart (parsing and defaults). Fails on main.
• React Native push.node.js also asserts the field; that line is coverage only, since the mock passes the JSON through.

Notes

• The React Native TS field is required (the native code ships in the same package); Kotlin and Dart default it to false. Worth a changelog line.
• The local Docker lanes were limited by host resources: Android16Java17 and ReactNativeAndroid passed before the last bestEffort refinement; host Robolectric and Flutter cover the final head. CI is the gate.
• Not yet confirmed on a device: Restricted → requestIgnoreBatteryOptimizations → Allow → close the app → push (expect delivery through the scheduled wake-ups).
• Follow-up: optionally a helper that opens the app's battery settings.

🤖 Generated with Claude Code

[hansi-codes]

🟢 Tier S · Ready to merge

This change adds Android background-restriction reporting to the push status API and includes it in the bestEffort calculation. It exposes the field through the Android bridge, React Native and Flutter, and updates the SDK guidance and tests.

Verdict	New comments	Fixed	Still open
✅ Approved	0	0	0

📂 Walkthrough · 15

File	Change
src/SDK/Language/Flutter.php	Registers the Flutter background-status test template.
templates/android/README.md.twig	Documents restricted background usage and its effect on delivery.
templates/android/library/src/main/java/io/package/services/Push.kt.twig	Updates the Android API documentation for the new status field.
templates/android/library/src/main/java/io/package/services/PushBackground.kt.twig	Reads Android's background-restricted state on API 28 and later.
templates/android/library/src/main/java/io/package/services/PushBridge.kt.twig	Adds backgroundRestricted to the bridge status JSON.
templates/android/library/src/main/java/io/package/services/PushCore.kt.twig	Adds the status field and accounts for restriction and battery exemption in bestEffort.
templates/flutter/README.md.twig	Documents restricted background usage and its effect on delivery.
templates/flutter/lib/src/mqtt.dart.twig	Adds the field to the Flutter model and parses it with a false default.
templates/flutter/test/src/push_background_status_test.dart.twig	Tests Flutter parsing and default behavior for the new field.
templates/react-native/README.md.twig	Documents restricted background usage and demonstrates handling it.
templates/react-native/src/services/push.ts.twig	Adds the field to the React Native status type and API documentation.
tests/e2e/Base.php	Adds the restricted-background scenario to Android expected responses.
tests/e2e/languages/android/Tests.kt	Tests status reporting and bestEffort for restricted usage.
tests/e2e/languages/react-native/android-test/Tests.kt	Tests restriction reporting through the React Native Android bridge.
tests/e2e/languages/react-native/push.node.js	Asserts that the React Native status includes the new field.

---

_{Merged main (512edea); no changes to this PR's code since b25c935 · Details · Comment @hansi-codes review to re-run, or mention @hansi-codes with a question.}

[hansi-codes]

🟢 Tier S · Looks good to merge. Summary

[ArnabChatterjee20k]

Reviewed. backgroundRestricted comes from isBackgroundRestricted() on Android 9+. Restricted without the battery exemption reports best effort; with the exemption it follows exact alarms, and foreground mode no longer counts. Unrestricted is unchanged. It stays backward compatible (a false default, @JvmOverloads, the Flutter parser defaulting a missing key). The React Native field being required is worth a changelog line.