- Doze provides a recurring maintenance window for apps to use the network - and handle pending activities. + Figure 1. Doze provides a recurring maintenance window for apps to use the + network and handle pending activities.
Starting from Android 6.0 (API level 23), Android introduces two power-saving features that extend battery life for users by managing how apps behave when a - device is not plugged into a power source. Doze reduces power consumption by deferring - background - CPU and network activity for apps when the device is unused for long periods + device is not connected to a power source. Doze reduces battery consumption by deferring + background CPU and network activity for apps when the device is unused for long periods of time. App Standby defers background network activity for apps - that are not recently used. + with which the user has not recently interacted.
@@ -58,23 +58,23 @@ next.link=battery-monitoring.html
If a user leaves a device unplugged and stationary for a period of time, with the screen off, the device enters Doze mode. In Doze mode, the system - attempts to conserve battery by restricting apps ‘ access to network and - CPU-intensive services. It prevents apps from accessing the network and + attempts to conserve battery by restricting apps' access to network and + CPU-intensive services. It also prevents apps from accessing the network and defers their jobs, syncs, and standard alarms.
Periodically, the system exits Doze for a brief time to let apps complete their deferred activities. During this maintenance window, the - system runs all pending syncs, jobs, and alarms and lets apps access the + system runs all pending syncs, jobs, and alarms, and lets apps access the network.
- Doze provides a recurring maintenance window for apps to use the network - and handle pending activities. + Figure 1. Doze provides a recurring maintenance window for apps to use the + network and handle pending activities.
- To assess your app in Doze, you can use adb commands to force the system to - enter and exit Doze and observe your app’s behavior. See Testing with Doze for details. -
+Doze can affect apps differently, depending on the capabilities they offer - and the services they use. Many apps will function normally across Doze - cycles without modification. In some cases, you will need to optimize the way + and the services they use. Many apps function normally across Doze + cycles without modification. In some cases, you must optimize the way that your app manages network, alarms, jobs, and syncs. Apps should be able to efficiently manage activities during each maintenance window.
- In particular, activities managed by AlarmManager alarms and timers may be - affected, since legacy alarms (API level 22 and lower) do not fire when the - system is in Doze. + Doze is particularly likely to affect activities that {@link android.app.AlarmManager} alarms and + timers manage, because alarms in Android 5.1 (API level 22) or lower do not fire when the system + is in Doze.
- To help with scheduling alarms, Android 6.0 Marshmallow introduces two new - AlarmManager methods — {@link + To help with scheduling alarms, Android 6.0 (API level 23) introduces two new + {@link android.app.AlarmManager} methods: {@link android.app.AlarmManager#setAndAllowWhileIdle(int, long, android.app.PendingIntent) setAndAllowWhileIdle()} and {@link android.app.AlarmManager#setExactAndAllowWhileIdle(int, long, android.app.PendingIntent) setExactAndAllowWhileIdle()}. With these methods, - you can set alarms that will fire even if the device is Doze. + you can set alarms that will fire even if the device is in Doze.
-Keep in mind these characteristics of alarm frequency, however:
+The system places certain restrictions on alarm frequency:
- Google Cloud - Messaging (GCM) is a cloud-to-device service that lets you support - real-time downstream messaging between backend services and apps on - Android devices. GCM provides a single persistent connection to the cloud - that can be shared among all apps needing real-time messaging. This shared - connection significantly optimizes battery by making it unnecessary for - multiple apps to each maintain a separate persistent connection, which can - deplete the battery rapidly. + receive messages, you should use Google Cloud Messaging(GCM) + if possible.
- If your app requires messaging integration with a backend service, it’s highly - recommended that you use GCM if possible, rather than - maintaining your own persistent network connection. Also, GCM is optimized to - work with Doze and App Standby idle modes by means of - high-priority GCM messages. -
- -- GCM high-priority messages let you reliably wake your app to access the - network, even if the user’s device is in Doze or the app is in App Standby. - In Doze or App Standby, the system delivers the message and gives the - app temporary access to network services and partial wakelocks, then returns - to idle state. -
- -- High-priority GCM messages don’t wake the device from Doze and they don’t - affect the state of any other app, This means that you can use them to - efficiently communicate with your app while minimizing battery impacts across - the system and device. -
- -- As a general best practice, if your app requires downstream messaging, you - should use GCM. If you are already using GCM, make sure that you use - high-priority messages to for critical messages, since this will reliably - wake apps even when the device is in Doze. + To confirm that your app behaves as expected with Doze, you can use adb commands to force the + system to enter and exit Doze and observe your app’s behavior. For details, see + Testing with Doze and App Standby.
- Almost all apps should be able to support Doze and App Standby by managing - network, alarms, jobs, and syncs properly and using GCM high-priority - messages. For a narrow set of use cases, this might not be sufficient. - For those, the system provides a configurable whitelist of apps that are - partially exempt from Doze and App Standby optimizations. + Google Cloud + Messaging (GCM) is a cloud-to-device service that lets you support + real-time downstream messaging between backend services and apps on + Android devices. GCM provides a single, persistent connection to the cloud; all apps needing + real-time messaging can share this connection. This shared + connection significantly optimizes battery consumption by making it unnecessary for + multiple apps to maintain their own, separate persistent connections, which can + deplete the battery rapidly. For this reason, if your app requires messaging integration with a + backend service, we strongly recommend that you use GCM if possible, rather than + maintaining your own persistent network connection.
- An app that is whitelisted can use the network and hold {@link - android.os.PowerManager#PARTIAL_WAKE_LOCK partial wake locks} during Doze and + GCM is optimized to work with Doze and App Standby idle modes by means of + + high-priority GCM messages. GCM high-priority messages let you reliably wake your app to + access the network, even if the user’s device is in Doze or the app is in App Standby mode. + In Doze or App Standby mode, the system delivers the message and gives the + app temporary access to network services and partial wakelocks, then returns the device or app + to idle state. +
+ ++ High-priority GCM messages do not otherwise affect Doze mode, and they don’t + affect the state of any other app, This means that your app can use them to communicate + efficiently while minimizing battery impacts across the system and device. +
+ ++ As a general best practice, if your app requires downstream messaging, it + should use GCM. If your server and client already uses GCM, make sure that your service uses + high-priority messages for critical messages, since this will reliably + wake apps even when the device is in Doze. +
+ ++ Almost all apps should be able to support Doze by managing network connectivity, alarms, + jobs, and syncs properly, and using GCM high-priority messages. For a narrow + set of use cases, this might not be sufficient. For such cases, the system + provides a configurable whitelist of apps that are partially + exempt from Doze and App Standby optimizations. +
+ ++ An app that is whitelisted can use the network and hold + + + partial wake locks during Doze and App Standby. However, other restrictions still apply to the whitelisted app, just as they do to other apps. For example, the whitelisted - app’s jobs and syncs are deferred and its regular AlarmManager alarms do not - fire. + app’s jobs and syncs are deferred, and its regular {@link android.app.AlarmManager} alarms do not + fire. An app can check whether it is currently on the exemption whitelist by + calling {@link + android.os.PowerManager#isIgnoringBatteryOptimizations(java.lang.String) + isIgnoringBatteryOptimizations()}. +
Users can manually configure the whitelist in Settings > Battery > Battery Optimization. Alternatively, the system provides ways for apps to ask users to whitelist them. +
- Before asking the user to add your app to the whitelist, make sure the - app meets the acceptable use-cases for whitelisting listed below. -
+Before asking the user to add your app to the whitelist, make sure the app + +matches the acceptable use cases for whitelisting.
@@ -370,13 +368,12 @@ next.link=battery-monitoring.html
To ensure a great experience for your users, you should test your app fully - in Doze and Standby. + in Doze and App Standby.
-You can test your app in Doze by following these steps:
+You can test Doze mode by following these steps:
$ adb shell dumpsys battery unplug $ adb shell dumpsys deviceidle step $ adb shell dumpsys deviceidle -h-
To test the App Standby mode with your app:
@@ -421,8 +417,6 @@ $ adb shell am set-inactive <packageName> true$ adb shell am set-inactive <packageName> false $ adb shell am get-inactive <packageName>-
The table below highlights the acceptable use-cases for requesting or being on - the Battery Optimizations exceptions whitelist. For more information, see - Other supported use cases.
+The table below highlights the acceptable use cases for requesting or being on + the Battery Optimizations exceptions whitelist. In general, your app should not be on the + whitelist unless Doze and App Standby break the core function of the app, and there is a + technical reason why your app cannot use GCM high-priority messages.
-In general, your app should not be on the whitelist Doze and - App Standby break the core function of the app and you cannot use GCM high-priority - messages because of a technical reason.
+For more information, see Support for Other Use Cases + .
| Use {@link android.app.AlarmManager} and {@link android.app.job.JobScheduler} APIs to optmize notifications, sync, etc. |