docs/html/preview/behavior-changes.jd

page.title=Behavior Changes
page.keywords=preview,sdk,compatibility
meta.tags="preview", "compatibility"
page.tags="preview", "developer preview"
page.image=images/cards/card-n-changes_2x.png
@jd:body


<div id="qv-wrapper">
<div id="qv">

<h2>In this document</h2>

<ol>
  <li><a href="#perf">Performance Improvements</a>
    <ol>
      <li><a href="#doze">Doze</a></li>
      <li><a href="#bg-opt">Background Optimizations</a></li>
    </ol>
  </li>
  <li><a href="#perm">Permissions Changes</a></li>
  <li><a href="#accessibility">Accessibility Improvements</a>
    <ol>
      <li><a href="#screen-zoom">Screen Zoom</a></li>
      <li><a href="#vision-settings">Vision Settings in Setup Wizard</a></li>
    </ol>
  </li>
  <li><a href="#ndk">NDK Apps Linking to Platform Libraries</a></li>
  <li><a href="#afw">Android for Work</a></li>
</ol>

<h2>See Also</h2>
<ol>
  <li><a href="{@docRoot}preview/api-overview.html">
    Android N API Overview</a></li>
</ol>

</div>
</div>


<p>
  Along with new features and capabilities, Android N
  includes a variety of system and API behavior changes. This document
  highlights some of the key changes that you should understand and account for
  in your apps.
</p>

<p>
  If you have previously published an app for Android, be aware that your app
  might be affected by these changes in the platform.
</p>


<h2 id="perf">Performance Improvements</h2>

<p>
  Android N contains system behavior changes aimed at improving the battery
  life of devices, RAM usage, and app performance. These changes can impact the
  availability of system resources and system notifications to your app. You
  should review these changes and evaluate how your app may need to adjust to
  them.
</p>

<h3 id="doze">Doze</h3>

<p>
  Introduced in Android 6.0 (API level 23), Doze improves battery life by
  deferring CPU and network activities when a user leaves a device unplugged,
  stationary, and with the screen turned off. Android N brings further
  enhancements to Doze by applying a subset of CPU and network restrictions
  while the device is unplugged with the screen turned off, but not necessarily
  stationary, for example, when a handset is traveling in a user’s pocket.
</p>


<img src="{@docRoot}preview/images/doze-diagram-1.png"
  alt="" height="251px" id="figure1" />
<p class="img-caption">
  <strong>Figure 1.</strong> Illustration of how Doze applies a first level of
  system activity restrictions to improve battery life.
</p>

<p>
  When a device is on battery power, and the screen has been off for a certain
  time, the device enters Doze and applies the first subset of restrictions: It
  shuts off app network access, and defers jobs and syncs. If the device is
  stationary for a certain time after entering Doze, the system applies the
  rest of the Doze restrictions to {@link android.os.PowerManager.WakeLock},
  {@link android.app.AlarmManager} alarms, GPS, and Wi-Fi scans. Regardless of
  whether some or all Doze restrictions are being applied, the system wakes the
  device for brief maintenance windows, during which applications are allowed
  network access and can execute any deferred jobs/syncs.
</p>


<img src="{@docRoot}preview/images/doze-diagram-2.png"
  alt="" id="figure2" />
<p class="img-caption">
  <strong>Figure 2.</strong> Illustration of how Doze applies a second level of
  system activity restrictions after the device is stationary for a certain time.
</p>

<p>
  Note that activating the screen on or plugging in the device exits Doze and
  removes these processing restrictions. The additional behavior does not
  affect recommendations and best practices in adapting your app to the prior
  version of Doze introduced in Android 6.0 (API level 23), as discussed in
  <a href="{@docRoot}training/monitoring-device-state/doze-standby.html">
  Optimizing for Doze and App Standby</a>. You should still
  follow those recommendations, such as using Google Cloud Messaging (GCM) to
  send and receive messages, and start planning updates to accomodate the
  additional Doze behavior.
</p>


<h3 id="bg-opt">Project Svelte: Background Optimizations</h3>

<p>
  Android N removes three implicit broadcasts in order to help optimize both
  memory use and power consumption. This change is necessary because implicit
  broadcasts frequently start apps that have registered to listen for them in
  the background. Removing these broadcasts can substantially benefit device
  performance and user experience.
</p>

