Known Compatibility Issues and Workarounds

Custom OS’s ignoring process affinity - Aggressive App Closures

We have identified that the Custom OS layers that some manufacturers build on top of Android do not respect Android’s specified behavior for closing apps when many apps are in use, which can result in CommCare being closed in the background unexpectedly.

On devices with this behavior, users who navigate away from CommCare in their app OS may return later to CommCare and find their session (including any forms currently being entered) gone, and the app expecting a fresh login.

Presentation and Impact

This issue can arise on devices from some manufacturers (see below) with limited RAM when users are performing a significant amount of switching between multiple applications which consume a lot of memory before returning to CommCare.

In scenarios where users are not frequently exiting CommCare during form entry, this is unlikely to cause major issues other than requiring somewhat more frequent logins. However if users' workflows require them to exit CommCare during form entry to perform other tasks with large apps before returning to form entry on affected devices it can result in losing the form entry session unless a workaround is enabled (see below).

One other potential impact of this issue outside of issues with form session retention is that background tasks requiring a seated application (like auto-syncs, or automatic app updates) may be blocked, resulting in slower uptake of new app versions or delayed form submissions.

Known Affected Devices

We have performed proactive testing on phones from different manufacturers to provide guidance on how to anticipate and manage this issue.

Since the underlying issues we’ve identified are specific to manufactures and OS versions, these recommendations can’t be comprehensive. Devices from an affected manufacturer could work better than expected, and newer devices from currently not-affected manufacturers could begin exhibiting new problems, but we’ve provided the outcomes from our testing here to help out partners make the best possible decisions.

Thus far we have only identified this issue on devices from brands which are owned by one company (Transsion Holdings), all of which appear to share a common custom tweak to the underlying OS. If your use cases for CommCare rely on the presenting scenarios outlined triggering above (required concurrent usage of multiple non-CommCare apps during form entry), we strongly recommend avoiding these devices.

We have been able to also test a number of manufacturer’s devices to confirm that they are safe from the issue as we understand it.

We will continue to expand these recommendations as we complete testing on more devices. If you believe a device may be experiencing this issue (or want to confirm whether it may), and have access to technical resources, we have also provided instructions below on how to independently confirm so.

Managing background app closures

If a device is frequently closing CommCare in the background as a result of this issue, there are steps you can take to mitigate the impact of the OS app closures on users of the mobile app.

Graceful Session Recovery

This feature is available as a part of CommCare version 2.54.1

The Session Recovery feature will instruct CommCare to auto-save your form entry progress any time the app is dismissed from the foreground of the user’s attention, and checks whether a pending form was autosaved for recovery on startup. This allows users to pick up their form entry where they left off after login, even if CommCare was killed by the device OS in between. Please follow the below steps to enable the feature:

Open

Open

Configuring the Custom Property

Use Device Features to Keep CommCare Open Preferentially

Some devices come with a features on the “Recents” screen (the background screen that lets you switch apps) that lets you manually instruct the OS you do not want it to force-close the app. On the Recents screen (with CommCare recently open), find CommCare and tap the lock icon in the top right corner to make it go from unlocked to locked. This may reduce the rate of forced closes CommCare experiences from the OS.

Some example lock icons are shown below:

Example 1:

Example 2:

Technical overview and identifying the issue from behavior

Under the hood, this issue arises from manufacturers customizing how the Android OS manages running apps. On these devices CommCare’s process can be killed to recover memory in a non-critical state in spite of a registered Foreground Service, counter to the specified Android OS expectations.

You can attempt to trigger the issue on a device with the following rough process, which puts moderate pressure on the device’s memory in an attempt to provoke a force-close of CommCare. If it does result in a force close, this is a good indication that the device has an aggressive application closing process.

1. Open CommCare on the device and fill in a form, ideally with multimedia questions or signature questions. Leave the form filled but unsubmitted, and navigate away from CommCare.

2. You should notice a persistent notification at the top of the screen which indicates that CommCare is running in the background.

3. Open additional applications one by one and do not close them. For instance, open Google Sheets then navigate away without closing. Open Slack, then navigate away without closing. Open the web browser, navigate to various websites, and navigate away without closing. Repeat this process for 5+ large applications.

4. As you do this, continue to monitor the persistent notification at the top of the screen. As the phone continues to load more and more applications in the background, CommCare should remain open.

5. However, if at a certain point you see that the notification is gone, that means CommCare has been forced closed, and the device likely has an aggressive application closing process.

6. If you pull down the notification bar, and this issue has triggered you should see no notifications from CommCare, including a persistent notification about your login or a notification that the user was logged out.

7. As you navigate back to CommCare after the issue has triggered, you will be directed to the login screen.

Identification by specific process name

Below is a list of known processes to look out for and avoid: