Skip to main content

Best practices

Android and Health Connect Data sources​

You should think of Android Steps and Health Connect as 2 different data sources, the recommended approach is checking for Health Connect background availability if is available show the Health Connect connection button which will redirect the user to the Health Connect permissions screen. Then check for Android steps availability if is available show the Android connection button which will ask for android permissions.

Using this approach you can guarantee that the user will only see the connections options that their device currently supports.

Health Connect permissions screen​

Instead of just asking permissions when the user clicks on the Connection button for Health Connect we recommend to take the user to a new screen where you can explain what permissions will be asked and why you need them, the Health Connect official documentation has a UI guidelines section with examples you can use in this screen.

info

Our official Extraction app uses the Home Screen Promo Card Flow to ask permissions.

Prefer Custom Tabs over webview​

When building your own connections page inside your app you will need to take the user to the selected provider web page so they can log in and give read permissions, usually a web view may be sufficient however some providers web pages like Polar may not be displayed correctly or even be functional with a web view, for this we recommend to replace your entire web view flow with Chrome's Custom Tabs and using an App Link as a redirectUrl so the user is redirected to your app when the web based part of the flow finishes.

You can get started with Custom Tabs in the official documentation.

You can read more about App links in the official documentation

Always try to schedule BackgroundSync​

When a user allows the background read permissions you should immediately call RookBackgroundSyncManager.schedule however you should also save the user's acceptance in preferences, this will allow you to also call RookBackgroundSyncManager.schedule while the app is being launched:

class MyAplication : Application() {
    override fun onCreate() {
        super.onCreate()

        if (userAllowedBackgroundSync) {
            RookBackgroundSyncManager.schedule(this, enableLogs = isDebug)
        }
    }
}

This will allow to re-schedule the background sync in case that the system kill the process.

Prepare for strict battery scenarios​

Some users want to have as much battery life as possible, so they have power saving mode always active, also some phone manufactures add their own energy restriction on top of Android's, these restrictions are mostly enabled by default and depending on the device will add a delay to background sync or even stopping it completely.

Battery Optimizations​

There are 2 ways you can ask the user to disable battery optimizations:

  1. Use the ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS intent to show the battery optimization settings screen to your users, because every Android Skin is different you will need to create instructions for every phone manufacturer.
  2. A more straightforward approach would be using the ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS intent which displays a dialog with "Allow/Deny" options, however you will need to justify in the Play Console why is ignoring battery optimizations so important for your app.

Widgets​

When a widget is active, the Android system grants your app a slightly higher priority for resource usage. This widget can be used to allow users to see a summary of their health data; latest sleep details, yesterday's physical/body summary.

You can use the widget’s update interval to trigger data refreshes via Background Sync scheduling or a manual Sync as often as every 30 minutes (see updatePeriodMillis Android docs).

Push Notifications​

Use Firebase Cloud Messaging (FCM) or a similar provider to send a push notification to the device and schedule an automatic sync with BackgroundSync or initiate a manual sync.

tip

High priority FCM messages can wake an app even if it is in Doze mode.

Brand specific settings​

Even when following official Android guidelines, certain device manufacturers have custom battery management software that can be more restrictive than the "original" Android system.

Requesting that users manually adjust system level battery settings should be considered a last resort as this requires a lot of user effort. We only recommend requesting this for power users or in cases where the SDK has been unable to sync for an extended period (your backed service is not receiving any data or logs).

If you choose to implement user instructions, dontkillmyapp is a good resource to provides the necessary steps for users to whitelist an application or for helping in the design of a custom showcase based on the device manufacturer to lessen the friction caused to the user by navigating in the system settings.