Background Restrictions

Android devices can restrict your app while it's in the background to preserve battery life. This can prevent trigger notifications from being displayed.

There are numerous factors that can cause your app to be killed which varies between device manufacturers and android versions (see dontkillmyapp.com).

Notify Kit provides a set of helper endpoints to exempt your app from these restrictions.

It's important to note that these endpoints should be used wisely; if your notifications can be deferred, it's recommended to keep the default battery optimization and power settings.

Battery Optimization

On newer Android devices, apps can, by default, have Battery Optimization enabled which makes them susceptible to these power restrictions. It is possible for the user to disable this feature for your app.

On Android devices using 6.0 or higher (API level 23) there are two methods to help achieve this, isBatteryOptimizationEnabled and openBatteryOptimizationSettings.

Below is a snippet on how to use these methods:

// 1. checks if battery optimization is enabled
const batteryOptimizationEnabled = await notifee.isBatteryOptimizationEnabled();
if (batteryOptimizationEnabled) {
  // 2. ask your users to disable the feature
  Alert.alert(
    'Restrictions Detected',
    'To ensure notifications are delivered, please disable battery optimization for the app.',
    [
      // 3. launch intent to navigate the user to the appropriate screen
      {
        text: 'OK, open settings',
        onPress: async () => await notifee.openBatteryOptimizationSettings(),
      },
      {
        text: 'Cancel',
        onPress: () => console.log('Cancel Pressed'),
        style: 'cancel',
      },
    ],
    { cancelable: false },
  );
}

Power Manager

Depending on the device, there will be a series of steps the user can take to avoid your app being killed.

Call getPowerManagerInfo() to retrieve best-effort information on the device and its power management configuration. An instance of PowerManagerInfo will be returned with an activity property when Notify Kit has a known vendor-settings candidate for the current manufacturer. This is not a guarantee that the activity is installed or accessible on the current device firmware.

For google devices, such as Pixel 2a, activity will be null. For these devices there's not much else the user can do other than turning off battery optimizations.

On Android 11 and higher, Notify Kit avoids package-visibility discovery for these helpers. Consumer apps do not need to add <queries> to their manifest just to use getPowerManagerInfo() or openPowerManagerSettings(). openPowerManagerSettings() tries known vendor settings candidates best-effort and fails safely if a vendor changes, removes, or blocks a settings activity. The vendor-settings helper does not use the direct ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS request path.

Below is a snippet on how to use these methods:

// 1. get info on the device and the Power Manager settings
const powerManagerInfo = await notifee.getPowerManagerInfo();
if (powerManagerInfo.activity) {
  // 2. ask your users to adjust their settings
  Alert.alert(
    'Restrictions Detected',
    'To ensure notifications are delivered, please adjust your settings to prevent the app from being killed',
    [
      // 3. try to open the vendor settings screen
      {
        text: 'OK, open settings',
        onPress: async () => await notifee.openPowerManagerSettings(),
      },
      {
        text: 'Cancel',
        onPress: () => console.log('Cancel Pressed'),
        style: 'cancel',
      },
    ],
    { cancelable: false },
  );
}

Known manufacturers and their possible settings screen candidates:

Samsung Devices

Samsung devices have their own custom Power Manager called 'Device Care'. For example, on many Samsung devices running Android 10, openPowerManagerSettings() can open the Battery menu of Device Care. You could ask your users to tap 'App power management', and then tap 'Apps that won't be put to sleep', and add your app to the list.

Testing

It's possible to test your app under a variety of conditions to see how your notifications behave with several adb commands. For example, run adb shell settings put global low_power 1 to test your app while the device/emulator has low power.