Known Compatibility Issues and Workarounds

This page outlines known compatibility issues that our team is aware of with certain devices or configurations in running CommCare’s Android client or its features. The list provided here is not exhaustive and will be continually updated as we learn more about potential challenges and ways to address them.


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.

Tested devices with known symptoms

Devices with unconfirmed risk of the issue

Tested devices with known symptoms

Devices with unconfirmed risk of the issue

Infinix

Itel

Tecno

Spice

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.

Devices tested to be clear of the problem

Devices tested to be clear of the problem

Samsung

Pixel

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:

Enabling or Disabling this feature on a single device: To enable this feature on a specific device, you can activate the “Auto Save Form on Pause” setting

Enabling the feature for all users of an app:

An app builder can also configure this setting to be enabled for all users of a CommCare App by setting a Custom Property in the application’s Advanced Settings. After configuring this Custom Property, it will be included and deployed with any future App Updates for that app, as with the other Advanced Settings.

Navigate to the Advanced App Settings for your application

Scroll to the bottom of the page to locate the Custom Properties section, and add a new property (contact Dimagi if you don’t see a Custom Properties section in your App’s Advanced Settings menu)

Set the key for the custom property to cc-auto-form-save-on-pause and the value of the custom property to yes

Don’t forget to Save the settings page after you’ve added the Custom Property, then and proceed to Build and Release the application to make it available to users

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

This section requires using advanced developer options and some familiarity with software developer tools. For a more broadly accessible identification method, see Identification by symptom.

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

Process Name

How to test for this process

Known devices where this has been identified

Process Name

How to test for this process

Known devices where this has been identified

Griffin

The most comprehensive way to identify the presence of a process in an Operating System involves accessing system logs and searching by its name. On Android devices, this can be done using a tool called logcat (Logs Catalog), which allows real-time access to system and application logs. The steps below describe how to prepare the device and configure the environment to run that tool.

Prepare device

This step is mainly to allow a communication between the computer and the mobile device for Debugging purposes.

  1. Enable Developer option, follows the steps described here

    1. Depending on the device manufacturer the steps can be slightly different

  2. Enable USB debugging, follow the steps described here

  3. Connect the device to the computer using an USB cable, by doing so a dialog should popup asking permission to do so (see image below)

 

Now that the device is ready, let’s download the necessary tools and run the logcat tool:

  1. Download Android SDK platform tools from here

    1. The actual tool needed here is adb (Android Debug Bridge), which allows the communication between the computer and the mobile device

  2. Unpack the downloaded file and store its content in an easy to access/known folder

  3. Open a terminal and navigate to the folder from number 2

  4. Execute the following command:

    1. Windows

      1. ./adb logcat | findstr Griffin

    2. Linux/Mac

      1. ./adb logcat | grep Griffin

    3. In case the execution fails, try without the ./ in the beginning of the command so adb logcat ...

  5. Once the command is executed and if the process in question is present, a continuous stream of logs will be outputted to the terminal (see image below):

    1. If not present, then nothing will be printed. If unsure whether the setup is working well, execute the command without the filtering:

      1. ./adb logcat

 

Multiple Infinix and Tecno models