<p>
  Mobile devices experience frequent connectivity changes, such as when moving
  between Wi-Fi and mobile data. Currently, apps can monitor for changes in
  connectivity by registering a receiver for the implicit {@link
  android.net.ConnectivityManager#CONNECTIVITY_ACTION} broadcast in their
  manifest. Since many apps register to receive this broadcast, a single
  network switch can cause them all to wake up and process the broadcast at
  once.
</p>

<p>
  Similarly, apps can register to receive implicit {@link
  android.hardware.Camera#ACTION_NEW_PICTURE} and {@link
  android.hardware.Camera#ACTION_NEW_VIDEO} broadcasts from other apps, such as
  Camera. When a user takes a picture with the Camera app, these apps wake up
  to process the broadcast.
</p>

<p>
  To alleviate these issues, Android N applies the following
  optimizations:
</p>

<ul>
  <li>Apps targeting Android N do not receive {@link
  android.net.ConnectivityManager#CONNECTIVITY_ACTION} broadcasts, even if they
  have manifest entries to request notification of these events. Apps running
  in the foreground can still listen for {@code CONNECTIVITY_CHANGE} on their
  main thread if they request notification with a {@link
  android.content.BroadcastReceiver}.
  </li>

  <li>Apps cannot send or receive {@link
  android.hardware.Camera#ACTION_NEW_PICTURE} or {@link
  android.hardware.Camera#ACTION_NEW_VIDEO} broadcasts. This optimization
  affects all apps, not only those targeting Android N.
  </li>
</ul>

<p>
  Future releases of Android may deprecate additional implicit broadcasts, as
  well as unbound background services. For this reason, you should avoid or
  remove dependencies on manifest-declared receivers for implicit broadcasts,
  as well as on background services.
</p>

<p>
  The Android framework provides several solutions to mitigate the need for
  these implicit broadcasts or background services. For example, the {@link
  android.app.job.JobScheduler} API provides a robust mechanism to schedule
  network operations when specified conditions, such as connection to an
  unmetered network, are met. You can even use {@link
  android.app.job.JobScheduler} to react to changes to content providers.
</p>

<p>
  For more information about this behavior change and how to adapt your app,
  see <a href=
  "{@docRoot}preview/features/background-optimization.html">Background
  Optimizations</a>.
</p>


<h2 id="perm">Permissions Changes</h2>

<p>
  Android N includes changes to permissions that may affect your app,
  including user accounts permissions and a new permission for writing to
  external storage. Here is a summary of the permissions that have changed in
  the preview:
</p>

<ul>
  <li>{@code GET_ACCOUNTS} (Deprecated)
    <p>
      The GET_ACCOUNTS permission is now deprecated. The system ignores this
      permission for apps that target Android N.
    </p>
  </li>

  <li>{@code ACTION_OPEN_EXTERNAL_DIRECTORY} (New)
    <p>
      This permission is for a new storage option. Apps can now use the intent
      {@code ACTION_OPEN_EXTERNAL_DIRECTORY} to request that the system create a
      directory for the app's use. The system prompts the user to grant
      approval. If the user approves, the app can read and write files and
      directories in that one directory (and its descendants). The app does not
      need {@link android.Manifest.permission_group#STORAGE STORAGE}
      permissions to access this external directory
    </p>

    <p>
      For more information about this intent, see the updated
      {@code Intent} reference documentation in the
      <a href="{@docRoot}preview/setup-sdk.html#docs-dl">N Preview SDK
      Reference</a>.
    </p>
  </li>
</ul>



<h2 id="accessibility">Accessibility Improvements</h2>

<p>
  Android N includes changes intended to improve the usability of the
  platform for users with low or impaired vision. These changes should
  generally not require code changes in your app, however you should review
  these feature and test them with your app to assess potential impacts to user
  experience.
</p>


<h3 id="screen-zoom">Screen Zoom</h3>

<p>
  Android N enables users to set <strong>Display size</strong>which magnifies
  or shrinks all elements on the screen, thereby improving device accessibility
  for users with low vision. Users cannot zoom the screen past a minimum screen
  width of <a href=
  "http://developer.android.com/guide/topics/resources/providing-resources.html">
  sw320dp</a>, which is the width of a Nexus 4, a common medium-sized phone.
</p>

<div class="cols">

<div class="col-6">
  <img src="{@docRoot}preview/images/screen-zoom-1.png" alt="" height="XXX" id="figure1" />
</div>
<div class="col-6">
  <img src="{@docRoot}preview/images/screen-zoom-2.png" alt="" height="XXX" id="figure1" />
</div>

</div> <!-- end cols -->
<p class="img-caption">
  <strong>Figure 3.</strong> The screen on the right shows the effect of
  increasing the Display size of a device running an Android N system image.
</p>


<p>
  When the device density changes, the system notifies running apps in the
  following ways:
</p>

<ul>
  <li>If an app targets API level 23 or lower, the system automatically kills
  all its background processes. This means that if a user switches away from
  such an app to open the <em>Settings</em> screen and changes the
  <strong>Display size</strong> setting, the system kills the app in the same
  manner that it would in a low-memory situation. If the app has any foreground
  processes, the system notifies those processes of the configuration change as
  described in <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling
  Runtime Changes</a>, just as if the device's orientation had changed.
  </li>

  <li>If an app targets Android N, all of its processes
  (foreground and background) are notified of the configuration change as
  described in <a href=
  "{@docRoot}guide/topics/resources/runtime-changes.html">Handling
  Runtime Changes</a>.
  </li>
</ul>

<p>
  Most apps do not need to make any changes to support this feature, provided
  the apps follow Android best practices. Specific things to check for:
</p>

<ul>
  <li>Test your app on a device with screen width <code><a href=
  "{@docRoot}guide/topics/resources/providing-resources.html">sw320dp</a></code>
  and be sure it performs adequately.
  </li>

  <li>When the device configuration changes, update any density-dependent
  cached information, such as cached bitmaps or resources loaded from the
  network. Check for configuration changes when the app resumes from the paused
  state.
    <p class="note">
      <strong>Note:</strong> If you cache configuration-dependent data, it's a
      good idea to include relevant metadata such as the appropriate screen
      size or pixel density for that data. Saving this metadata allows you to
      decide whether you need to refresh the cached data after a configuration
      change.
    </p>
  </li>

  <li>Avoid specifying dimensions with px units, since they do not scale with
  screen density. Instead, specify dimensions with <a href=
  "{@docRoot}guide/practices/screens_support.html">density-independent
  pixel</a> (<code>dp</code>) units.
  </li>
</ul>

<h3 id="vision-settings">Vision Settings in Setup Wizard</h3>

<p>
  Android N includes Vision Settings on the Welcome screen, where users can
  set up the following accessibility settings on a new device:
  <strong>Magnification gesture</strong>, <strong>Font size</strong>,
  <strong>Display size</strong> and <strong>TalkBack</strong>. This change
  increases the visibility of bugs related to different screen settings. To
  assess the impact of this feature, you should test your apps with these
  settings enabled. You can find the settings under <strong>Settings &gt;
  Accessibility</strong>.
</p>

<h2 id="ndk">NDK Apps Linking to Platform Libraries</h2>

<p>
  Android N includes namespace changes to prevent loading of non-public APIs.
  If you use the NDK, you should only be using public APIs from the Android
  platform. Using non-public APIs in the next official release of Android
  can cause your app to crash.
</p>

<p>
  In order to alert you to use of non-public APIs, apps running on an Android N
  device generate an error in logcat output when an app calls a non-public API.
  This error is also displayed on the device screen as a message to help
  raise awareness of this situation. You should review your app code to
  remove use of non-public platform APIs and thoroughly test your apps using
  a preview device or emulator.
</p>

<p>
  If your app depends on platform libraries, see the NDK documentation for
  typical fixes for replacing common private APIs with public API equivalents.
  You may also be linking to platform libraries without realizing it,
  especially if your app uses a library that is part of the platform (such as
  <code>libpng</code>), but is not part of the NDK. In that case, ensure that
  your APK contains all the .so files you intended to link against.
</p>

<p class="caution">
  <strong>Caution:</strong> Some third-party libraries may link to non-public
  APIs. If your app uses these libraries, your app may crash when running
  on the next official release of Android.
</p>

<p>
  Apps should not depend on or use native libraries that are not included in
  the NDK, because they may change, or be removed from one Android release to
  another. The switch from OpenSSL to BoringSSL is an example of such a change.
  Also, different devices may offer different levels of compatibility, because
  there are no compatibility requirements for platform libraries not included
  in the NDK. If you must access non-NDK libraries on older devices, make the
  loading dependent on the Android API level.
</p>

<p>
  To help you diagnose these types problems here are some example Java and NDK
  errors you might encounter when attempting to build your app with Android N:
</p>

<p>Example Java error:</p>
<pre class="no-pretty-print">
java.lang.UnsatisfiedLinkError: dlopen failed: library "/system/lib/libcutils.so"
    is not accessible for the namespace "classloader-namespace"
</pre>

<p>Example NDK error:</p>
<pre class="no-pretty-print">
dlopen failed: cannot locate symbol "__system_property_get" referenced by ...
</pre>


<p>
  Here are some typical fixes for apps encountering these types of errors:
</p>

<ul>
  <li>Use of getJavaVM and getJNIEnv from libandroid_runtime.so can be replaced
  with standard JNI functions:
<pre class="no-pretty-print">
AndroidRuntime::getJavaVM -&gt; GetJavaVM from &lt;jni.h&gt;
AndroidRuntime::getJNIEnv -&gt; JavaVM::GetEnv or
JavaVM::AttachCurrentThread from &lt;jni.h&gt;.
</pre>
  </li>

  <li>Use of {@code property_get} symbol from {@code libcutils.so} can be
    replaced with the public {@code alternative __system_property_get}.
   To do this, use {@code __system_property_get} with the following include:
<pre>
#include &lt;sys/system_properties.h&gt;
</pre>
  </li>

  <li>Use of {@code SSL_ctrl} symbol from {@code libcrypto.so} should be
  replaced with an app local version. For example, you should statically link
  {@code libcyrpto.a} in your {@code .so} file or include your own dynamically
  {@code libcrypto.so} from BoringSSL or OpenSSL in your app.
  </li>
</ul>

<h2 id="afw">Android for Work</h2>
<p>
  Android N contains changes for apps that target Android for Work, including
  changes to certificate installation, password resetting, secondary user
  management, and access to device identifiers. If you are building apps for
  Android for Work environments, you should review these changes and modify
  your app accordingly.
</p>

<ul>
  <li>You must install a delegated certificate installer before the DPC can set
  it. For both profile and device-owner apps targeting the N SDK, you should
  install the delegated certificate installer before the device policy
  controller (DPC) calls
  <code>DevicePolicyManager.setCertInstallerPackage()</code>. If the installer
  is not already installed, the system throws an
  <code>IllegalArgumentException</code>.
  </li>

  <li>Reset password restrictions for device admins now apply to profile
  owners. Device admins can no longer use
  <code>DevicePolicyManager.resetPassword()</code> to clear passwords or change
  ones that are already set. Device admins can still set a password, but only
  when the device has no password, PIN, or pattern.
  </li>

  <li>Device and profile owners can manage accounts even if restrictions are
  set. Device owners and profile owners can call the Account Management APIs
  even if <code>DISALLOW_MODIFY_ACCOUNTS</code> user restrictions are in place.
  </li>

  <li>Device owners can manage secondary users more easily. When a device is
  running in device owner mode, the <code>DISALLOW_ADD_USER</code> restriction
  is automatically set. This prevents users from creating unmanaged secondary
  users. In addition, the <code>CreateUser()</code> and
  <code>createAndInitial()</code> methods are deprecated; the new
  <code>DevicePolicyManager.createAndManageUser()</code> method replaces them.
  </li>

  <li>Device owners can access device identifiers. A Device owner can access the
  Wi-Fi MAC address of a device, using
  <code>DevicePolicyManagewr.getWifiMacAddress()</code>. If Wi-Fi has never
  been enabled on the device, this method returns a value of {@code null}.
  </li>
</ul>

<p>
  For more information about changes to Android for Work in Android N, see
  <a href="{@docRoot}preview/features/afw.html">Android for Work Updates</a>.
</p>

<h2 id="other">Other important points</h2>

<ul>
<li>When an app is running on Android N, but targets a lower API level,
and the user changes display size, the app process is killed. The app
must be able to gracefully handle this scenario. Otherwise, it crashes
when the user restores it from Recents.

<p>
You should test your app to ensure
that this behavior does not occur.
You can do so by causing an identical crash
when killing the app manually via DDMS.
</p>

<p>
Apps targeting N and above are not automatically killed on density changes;
however, they may still respond poorly to configuration changes.
</p>
</li>

<li>
Apps on Android N should be able to gracefully handle configuration changes,
and should not crash on subsequent starts. You can verify app behavior
by changing font size (<strong>Setting</strong> >
<strong>Display</strong> > <strong>Font size</strong>), and then restoring
the app from Recents.
</li>
</ul>