Docs: Android 6.0 release updates to Doze/App Standby. Continues b2/ 23725346

    <ol>

      <li><a href="#understand_doze">Understanding Doze</a>

      <ol>

        <li><a href="#restrictions">Doze Restrictions</a></li>

        <li><a href="#assessing_your_app">Assessing Your App</a></li>

        <li><a href="#using_gcm">Using GCM to Interact with Your App</a></li>

        <li><a href="#restrictions">Doze restrictions</a></li>

        <li><a href="#assessing_your_app">Adapting your app to Doze</a></li>

      </ol>

      </li>

      <li><a href="#understand_app_standby">Understanding App Standby</a></li>

      <li><a href="#other_use_cases">Support for Other Use-Cases</a></li>

      <li><a href="#testing_doze_and_app_standby">Testing</a>

      <li><a href="#using_gcm">Using GCM to Interact with Your App</a></li>

      <li><a href="#support_for_other_use_cases">Support for Other Use Cases</a></li>

      <li><a href="#testing_doze_and_app_standby">Testing with Doze and App

Standby</a>

      <ol>

        <li><a href="#testing_your_app_with_doze">With Doze</a></li>

        <li><a href="#testing_your_app_with_app_standby">With App Standby</a></li>

        <li><a href="#testing_doze">Testing your app with Doze</a></li>

        <li><a href="#testing_your_app_with_app_standby">Testing your app with App Standby</a></li>

      </ol>

      </li>

      <li><a href="#appendix">Appendix</a></li>

      <li><a href="#whitelisting-cases">Example Use Cases for Whitelisting</a></li>

    </ol>

  </div>

</div>

<p>

  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. <em>Doze</em> 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. <em>Doze</em> reduces battery consumption by deferring

  background CPU and network activity for apps when the device is unused for long periods

  of time. <em>App Standby</em> defers background network activity for apps

  that are not recently used.

  with which the user has not recently interacted.

</p>

<p>

<p>

  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.

</p>

<p>

  Periodically, the system exits Doze for a brief time to let apps complete

  their deferred activities. During this <em>maintenance window</em>, 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.

</p>

<div style="margin:1em 0em;">

  <img src="{@docRoot}images/training/doze.png">

  <p class="img-caption" style="text-align:center;">

    Doze provides a recurring maintenance window for apps to use the network

    and handle pending activities.

    <strong>Figure 1.</strong> Doze provides a recurring maintenance window for apps to use the

    network and handle pending activities.

  </p>

</div>

  At the conclusion of each maintenance window, the system again enters Doze,

  suspending network access and deferring jobs, syncs, and alarms. Over time,

  the system schedules maintenance windows less and less frequently, helping to

  save battery in cases of longer-term inactivity when the device is not

  reduce battery consumption in cases of longer-term inactivity when the device is not

  connected to a charger.

</p>

</p>

