1 page.title=Android 5.0 Behavior Changes
2 excludeFromSuggestions=true
3 sdk.platform.version=5.0
4 sdk.platform.apiLevel=21
12 <h2>In this document</h2>
14 <ol id="toc44" class="hide-nested">
15 <li><a href="#UI"><a href="#ART">ART Runtime</a></a></li>
16 <li><a href="#BehaviorNotifications">Notifications</a></li>
17 <li><a href="#BehaviorMediaControl">Media Controls</a></li>
18 <li><a href="#BehaviorGetRecentTasks">getRecentTasks()</a></li>
19 <li><a href="#64BitSupport">64-Bit Android NDK</a></li>
20 <li><a href="#BindService">Binding to a Service</a></li>
21 <li><a href="#Power"><a href="#BehaviorWebView">WebView</a></a></li>
22 <li><a href="#custom_permissions">Custom Permissions</a></li>
23 <li><a href="#ssl">TLS/SSL Configuration</a></li>
24 <li><a href="#managed_profiles">Support for Managed Profiles</a></li>
27 <h2>API Differences</h2>
29 <li><a href="{@docRoot}sdk/api_diff/21/changes.html">API level 20 to 21 »</a> </li>
30 <li><a href="{@docRoot}sdk/api_diff/preview-21/changes.html">L Developer Preview to 21 »</a> </li>
36 <li><a href="{@docRoot}about/versions/lollipop.html">Android Lollipop Highlights</a> </li>
37 <li><a href="{@docRoot}about/versions/android-5.0.html">Android 5.0 API Overview</a> </li>
44 <a class="notice-developers-video" href="https://www.youtube.com/watch?v=um1S2u022HA">
47 <p>Dev Byte: What's New in Android 5.0</p>
51 <a class="notice-developers-video" href="https://www.youtube.com/watch?v=Uiq2kZ2JHVY">
54 <p>Dev Byte: Notifications</p>
58 <p>API Level: {@sdkPlatformApiLevel}</p>
59 <p>Along with new features and capabilities, Android 5.0 includes a variety of
60 system changes and API behavior changes. This document highlights
61 some of the key changes that you should be understand and account for in your apps.</p>
63 <p>If you have previously published an app for Android, be aware that your app
64 might be affected by these changes in Android 5.0.</p>
67 <p>For a high-level look at the new platform features, instead
69 <a href="{@docRoot}about/versions/lollipop.html">Android Lollipop
74 <h2 id="ART">Android Runtime (ART)</h2>
76 <p>In Android 5.0 the ART runtime replaces Dalvik as the platform default. The ART runtime was
77 introduced in Android 4.4 on an experimental basis.</p>
79 <p>For an overview of ART's new features, see
80 <a href="https://source.android.com/devices/tech/dalvik/art.html">Introducing
81 ART</a>. Some of the major new features are:</p>
84 <li>Ahead-of-time (AOT) compilation</li>
85 <li>Improved garbage collection (GC)</li>
86 <li>Improved debugging support</li>
89 <p>Most Android apps should just work without any changes under ART. However, some
90 techniques that work on Dalvik do not work on ART. For information about the
91 most important issues, see
92 <a href="{@docRoot}guide/practices/verifying-apps-art.html">Verifying App
93 Behavior on the Android Runtime (ART)</a>. Pay particular attention if:</p>
96 <li>Your app uses Java Native Interface (JNI) to run C/C++ code.</li>
97 <li>You use development tools that generate non-standard code (such as some
99 <li>You use techniques that are incompatible with compacting garbage
104 <h2 id="BehaviorNotifications">Notifications</h2>
106 <p>Make sure your notifications take these Android 5.0 changes into account.
107 To learn more about designing your notifications for Android 5.0 and higher,
108 see the <a href="{@docRoot}design/patterns/notifications.html">notifications design guide</a>.
111 <h3 id="NotificationsMaterialDesignStyle">Material design style</h3>
112 <p>Notifications are drawn with dark text atop white (or very light) backgrounds
113 to match the new material design widgets. Make sure that all your
114 notifications look right with the new color scheme. If your notifications
115 look wrong, fix them:</p>
118 <li>Use {@link android.app.Notification.Builder#setColor(int) setColor()}
119 to set an accent color in a circle behind your icon image. </li>
120 <li>Update or remove assets that involve color. The system ignores all
121 non-alpha channels in action icons and in the main notification icon. You
122 should assume that these icons will be alpha-only. The system draws
123 notification icons in white and action icons in dark gray.</li>
126 <h3 id="NotificationsSoundVibration">Sound and vibration</h3>
127 <p>If you are currently adding sounds and vibrations to your notifications by
128 using the {@link android.media.Ringtone}, {@link android.media.MediaPlayer},
129 or {@link android.os.Vibrator} classes, remove this code so that
130 the system can present notifications correctly in
131 <em>priority</em> mode. Instead, use
132 {@link android.app.Notification.Builder} methods to add sounds and
135 <p>Setting the device to
136 {@link android.media.AudioManager#RINGER_MODE_SILENT RINGER_MODE_SILENT} causes
137 the device to enter the new priority mode. The device leaves priority
138 mode if you set it to
139 {@link android.media.AudioManager#RINGER_MODE_NORMAL RINGER_MODE_NORMAL} or
140 {@link android.media.AudioManager#RINGER_MODE_NORMAL RINGER_MODE_VIBRATE}.</p>
142 <p>Previously, Android used {@link android.media.AudioManager#STREAM_MUSIC STREAM_MUSIC}
143 as the master stream to control volume on tablet devices. In Android 5.0, the
144 master volume stream for both phone and tablet devices is now unified, and
145 is controlled by {@link android.media.AudioManager#STREAM_RING STREAM_RING} or
146 {@link android.media.AudioManager#STREAM_NOTIFICATION STREAM_NOTIFICATION}.</p>
148 <h3 id="NotificationsLockscreenVisibility">Lock screen visibility</h3>
149 <p>By default, notifications now appear on the user's lock screen in Android 5.0.
150 Users can choose to protect sensitive information from being exposed, in which
151 case the system automatically redacts the text displayed by the notification. To
152 customize this redacted notification, use
153 {@link android.app.Notification.Builder#setPublicVersion(android.app.Notification)
154 setPublicVersion()}.</p>
155 <p>If the notification does not contain personal information, or if you want to
156 allow media playback control on the notification, call the
157 {@link android.app.Notification.Builder#setVisibility(int) setVisibility()}
158 method and set the notification's visibility level to
159 {@link android.app.Notification#VISIBILITY_PUBLIC VISIBILITY_PUBLIC}.
162 <h3 id="NotificationsMediaPlayback">Media playback</h3>
163 <p>If you are implementing notifications that present media playback
164 status or transport controls, consider using the new
165 {@link android.app.Notification.MediaStyle} template instead of a custom
166 {@link android.widget.RemoteViews.RemoteView} object. Whichever approach you
167 choose, make sure to set the notification's visibility to
168 {@link android.app.Notification#VISIBILITY_PUBLIC VISIBILITY_PUBLIC} so that
169 your controls are accessible from the lock screen. Note that beginning in
170 Android 5.0, the system no longer shows
171 {@link android.media.RemoteControlClient} objects on the lock screen. For more
173 <a href="#BehaviorMediaControl">If your app uses RemoteControlClient</a>.</p>
175 <h3 id="NotificationsHeadsup">Heads-up notification</h3>
176 <p>Notifications may now appear in a small floating window (also called a
177 heads-up notification) when the device is active (that is, the device is
178 unlocked and its screen is on). These notifications appear similar to the
179 compact form of your notification, except that the heads-up notification also
180 shows action buttons. Users can act on, or dismiss, a heads-up notification
181 without leaving the current app.</p>
183 <p>Examples of conditions that may trigger heads-up notifications include:</p>
186 <li>The user's activity is in fullscreen mode (the app uses
187 {@link android.app.Notification#fullScreenIntent})</li>
188 <li>The notification has high priority and uses ringtones or vibrations</li>
191 <p>If your app implements notifications under any of those scenarios, make sure
192 that heads-up notifications are presented correctly.</p>
194 <h2 id="BehaviorMediaControl">Media Controls and RemoteControlClient</h2>
195 <p>The {@link android.media.RemoteControlClient} class is now deprecated. Switch
196 to the new {@link android.media.session.MediaSession} API as
197 soon as possible.</p>
199 <p>Lock screens in Android 5.0 do not show transport controls for
200 your {@link android.media.session.MediaSession} or
201 {@link android.media.RemoteControlClient}. Instead, your app can provide
202 media playback control from the lock screen through a notification. This
203 gives your app more control over the presentation of media buttons, while
204 providing a consistent experience for users across locked and
205 unlocked devices.</p>
207 <p>Android 5.0 introduces a new
208 {@link android.app.Notification.MediaStyle} template for this purpose.
209 {@link android.app.Notification.MediaStyle} converts notification
210 actions that you added with
211 {@link android.app.Notification.Builder#addAction(int, java.lang.CharSequence,
212 android.app.PendingIntent)
213 Notification.Builder.addAction()} into compact buttons embedded in your app's
214 media playback notifications. Pass your session token to the
215 {@link android.app.Notification.MediaStyle#setMediaSession(android.media.session.MediaSession.Token)
216 setSession()} method to inform the system that this notification controls an
217 ongoing media session.</p>
219 <p>Make sure to set the notification's visibility to
220 {@link android.app.Notification#VISIBILITY_PUBLIC VISIBILITY_PUBLIC}
221 to mark the notification as safe to show on any lock screen (secure or
222 otherwise). For more information, see
223 <a href="#LockscreenNotifications">Lock screen notifications</a>.</p>
225 <p>To display media playback controls if your app is running on the
226 Android <a href="{@docRoot}tv/index.html">TV</a> or
227 <a href="{@docRoot}wear/index.html">Wear</a> platform, implement the
228 {@link android.media.session.MediaSession} class. You should also implement
229 {@link android.media.session.MediaSession} if your app needs to receive media
230 button events on Android devices.</p>
232 <h2 id="BehaviorGetRecentTasks">getRecentTasks()</h2>
234 <p>With the introduction of the new <em>concurrent documents and activities
235 tasks</em> feature in Android 5.0 (see <a href="#Recents">Concurrent
236 documents and activities in the recents screen</a> below),
237 the {@link android.app.ActivityManager#getRecentTasks
238 ActivityManager.getRecentTasks()} method is now deprecated to improve user
239 privacy. For backward compatibility, this method still returns a small subset of
240 its data, including the calling application’s own tasks and possibly some other
241 non-sensitive tasks (such as Home). If your app is using this method to retrieve
242 its own tasks, use {@link android.app.ActivityManager#getAppTasks() getAppTasks()}
243 instead to retrieve that information.</p>
245 <h2 id="64BitSupport">64-Bit Support in the Android NDK</h2>
247 <p>Android 5.0 introduces support for 64-bit systems. The 64-bit enhancement
248 increases address space and improves performance, while still supporting
249 existing 32-bit apps fully. The 64-bit support also improves the performance of
250 OpenSSL for cryptography. In addition, this release introduces new native
251 media NDK APIs, as well as native OpenGL ES (GLES) 3.1 support.</p>
253 <p>To use the 64-bit support provided in Android 5.0, download and install NDK
254 Revision 10c from the
255 <a href="{@docRoot}tools/sdk/ndk/index.html">Android NDK page</a>. Refer to the
256 Revision 10c <a href="{@docRoot}tools/sdk/ndk/index.html#Revisions">release notes</a>
257 for more information about important changes and bug fixes to the NDK.</p>
259 <h2 id="BindService">Binding to a Service</h2>
262 {@link android.content.Context#bindService(android.content.Intent, android.content.ServiceConnection, int) Context.bindService()}
263 method now requires an explicit {@link android.content.Intent},
264 and throws an exception if given an implicit intent.
265 To ensure your app is secure, use an explicit intent when starting or binding
266 your {@link android.app.Service}, and do not declare intent filters for the service.</p>
268 <h2 id="BehaviorWebView">WebView</h2>
270 <p>Android 5.0 changes the default behavior for your app.</p>
272 <li><strong>If your app targets API level 21 or higher:</strong>
275 blocks <a href="https://developer.mozilla.org/en-US/docs/Security/MixedContent"
276 class="external-link">mixed content</a> and third party cookies by default. To allow mixed
277 content and third party cookies, use the
278 {@link android.webkit.WebSettings#setMixedContentMode(int) setMixedContentMode()}
279 and {@link android.webkit.CookieManager#setAcceptThirdPartyCookies(android.webkit.WebView, boolean) setAcceptThirdPartyCookies()}
280 methods respectively.</li>
281 <li>The system now intelligently chooses portions of the HTML
282 document to draw. This new default behavior helps to reduce memory
283 footprint and increase performance. If you want to
284 render the whole document at once, disable this optimization by calling
285 {@link android.webkit.WebView#enableSlowWholeDocumentDraw()}.</li>
288 <li><strong>If your app targets API levels lower than 21:</strong> The system
289 allows mixed content and third party cookies, and always renders the whole
290 document at once.</li>
293 <h2 id="custom_permissions">Uniqueness Requirement for Custom Permissions</h2>
296 As documented in the <a href=
297 "{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a>
298 overview, Android apps can define custom permissions as a means of managing
299 access to components in a proprietary way, without using the platform’s
300 pre-defined system permissions. Apps define custom permissions in <a href=
301 "http://developer.android.com/guide/topics/manifest/permission-element.html"><code>
302 <permission></code></a> elements declared in their manifest files.
306 There are a small number of scenarios where defining custom permissions is a
307 legitimate and secure approach. However, creating custom permissions is
308 sometimes unnecessary and can even introduce potential risk to an app,
309 depending on the protection level assigned to the permissions.
313 Android 5.0 includes a behavior change to ensure
314 that only one app can define a given custom permission, unless signed with the
315 same key as other apps defining the permission.
319 Apps using duplicate custom permissions
323 Any app can define any custom permission it wants, so it can happen
324 that multiple apps might <strong>define the same custom permission</strong>.
325 For example, if two apps offer a similar capability, they might derive the
326 same logical name for their custom permissions. Apps might also incorporate
327 common public libraries or code examples that themselves include the same
328 custom permission definitions.
332 In Android 4.4 and earlier, users were able to install multiple such
333 apps on a given device, although the system assigned the protection level
334 specified by the first-installed app.
338 Starting in Android 5.0, the system enforces a new
339 <strong>uniqueness restriction on custom permissions</strong> for
340 apps that are signed with different keys. Now only one app on a device can
341 define a given custom permission (as determined by its name), unless the
342 other app defining the permission is signed with the same key. If the user
343 tries to install an app with a duplicate custom permission and is not signed
344 with the same key as the resident app that defines the permission, the system
345 blocks the installation.
349 Considerations for your app
353 In Android 5.0 and later, apps can continue to define their own custom
354 permissions just as before and to request custom permissions from other apps
355 through the <code><uses-permission></code> mechanism. However with the
356 new requirement introduced in Android 5.0, you should carefully assess
357 possible impacts on your app.
361 Here are some points to consider:
365 <li>Does your app declare any <a href=
366 "http://developer.android.com/guide/topics/manifest/permission-element.html">
367 <code><permission></code></a> elements in its manifest? If so, are
368 they actually necessary to the proper function of your app or service? Or
369 could you use a system default permission instead?
372 <li>If you have <a href=
373 "http://developer.android.com/guide/topics/manifest/permission-element.html">
374 <code><permission></code></a> elements in your app, do you know where
378 <li>Do you actually intend for other apps to request your custom permissions
380 "http://developer.android.com/guide/topics/manifest/uses-permission-element.html">
381 <code><uses-permission></code></a>?
384 <li>Are you using boilerplate or example code in your app that includes
386 "http://developer.android.com/guide/topics/manifest/permission-element.html">
387 <code><permission></code></a> elements? Are those permission elements
391 <li>Do your custom permissions use names that are simple or based on common
392 terms that other apps might share?
397 New installs and updates
401 As mentioned above, for new installs and updates of your app on devices
402 running Android 4.4 or earlier are unaffected and there is no change in
403 behavior. For new installs and updates on devices running Android 5.0 or
404 later, the system <strong>prevents installation of your app</strong> if it
405 defines a custom permission that is already defined by an existing resident
410 Existing installs with Android 5.0 system update
414 If your app uses custom permissions and is widely distributed and installed,
415 there’s a chance that it will be affected when users receive update their
416 devices to Android 5.0. After the system update is installed, the system
417 revalidates installed apps, including a check of their custom permissions. If
418 your app defines a custom permission that is already defined by another app
419 that has already been validated, and your app is not signed with the same key
420 as the other app, the system <strong>does not re-install your app</strong>.
428 On devices running Android 5.0 or later, we recommend that you examine your
429 app immediately, make any adjustments needed, and publish the updated version
430 as soon as possible to your users.
434 <li>If you are using custom permissions in your app, consider their origin
435 and whether you actually need them. Remove all <a href=
436 "http://developer.android.com/guide/topics/manifest/permission-element.html">
437 <code><permission></code></a> elements from your app, unless you are
438 certain that they are required for proper function of your app.
441 <li>Consider replacing your custom permissions with system default
442 permissions where possible.
445 <li>If your app requires custom permissions, rename your custom permissions
446 to be unique to your app, such as by appending them to the full package name
450 <li>If you have a suite of apps <em>signed with different keys</em> and the apps
451 access a shared component by means of a custom permission, make sure that the
452 custom permission is only defined once, in the shared component. Apps that
453 use the shared component should not define the custom permission themselves,
454 but should instead request access through the <a href=
455 "{@docRoot}guide/topics/manifest/uses-permission-element.html">
456 <code><uses-permission></code></a> mechanism.
459 <li>If you have a suite of apps are <em>signed with the same key</em>,
460 each app can define the same custom permission(s) as <span style="white-space:nowrap;">needed
461 — the</span> system allows the apps to be installed in the usual way.
468 TLS/SSL Default Configuration Changes
472 Android 5.0 introduces changes the default TLS/SSL configuration used by apps
473 for HTTPS and other TLS/SSL traffic:
477 <li>TLSv1.2 and TLSv1.1 protocols are now enabled,</li>
478 <li>AES-GCM (AEAD) cipher suites are now enabled,</li>
479 <li>MD5, 3DES, export, and static key ECDH cipher suites are now disabled,</li>
480 <li>Forward Secrecy cipher suites (ECDHE and DHE) are preferred.</li>
484 These changes may lead to breakages in HTTPS or TLS/SSL connectivity in a
485 small number of cases listed below.
489 Note that the security ProviderInstaller from Google Play services already
490 offers these changes across Android platform versions back to Android 2.3.
494 Server does not support any of the enabled ciphers suites
498 For example, a server might support only 3DES or MD5 cipher suites. The
499 preferred fix is to improve the server’s configuration to enable stronger and
500 more modern cipher suites and protocols. Ideally, TLSv1.2 and AES-GCM should
501 be enabled, and Forward Secrecy cipher suites (ECDHE, DHE) should be enabled
506 An alternative is to modify the app to use a custom SSLSocketFactory to
507 communicate with the server. The factory should be designed to create
508 SSLSocket instances which have some of the cipher suites required by the
509 server enabled in addition to default cipher suites.
513 App is making wrong assumptions about cipher suites used to connect to server
517 For example, some apps contain a custom X509TrustManager that breaks because
518 it expects the authType parameter to be RSA but encounters ECDHE_RSA or
523 Server is intolerant to TLSv1.1, TLSv1.2 or new TLS extensions
527 For example, the TLS/SSL handshake with a server is erroneously rejected or
528 stalls. The preferred fix is to upgrade the server to comply with the TLS/SSL
529 protocol. This will make the server successfully negotiate these newer
530 protocols or negotiate TLSv1 or older protocols and ignore TLS extensions it
531 does not understand. In some cases disabling TLSv1.1 and TLSv1.2 on the
532 server may work as a stopgap measure until the server software is upgraded.
536 An alternative is to modify the app to use a custom SSLSocketFactory to
537 communicate with the server. The factory should be designed to create
538 SSLSocket instances with only those protocols enabled which are correctly
539 supported by the server.
542 <h2 id="managed_profiles">Support for Managed Profiles</h2>
545 Device administrators can add a <em>managed profile</em> to a device. This
546 profile is owned by the administrator, giving the administrator control
547 over the managed profile while leaving the user's personal profile, and its
548 storage space, under the user's control.
549 This change can affect the behavior of your existing app in
550 the following ways.</p>
552 <h3 id="mg_profile_intents">Handling intents</h3>
554 <p>Device administrators can restrict access to system applications from the
555 managed profile. In this case, if an app fires an intent from the managed
556 profile that would ordinarily be handled by that application, and there is no
557 suitable handler for the intent on the managed profile,
558 the intent causes an exception. For example, the
559 device administrator can restrict apps on the managed profile from accessing
560 the system's camera application. If your app is running on the managed profile
562 android.app.Activity#startActivityForResult startActivityForResult()} for {@link
563 android.provider.MediaStore#ACTION_IMAGE_CAPTURE
564 MediaStore.ACTION_IMAGE_CAPTURE}, and there is no app on the managed profile
565 that can handle the intent, this results in an {@link
566 android.content.ActivityNotFoundException}.</p>
568 <p>You can prevent this by checking
569 that there is at least one handler for any intent
570 before firing it. To check for a valid handler, call {@link
571 android.content.Intent#resolveActivity Intent.resolveActivity()}. You can see
572 an example of this being done in <a
573 href="{@docRoot}training/camera/photobasics.html#TaskCaptureIntent">Take Photos
574 Simply: Take a Photo with the Camera App</a>.</p>
576 <h3 id="mp_profile_file_sharing">Sharing files across profiles</h3>
578 <p>Each profile has its own file storage. Since a file URI refers to a specific
579 location in the file storage, this means that a file URI that is valid on one
580 profile is not valid on the other one. This is not ordinarily a problem for an
581 app, which usually just accesses the files it creates. However, if an app
582 attaches a file to an intent, it is not safe to attach a file URI, since in some
583 circumstances, the intent might be handled on the other profile.
584 For example, a device administrator might specify that image capture events
585 should be handled by the camera app on the personal profile. If the intent is
586 fired by an app on the managed profile, the camera needs to be able to write the
587 image to a location where the managed profile's apps can read it.</p>
590 you need to attach a file to an intent that might cross from one profile to the
591 other, you should create and use a <em>content URI</em> for the file. For more
592 information about sharing files with content URIs, see <a
593 href="{@docRoot}training/secure-file-sharing/index.html">Sharing Files</a>.
594 For example, the device administrator might whitelist {@link
595 android.provider.MediaStore#ACTION_IMAGE_CAPTURE ACTION_IMAGE_CAPTURE} to be
596 handled by the camera in the personal profile. The firing intent's {@link
597 android.provider.MediaStore#EXTRA_OUTPUT EXTRA_OUTPUT} should contain a content
598 URI specifying where the photo should be stored. The camera app can write the
599 image to the location specified by that URI, and the app that fired the intent
600 would be able to read that file, even if the app is on the other profile. </p>