Skip to main content

Best practices

Always try to schedule BackgroundSync​

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

void main() {
  // Ensure that the plugin is ready
  WidgetsFlutterBinding.ensureInitialized();

  if (Platform.isAndroid) {
    enableAndroidBackgroundSync();
  } else {
    enableIOSBackgroundSync();
  }

  runApp(App());
}

void enableAndroidBackgroundSync() async {
  try {
    final userAllowedBackgroundSync = await AppPreferences().getUserAllowedBackgroundSync();

    if (userAllowedBackgroundSync) {
      await HCRookBackgroundSync.enableBackground(enableNativeLogs: isDebug);
    }
  } catch (error) {
    // Log
  }
}

void enableIOSBackgroundSync() async {
  // Go to IOS documentation to learn how to enable background sync
}

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.