<ul>

  <li>Network access is suspended

  <li>Network access is suspended.

  </li>

  <li>The system ignores {@link android.os.PowerManager.WakeLock Wakelocks}.

  <li>The system ignores <a href="{@docRoot}reference/android/os/PowerManager.WakeLock.html">

  wake locks</a>.

  </li>

  <li>Standard {@link android.app.AlarmManager} alarms (including {@link

  <li style="list-style: none; display: inline">

    <ul>

      <li>If you need to set alarms that fire while in Doze, you can use {@link

      <li>If you need to set alarms that fire while in Doze, use {@link

      android.app.AlarmManager#setAndAllowWhileIdle(int,long,android.app.PendingIntent)

      setAndAllowWhileIdle()}

      or {@link android.app.AlarmManager#setExactAndAllowWhileIdle(int, long,

  <li>The system does not perform Wi-Fi scans.

  </li>

  <li>The system does not allow {@link android.content.AbstractThreadedSyncAdapter sync adapters} to run.

  <li>The system does not allow

  <a href="{@docRoot}reference/android/content/AbstractThreadedSyncAdapter.html">sync adapters</a>

  to run.

  </li>

  <li>The system does not allow {@link android.app.job.JobScheduler} to run.

<ul>

  <li>If possible, use GCM for <a href=

  "https://developers.google.com/cloud-messaging/downstream">downstream

  messaging</a>

  messaging</a>.

  </li>

  <li>If your users must see a notification right away, make sure to use a <a href=

  </li>

  <li>

    <a href="#testing_your_app_with_doze">Test your app in Doze</a>

    <a href="#testing_doze">Test your app in Doze.</a>

  </li>

</ul>

</ol>

</div>

</div>

<h3 id="assessing_your_app">Assessing your app</h3>

<p>

  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 <a

  href="#testing_your_app_with_doze">Testing with Doze</a> for details.

</p>

<h3 id="assessing_your_app">Adapting your app to Doze</h3>

<p>

  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.

</p>

<p>

  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.

</p>

<p>

  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.

</p>

<p>Keep in mind these characteristics of alarm frequency, however: </p>

<p>The system places certain restrictions on alarm frequency:</p>

<ul>

  <li>The system restricts {@link

  <li>The {@link

  android.app.AlarmManager#setExactAndAllowWhileIdle(int, long,

  android.app.PendingIntent) setExactAndAllowWhileIdle()} alarms to firing at most once per 10 seconds per

  app while in Doze, and at most once per 5 seconds otherwise.

  android.app.PendingIntent) setExactAndAllowWhileIdle()} method can fire alarms no more than once

  per 10 seconds per app while in Doze. When not in Doze mode, the system can fire alarms no more

  than once per 5 seconds per app.

  </li>

  <li>The system restricts {@link

  <li>The {@link

  android.app.AlarmManager#setAndAllowWhileIdle(int, long,

  android.app.PendingIntent) setAndAllowWhileIdle()} alarms to firing at most once per 15 minutes per

  app while in Doze.

  android.app.PendingIntent) setAndAllowWhileIdle()} method can fire alarms no more than once per

  15 minutes per app while in Doze.

  </li>

</ul>

  The Doze restriction on network access is also likely to affect your app,

  especially if the app relies on real-time messages such as tickles or

  notifications. If your app requires a persistent connection to the network to

  receive messages, you should use Google Cloud Messaging (GCM) if possible,

  <a href="#using_gcm">as described below</a>.

  receive messages, you should use <a href="#using_gcm">Google Cloud Messaging(GCM)</a>

  if possible.

</p>

<h3 id="using_gcm">Using GCM to interact with app while the device is idle</h3>

<p>

  <a href="https://developers.google.com/cloud-messaging/">Google Cloud

  Messaging (GCM)</a> 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.

</p>

<p>

  If your app requires messaging integration with a backend service, it’s highly

  recommended that you <strong>use GCM if possible</strong>, rather than

  maintaining your own persistent network connection. Also, GCM is optimized to

  work with Doze and App Standby idle modes by means of <a href=

  "https://developers.google.com/cloud-messaging/concept-options#setting-the-priority-of-a-message">

  high-priority GCM messages</a>.

</p>

<p>

  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.

</p>

<p>

  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.

</p>

<p>

  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

  <a href="#testing_doze_and_app_standby">Testing with Doze and App Standby</a>.

</p>

<h2 id="understand_app_standby">Understanding App Standby</h2>

  time, the system allows idle apps network access around once a day.

</p>

<h2 id="other_use_cases">Support for other use-cases</h2>

<h2 id="using_gcm">Using GCM to Interact with Your App While the Device is Idle</h2>

<p>

  <a href="https://developers.google.com/cloud-messaging/">Google Cloud

  Messaging (GCM)</a> 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 <strong>use GCM if possible</strong>, rather than

  maintaining your own persistent network connection.

</p>

<p>

  GCM is optimized to work with Doze and App Standby idle modes by means of

  <a href="https://developers.google.com/cloud-messaging/concept-options#setting-the-priority-of-a-message">

  high-priority GCM messages</a>. 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.

</p>

<p>

  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

  <strong>partially exempt</strong> from Doze and App Standby optimizations.

  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.

</p>

<p>

  An app that is whitelisted can use the network and hold {@link

  android.os.PowerManager#PARTIAL_WAKE_LOCK partial wake locks} during Doze and

  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.

</p>

<h2 id="support_for_other_use_cases">Support for Other Use Cases</h2>

<p>

  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 <strong>partially

  exempt</strong> from Doze and App Standby optimizations.

</p>

<p>

  An app that is whitelisted can use the network and hold

  <a href="{@docRoot}reference/android/os/PowerManager.html#PARTIAL_WAKE_LOCK">

  partial wake locks</a> during Doze and

  App Standby. However, <strong>other restrictions still apply</strong> 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()}.

  </li>

</p>

<p>

  Users can manually configure the whitelist in <strong>Settings &gt; Battery

  &gt; Battery Optimization.</strong> Alternatively, the system provides

  ways for apps to ask users to whitelist them.

</p>

<ul>

  <li>Apps can fire the {@link

  <li>An app can fire the {@link

  android.provider.Settings#ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS} intent

  to take the user directly to Battery Optimization settings to add the app.

  to take the user directly to the <strong>Battery Optimization</strong>, where they can

  add the app.

  </li>

  <li>Apps holding the {@link

  <li>An app holding the {@link

  android.Manifest.permission#REQUEST_IGNORE_BATTERY_OPTIMIZATIONS} permission

  can trigger a system dialog to let the user add the app to the whitelist

  directly, without going to settings. The app fires a {@link

  android.provider.Settings#ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS} Intent

  to trigger dialog.

  </li>

  <li>An app can check whether it is currently on the exemption whitelist by

  calling {@link

  android.os.PowerManager#isIgnoringBatteryOptimizations(java.lang.String)

  isIgnoringBatteryOptimizations()}.

  to trigger the dialog.

  </li>

  <li>The user can manually remove apps from the whitelist as needed.

  </li>

</ul>

<p>

  Before asking the user to add your app to the whitelist, make sure the

  app meets the acceptable use-cases for whitelisting listed below.

</p>

<p>Before asking the user to add your app to the whitelist, make sure the app

matches the <a href="#whitelisting-cases">acceptable use cases</a> for whitelisting.</p>

<p class="caution">

<p>

  To ensure a great experience for your users, you should test your app fully

  in Doze and Standby.

  in Doze and App Standby.

</p>

<h3 id="testing_your_app_with_doze">Testing your app with Doze</h3>

<p>You can test your app in Doze by following these steps:</p>

<h3 id="testing_doze">Testing your app with Doze</h4>

<p>You can test Doze mode by following these steps:</p>

<ol>

  <li>Configure a hardware device or virtual device with an Android 6.0 (API

  level 23) or higher system image.

  <pre class="no-pretty-print">$ adb shell dumpsys battery unplug

$ adb shell dumpsys deviceidle step

$ adb shell dumpsys deviceidle -h</pre>

  <!--(TODO: App Standby tells how to wake app. We should explain this here, as well.)-->

  </li>

  <li> Observe the behavior of your app after you reactivate the device. Make

  </li>

</ol>

<h3 id="testing_your_app_with_app_standby">Testing your app with App Standby</h3>

<h3 id="testing_your_app_with_app_standby">Testing your app with App Standby</h4>

<p>To test the App Standby mode with your app:</p>

  <pre class="no-pretty-print">$ adb shell am set-inactive &lt;packageName&gt; false

$ adb shell am get-inactive &lt;packageName&gt;</pre>

  <!--// TODO: Testing page didn't have this fourth line. Do we need it? If not,

  change "following commands" to "following command". -->

  </li>

  <li>Observe the behavior of your app after waking it. Make sure the app recovers gracefully

    from standby mode. In particular, you should check if your app's Notifications and background

</ol>

<h2 id="appendix">Appendix. Example Whitelisting Use-Cases</h2>

<h2 id="whitelisting-cases">Example Use Cases for Whitelisting</h2>

<p>The table below highlights the acceptable use-cases for requesting or being on

   the Battery Optimizations exceptions whitelist. For more information, see

   <a href="">Other supported use cases</a>.</p>

<p>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.</p>

   <p>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. </p>

   <p>For more information, see <a href="#support_for_other_use_cases">Support for Other Use Cases

   </a>.</p>

<table>

 <tr>

    <td>Use {@link android.app.AlarmManager} and {@link android.app.job.JobScheduler}

    APIs to optmize notifications, sync, etc.</td>

 </tr>

</table>