API Level: M
+Along with new features and capabilities, M includes a variety of +system changes and API behavior changes. This document highlights +some of the key changes that you should be understand and account for in your apps.
+ +If you have previously published an app for Android, be aware that your app + might be affected by these changes in M.
+ +This release introduces a new runtime permissions model, where users can now directly manage +their app permissions at runtime. This model gives users improved visibility and control over +permissions, while streamlining the installation and auto-update processes for app developers. +Users can set permissions on or off for all apps running on Android M. However, apps that don’t +target M cannot request permissions at runtime.
+ +On your apps that target M, make sure to check and request for permissions at +runtime. To determine if your app has been granted a permission, call the +new {@code Context.checkSelfPermission()} method. To request for a permission, call the new +{@code Activity.requestPermission()} method.
+ +For more information on supporting the new permissions model in your app, see the + +Android M Runtime Permissions guide.
+ +Android is moving away from OpenSSL to the +BoringSSL +library. If you’re using the Android NDK in your app, don't link against cryptographic libraries +that are not a part of the NDK API, such as {@code libcrypto.so} and {@code libssl.so}. These +libraries are not public APIs, and may change or break without notice across releases and devices. +In addition, you may expose yourself to security vulnerabilities. Instead, modify your +native code to call the Java cryptography APIs via JNI or to statically link against a +cryptography library of your choice.
+ +This release introduces new power-saving optimizations for idle devices and apps.
+ +If a device is unplugged and not used for up to an hour, it goes into doze mode where +it attempts to keep the system in a sleep state. In this mode, devices may briefly resume normal +operations for up to 5 minutes every few hours so that app syncing can occur and the system can +perform any pending operations.
+ +The following restrictions apply to your apps while in device doze mode:
+When the system comes out of doze mode, it executes jobs and syncs that are pending.
+ +In M, the system may determine that apps are idle when they are not in active use by the user. +Your app goes into app standby mode after two days unless the system detects any of these +signals:
+ +If the system is running on battery power, apps that are in standby mode will have their +network access disabled and their syncs and jobs suspended. When the system is plugged into a power +supply, it brings an app out of standby mode and executes any jobs and syncs that are pending.
+ +Apps that use Google Cloud Messaging will +continue to receive messages even if they are idle. When the system is plugged into a power +supply, apps resume normal operations and can run any pending syncs and jobs.
+ +You can test this feature by connecting a device running M to your development machine and +calling the following commands: +
++$ adb shell am broadcast -a android.os.action.DISCHARGING +$ adb shell am set-idle <packageName> true +$ adb shell am set-idle <packageName> false +$ adb shell am get-idle <packageName> ++ +
+In M, users can adopt external storage devices such as SD cards. Adopting an external storage +device encrypts and formats the device to behave like internal storage. This feature allows users +to move both apps and private data of those apps between storage devices. When moving apps, the +system respects the +{@code android:installLocation} preference in the manifest.
+ +If your app accesses the following APIs or fields, be aware that the file paths they return +will dynamically change when the app is moved between internal and external storage devices. +When building file paths, it is strongly recommended that you always call these APIs dynamically. +Don’t use hardcoded file paths or persist fully-qualified file paths that were built previously.
+ +To debug this feature in the developer preview, you can enable adoption of a USB drive that is +connected to an Android device through a USB On-The-Go (OTG) cable, by running these +commands:
+ ++$ adb root +$ sleep 2 +$ adb shell setprop persist.fw.force_adoptable 1 +$ adb reboot ++ +
This release removes support for the Apache HTTP client. If your app is using this client and +targets Android 2.3 (API level 9) or higher, use the {@link java.net.HttpURLConnection} class +instead. This API is more efficient because it reduces network use through transparent compression +and response caching, and minimizes power consumption. To continue using the Apache HTTP APIs, you +must first declare the following compile-time dependency in your {@code build.gradle} file: +
+
+android {
+ compileSdkVersion M
+ useLibrary 'org.apache.http.legacy'
+}
+
+
+Setting the volume directly or muting specific streams via the {@link android.media.AudioManager} +class is no longer supported. The {@link android.media.AudioManager#setStreamSolo(int,boolean) +setStreamSolo()} method is deprecated, and you should call the +{@code AudioManager.requestAudioFocus()} method instead. Similarly, the +{@link android.media.AudioManager#setStreamMute(int,boolean) setStreamMute()} method is +deprecated; instead, call the {@code AudioManager.adjustStreamVolume()} method +and pass in the direction value {@code ADJUST_MUTE} or {@code ADJUST_UNMUTE}.
+ +
+
+When users selects text in your app, you can now display text selection actions such as +Cut, Copy, and Paste in a +floating toolbar. The user interaction implementation is similar to that +for the contextual action bar, as described in + +Enabling the contextual action mode for individual views.
+ +To implement a floating toolbar for text selection, make the following changes in your existing +apps:
+If you are using +Android Support Library revision 22.2, be aware that floating toolbars are not +backward-compatible and appcompat takes control over {@link android.view.ActionMode} objects by +default. This prevents floating toolbars from being displayed in M. To enable +{@link android.view.ActionMode} support in an +{@link android.support.v7.app.AppCompatActivity}, call +{@code android.support.v7.app.AppCompatActivity.getDelegate()}, then call +{@code android.support.v7.app.AppCompatDelegate.setHandleNativeActionModesEnabled()} on the returned +{@link android.support.v7.app.AppCompatDelegate} object and set the input +parameter to {@code false}. This call returns control of {@link android.view.ActionMode} objects to +the framework. In devices running M, that allows the framework to support +{@link android.support.v7.app.ActionBar} or floating toolbar modes, while on pre-M devices, only the +{@link android.support.v7.app.ActionBar} modes are supported.
+ +Starting this release, the +Android Keystore provider no longer supports +DSA. ECDSA is still supported.
+ +Keys which do not require encryption at rest will no longer be deleted when secure lock screen +is disabled or reset (for example, by the user or a Device Administrator). Keys which require +encryption at rest will be deleted during these events.
+ +Theme attributes are now supported in +{@link android.content.res.ColorStateList} for devices running M. The +{@link android.content.res.Resources#getColorStateList(int) getColorStateList()} and +{@link android.content.res.Resources#getColor(int) getColor()} methods have been deprecated. If +you are calling these APIs, call the new {@code Context.getColorStateList()} or +{@code Context.getColor()} methods instead. These methods are also available in the +v4 appcompat library via {@link android.support.v4.content.ContextCompat}.
+ ++Support for the {@code -night} resource qualifier has been updated in M. Previously, night mode was +only available when a device was docked and in car mode. Starting in M, night mode is available on +all devices and is user-configurable via Settings > Display > Theme. You can adjust this +setting globally using {@link android.app.UiModeManager#setNightMode(int) setNightMode()}. The +Dark theme corresponds to {@link android.app.UiModeManager#MODE_NIGHT_YES}. When the device is in +night mode, the resource framework will prefer resources that have the -night qualifier. To +take advantage of user-configurable Dark mode in your app, extend from the +{@code Theme.Material.DayNight} set of themes rather than {@code Theme.Material} or +{@code Theme.Material.Light}. +
+ +The ART runtime now properly implements access rules for the +{@link java.lang.reflect.Constructor#newInstance(java.lang.Object...) newInstance()} method. This +change fixes a problem where Dalvik was checking access rules incorrectly in previous versions. +If your app uses the +{@link java.lang.reflect.Constructor#newInstance(java.lang.Object...) newInstance()} method and you +want to override access checks, call the +{@link java.lang.reflect.Constructor#setAccessible(boolean) setAccessible()} method with the input +parameter set to {@code true}. If your app uses the +v7 appcompat library or the +v7 recyclerview library, +you must update your app to use to the latest versions of these libraries. Otherwise, make sure that +any custom classes referenced from XML are updated so that their class constructors are accessible.
+ +The M release updates the behavior of the dynamic linker. The dynamic linker now understands the +difference between a library’s {@code soname} and its path +( +public bug 6670), and search by {@code soname} is now +implemented. Apps which previously worked that have bad {@code DT_NEEDED} entries +(usually absolute paths on the build machine’s file system) may fail when loaded on M.
+ +The {@code dlopen(3) RTLD_LOCAL} flag is now correctly implemented in M. Note that +{@code RTLD_LOCAL} is the default, so calls to {@code dlopen(3)} that didn’t explicitly use +{@code RTLD_LOCAL} will be affected (unless your app explicitly used {@code RTLD_GLOBAL}). With +{@code RTLD_LOCAL}, symbols will not be made available to libraries loaded by later calls to +{@code dlopen(3)} (as opposed to being referenced by {@code DT_NEEDED} entries).
+ + +This release includes the following behavior changes for Android for Work:
+If you have previously published an app for Android, be aware that your app - might be affected by changes in the upcoming release.
+If you have previously published an app for Android, be aware that your app might be affected +by changes in M.
-Please see Behavior Changes for complete information.
-- Bacon ipsum dolor amet biltong picanha t-bone, jowl salami tri-tip jerky kielbasa sirloin boudin - porchetta fatback cow meatloaf capicola. Short ribs kielbasa pig drumstick rump boudin jowl chuck - beef ribs doner tenderloin biltong swine. +
The system now performs automatic full data backup and restore for apps. This behavior is +enabled by default for apps targeting M; you do not need to add any additional code. If users +delete their Google account, their backup data is deleted as well.
+To learn how this feature works and how to configure what to back up on the file system, +see the App Backup for Apps guide.
+ +M adds the following API changes for notifications:
+The M release offers new APIs to let you authenticate users by using their fingerprint scans on +supported devices, and check how recently the user was last authenticated using a device unlocking +mechanism (such as a lockscreen password). Use these APIs in conjunction with +the Android Keystore system.
+ +To authenticate users via fingerprint scan, get an instance of the new +{@code android.hardware.fingerprint.FingerprintManager} class and call the +{@code FingerprintManager.authenticate()} method. Your app must be running on a device with a +fingerprint sensor. You must implement the user interface for the fingerprint +authentication flow on your app, and use the standard fingerprint Android icon in your UI. +If you are developing multiple apps that use fingerprint authentication, note that each app must +authenticate the user’s fingerprint independently.
+
+To use this feature in your app, first add the {@code USE_FINGERPRINT} permission in your +manifest.
-+<uses-permission + android:name="android.permission.USE_FINGERPRINT" /> +-
The following snippet shows how you might listen for fingerprint events in your +{@code FingerprintManager.AuthenticationCallback} implementation.
-- Bacon ipsum dolor amet landjaeger capicola tail sausage shank swine biltong pork andouille t-bone - alcatra chicken. Strip steak bacon tongue beef bresaola landjaeger. Shankle boudin pork belly - jowl pig. Rump swine ham hock frankfurter pork shankle. Shank corned beef alcatra doner flank - turducken. Tongue brisket ham shoulder: +
+// Call this to start listening for fingerprint events
+public void startListening(FingerprintManager.CryptoObject cryptoObject) {
+ if (!isFingerprintAuthAvailable()) {
+ return;
+ }
+ mCancellationSignal = new CancellationSignal();
+ mSelfCancelled = false;
+ mFingerprintManager.authenticate(cryptoObject,
+ mCancellationSignal, this, 0 /* flags */);
+ // Icon to display when prompting users to start a fingerprint scan
+ mIcon.setImageResource(R.drawable.ic_fp_40px);
+}
+
+// Helper method to check if the device supports fingerprint
+// scanning and if the user has enrolled at least one fingerprint.
+public boolean isFingerprintAuthAvailable() {
+ return mFingerprintManager.isHardwareDetected()
+ && mFingerprintManager.hasEnrolledFingerprints();
+}
+
+
+Your app can authenticate users based on how recently they last unlocked their device. You can +use the same public or secret key to authenticate users into multiple apps. This feature frees +users from having to remember additional app-specific passwords, and avoids the need for you to +implement your own authentication user interface.
+ +You can set your own authentication policy by setting constraints against the key that you are +generating or importing. To set the constraints for using a key, use the +{@code android.security.KeyPairGeneratorSpec.Builder} and +{@code android.security.KeyGeneratorSpec.Builder} classes for public key pairs and secret keys +respectively. If you are importing keys, use the {@link android.security.KeyStoreParameter.Builder} +class to set your constraints.
+ +The following example shows how you might create a symmetric key in the Keystore which can only be +used if the user has successfully unlocked the device within the last 5 minutes.
+ +
+private void createKey() {
+ // Generate a key to decrypt payment credentials, tokens, etc.
+ // This will most likely be a registration step for the user when
+ // they are setting up your app.
+ try {
+ KeyStore ks = KeyStore.getInstance("AndroidKeyStore");
+ ks.load(null);
+ KeyGenerator keyGenerator = KeyGenerator.getInstance("AES",
+ "AndroidKeyStore");
+ keyGenerator.init(new KeyGeneratorSpec.Builder(this)
+ // Alias of the entry in Android KeyStore where the key will appear
+ .setAlias(KEY_NAME)
+ // Key use constraints
+ .setPurposes(KeyStoreKeyProperties.Purpose.ENCRYPT
+ | KeyStoreKeyProperties.Purpose.DECRYPT)
+ .setBlockModes("CBC")
+ .setUserAuthenticationRequired(true)
+ // Require that the user has unlocked in the last 5 minutes
+ .setUserAuthenticationValidityDurationSeconds(5 * 60)
+ .setEncryptionPaddings("PKCS7Padding")
+ .build());
+ keyGenerator.generateKey();
+ } catch (NoSuchAlgorithmException | NoSuchProviderException
+ | InvalidAlgorithmParameterException | KeyStoreException
+ | CertificateException | IOException e) {
+ throw new RuntimeException(e);
+ }
+}
+
+
+To determine the last time users logged into their account, call the +{@code android.accounts.AccountManager.confirmCredentials()} method. If the call is successful, the +method returns an bundle that includes a {@code KEY_LAST_AUTHENTICATED_TIME} value which indicates +the last time, in milliseconds, that the credential for that account was validated or created.
+ +
+
+This release provides you with APIs to makes sharing intuitive and quick for users. You can now +define deep links that target a specific activity in your app. These deep links are +exposed to users via the Share menu. This feature allows users to share content to +targets, such as contacts, within other apps. For example, the deep link might launch an +activity in another social network app, which lets the user share content directly to a specific +friend or community in that app.
+ +To enable sharing via deep links, you must define a class that extends the
+{@code android.service.}
+{@code chooser.ChooserTargetService} class. Declare your
+{@code ChooserTargetService} in the manifest. Within that declaration, specify the
+{@code BIND_CHOOSER_TARGET_SERVICE} permission and an intent filter with the
+{@code SERVICE_INTERFACE} action.
The following example shows how you might declare the {@code ChooserTargetService} in your +manifest.
++<service android:name=".ChooserTargetService" + android:label="@string/service_name" + android:permission="android.permission.BIND_CHOOSER_TARGET_SERVICE"> + <intent-filter> + <action android:name="android.service.chooser.ChooserTargetService" /> + </intent-filter> +</service> ++ +
For each activity that you want to expose to the {@code ChooserTargetService}, add a +{@code <meta-data>} element with the name +{@code "android.service.chooser.chooser_target_service"} in your app manifest.
-+<activity android:name=".MyShareActivity” + android:label="@string/share_activity_label"> + <intent-filter> + <action android:name="android.intent.action.SEND" /> + </intent-filter> +<meta-data + android:name="android.service.chooser.chooser_target_service" + android:value=".ChooserTargetService" /> +</activity> ++
- Bacon ipsum dolor amet landjaeger capicola tail sausage shank swine biltong pork andouille t-bone - alcatra chicken. Strip steak bacon tongue beef bresaola landjaeger. Shankle boudin pork belly - jowl pig. Rump swine ham hock frankfurter pork shankle. Shank corned beef alcatra doner flank - turducken. Tongue brisket ham shoulder: +This release provides a new voice interaction API which, together with +Voice Actions, +allows you to build conversational voice experiences into your apps. Call the +{@code android.app.Activity.isVoiceInteraction()} method to determine if your activity was +started in response to a voice action. If so, your app can use the +{@code android.app.VoiceInteractor} class to request a voice confirmation from the user, select +from a list of options, and more.
+To learn more about implementing voice actions, see the voice interaction API +guide.
-The M release provides improved support for user input using a Bluetooth stylus. If the user +touches a stylus with a button on the screen of your app, the +{@link android.view.MotionEvent#getToolType(int) getTooltype()} method now returns +{@code TOOL_TYPE_STYLUS}. The {@link android.view.MotionEvent#getButtonState() getButtonState()} +method returns {@link android.view.MotionEvent#BUTTON_SECONDARY} when the user +presses the primary stylus button. If the stylus has a second button, the same method returns +{@link android.view.MotionEvent#BUTTON_TERTIARY} when the user presses it. If the user presses +both buttons simultaneously, the method returns both these values. In addition, the system reports +the user button-press action to the new {@code View.onStylusButtonPressListener} and +{@code GestureDetector.OnStylusButtonPressListener} callbacks in your activity, if you have +registered these listeners in your app.
-- Bacon ipsum dolor amet landjaeger capicola tail sausage shank swine biltong pork andouille t-bone - alcatra chicken. Strip steak bacon tongue beef bresaola landjaeger. Shankle boudin pork belly - jowl pig. Rump swine ham hock frankfurter pork shankle. Shank corned beef alcatra doner flank - turducken. Tongue brisket ham shoulder: -
- -- Bacon ipsum dolor amet landjaeger capicola tail sausage shank swine biltong pork andouille t-bone - alcatra chicken. Strip steak bacon tongue beef bresaola landjaeger. Shankle boudin pork belly - jowl pig. Rump swine ham hock frankfurter pork shankle. Shank corned beef alcatra doner flank - turducken. Tongue brisket ham shoulder: -
+This release adds enhancements to audio processing on Android, including:
+This release includes the following new APIs for Android for Work:
+For a detailed view of all API changes in the M Developer Preview, see the + Users often invest significant time and effort collecting data and setting preferences within + apps. Preserving that data for users if they replace a broken device or upgrade to a new one is + an important part of ensuring a great user experience. The Android M Preview system helps ensure + a good experience for users in this circumstances by automatically backing up app data to the + cloud. +
+ ++ This behavior is enabled by default for all apps installed on devices running Android M or + higher. No additional app code is required. The system provides users with the ability opt out of + automatic data backups for individual apps. You can also choose to limit what data from your app + is backed up. +
+ ++ This document describes the new system behavior and how to specify what data is backed up for + your app. +
+ ++ The automatic backup feature preserves the data your app creates on a user device by uploading to + the user’s Google Drive account and encrypting it. There is no charge to you or the user for data + storage and the saved data does not count towards the user's personal Drive quota. During the M + Preview period, users can store up to 25MB per Android app. +
+ ++ Automatic backups occur every 24 hours, when the device is idle, charging, and connected to a + Wi-Fi network. When these conditions are met, the Backup Manager service uploads all available + backup data to the cloud. When the user transitions to a new device, or uninstalls and reinstalls + the backed up application, a restore operation will take place, copying the backed up data into + the newly installed application’s data directory. +
+ + ++ Not all app data should be backed up, such as temporary files and caches, so the automatic backup + service excludes certain data files by default: +
+ +getCacheDir() and
+ getCodeCacheDir()
+ methods.
+ getExternalFilesDir()
+ method.
+ getNoBackupFilesDir()
+ method.
+ + The data created by any app installed on an M device is backed up, except for the automatically + excluded files listed in the previous section. You can further limit and configure what data gets + backed up from your app using settings in your app manifest. +
+ ++ Depending on what data your application needs and how you save it, you may need to set specific + rules for including or excluding certain files or directories. The automatic backup service + supports setting these backup rules through use of an XML configuration file and the app + manifest. In the app manifest, you can specify a backup scheme configuration file as shown in the + following example: +
+ ++<?xml version="1.0" encoding="utf-8"?> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:tools="http://schemas.android.com/tools" + package="com.my.appexample"> + <uses-sdk android:minSdkVersion="9"/> + <uses-sdk android:targetSdkVersion="android-MNC"/> + <application ... + android:fullBackupContent="@xml/mybackupscheme"> + </application> + ... +</manifest> ++ +
+ In this example code, the android:fullBackupContent attribute specifies an XML file, located in
+ the res/xml/ directory of your app development project, named
+ mybackupscheme.xml. This configuration file can include rules for what files are
+ backed up. The following example code shows a configuration file that excludes a specific file
+ from backups:
+
+<?xml version="1.0" encoding="utf-8"?> + <full-backup-content> + <exclude domain="database" path="device_info.db"/> +</full-backup-content> ++ +
+ This backup configuration only excludes a specific database file from being backed up. All other + files are backed up. +
+ ++ The backup service configuration allows you to specify what files to include or exclude from + backup. The syntax for the data backup configuration xml file is as follows: +
+ ++<full-backup-content> + <include domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" /> + <exclude domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" /> +</full-backup-content> ++ +
+ The following elements and attributes allow you to specify the files to include and exclude from + backup: +
+ +<include>. Use this element if you want to specify a set of resources to
+ back up, instead of having the system back up all data in your app by default. When you specify
+ an <include> tag, the system backs up only the resources specified with this
+ element.
+ <exclude>. Use this element to specify a set of resources to exclude from
+ backup. The system backs up all data in your app, except for resources specified with this
+ element.
+ domain. The type of resource you want to include or exclude from backup. The valid
+ values you can specify for this attribute include:
+ root. Specifies that the resource is in the app’s root directory.
+ file. Corresponds to a resource in the directory returned by the
+ getFilesDir()
+ method.
+ database. Corresponds to a database returned by the getDatabasePath()
+ method or by using the SQLiteOpenHelper
+ class.
+ sharedpref. Corresponds to a SharedPreferences
+ object returned by the
+ getSharedPreferences() method.
+ external. Specifies that the resource is in external storage, and corresponds
+ to a file in the directory returned by the getExternalFilesDir()
+ method.
+ path. The file path to a resource that you want to include or exclude from
+ backup.
+
+ You can choose to prevent automatic backups of any of your app data by setting the
+ android:allowBackup attribute to false in the application element of
+ your manifest. This setting is illustrated in the following example code:
+
+<?xml version="1.0" encoding="utf-8"?> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:tools="http://schemas.android.com/tools" + package="com.my.appexample"> + <uses-sdk android:minSdkVersion="9"/> + <uses-sdk android:targetSdkVersion="android-MNC"/> + <application ... + android:allowBackup="false"> + </application> + ... +</manifest> ++ + +
+ Once you have created a backup configuration, you should test it to make sure your app saves data + and can be restored properly. +
+ + ++ To help determine how the backup feature is parsing your XML file, enable logging before + performing a test backup: +
+ +$ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE+ +
+ To manually enable a backup, call the following command, specifying the package name for your app
+ as the <PACKAGE> parameter:
+
$ adb shell bmgr fullbackup <PACKAGE>+ +
+ To manually initiate a restore after your app data is backed-up, call the following command,
+ specifying the package name for your app as the <PACKAGE> parameter:
+
$ adb shell bmgr restore <PACKAGE>+ +
+ Warning: This action stops your app and wipes its data before performing the restore + operation. +
+ ++ You initiate the restore process for your app by uninstalling and reinstalling your app. The app + data is automatically restored from the cloud once the app installation is complete. +
+ + ++ If you run into issues, clear the backup data and associated metadata by calling this command. +
+ +$ adb shell bmgr wipe <TRANSPORT> <PACKAGE>+ +
+ The <TRANSPORT> value must be prefixed by com.google.android.gms.
+ To get the list of transports, call the following command:
+
$ adb shell bmgr list transports+ +
The following are known issues with the automatic backup service:
+ ++ The M Developer Preview introduces a new app permissions model which makes it + less frustrating for users to install and upgrade apps. If an app running on + M supports the new permissions model, the user does not have to grant any + permissions when they install or upgrade the app. Instead, the app requests + permissions as they are needed, and the system shows a dialog to the user + asking for the permission. +
+ ++ If an app supports the new permissions model, it can still be installed and + run on devices running older versions of Android, using the old permissions + model on those devices. +
+ ++ If an app's target SDK version is the M developer preview, that indicates + that the app uses the new permissions model: +
+ +PROTECTION_NORMAL, as well as signature and system permissions, as
+ described below. The user is not prompted to grant any permissions
+ at this time.
+
+ Ordinarily, an app is just granted the
+ PROTECTION_NORMAL permissions when it is installed. However,
+ under some circumstances the app is granted more permissions:
+
+ In both cases, the user can still revoke permissions at any time by going to + the app's Settings screen, so the app should continue to check for + permissions at run time and request them if necessary. +
+ ++ If an app does not target the M developer preview, it continues to use the + old permissions model even on M devices. When the app is installed, the + system asks the user to grant all permissions listed in the app's manifest. +
+ ++ If an app using the new permissions model is run on a pre-M device, the + system treats it the same as any other app. Once again, the system asks the + user to grant all declared permissions at install time. +
+ ++ If your app targets the new M Developer Preview, you must use the new + permissions model. This means that in addition to declaring your needed + permissions in the manifest, you must also check to see if you have the + permissions at run time, and request the permissions if you do not already + have them. +
+ ++ To enable the new M Developer Preview permissions model, set the app's + + targetSdkVersion attribute to "M". Doing this enables all the new + permissions features. +
+ + + +
+ You can use the new <uses-permission-sdk-m> element in the
+ app manifest to indicate that a permission is only needed on the M platform.
+ If you declare a permission this way, then whenever the app is installed on
+ an older device, the user is not prompted to grant the permission and the
+ permission is not granted to the app. This allows you to add new permissions
+ to updated versions of your app without forcing users to grant permissions
+ when they install the update.
+
+ If the app is running on a device with the M developer preview,
+ <uses-permission-sdk-m> behaves the same as
+ <uses-permission>. The user is not prompted to grant any
+ permissions when the app is installed, and the app requests permissions as
+ they are needed.
+
+ If your app uses the new M Developer Preview permissions model, the user is + not asked to grant all permissions when the app is first launched on a device + running the M Preview. Instead, your app requests permissions as they are + needed. When your app requests a permission, the system shows a dialog to the + user. +
+ ++ An app should follow this workflow to request permissions on an Android M + device. The device can check what platform it's running on by checking the + value of {@link android.os.Build.VERSION#SDK_INT Build.VERSION.SDK_INT}. If + the device is running the M Developer Preview, {@link + android.os.Build.VERSION#SDK_INT SDK_INT} is 23. + +
+Context.CheckSelfPermission(permission_name) . The
+ app should do this even if it knows the user has already granted that
+ permission, since the user can revoke an app's permissions at any time. For
+ example, if a user wants to use an app to take a picture, the app calls
+ Context.CheckSelfPermission(Manifest.permission.CAMERA).
+ requestPermissions() to request the
+ appropriate permission or permissions. This method functions
+ asynchronously.
+
+ Activity.onRequestPermissionsResult() with the
+ results; your app needs to override that method. The callback is passed the
+ same request code you passed to
+ requestPermissions().
+
+
+ When the system asks the user to grant a permission, the user has the option
+ of telling the system not to ask for that permission again. In that case,
+ when an app asks for that permission with
+ requestPermissions(), the
+ system immediately denies the request. For this reason, your app cannot
+ assume that any direct interaction with the user has taken place.
+
+ If your app runs on a device that has SDK 22 or lower, the app uses the old
+ permissions model. When the user installs the app, they are prompted to grant
+ all the permissions your app requests in its manifest, except for those
+ permissions which are labeled with <uses-permission-sdk-m>.
+
+ The new permissions model gives users a smoother experience, and makes it + easier for them to install apps and feel comfortable with what the apps are + doing. We recommend the following best practices to take full advantage of + the new model. +
+ ++ If you confront the user with a lot of permissions requests at once, you may + overwhelm the user and cause them to quit your app. Instead, you should ask + for permissions as you need them. +
+ ++ In some cases, one or more permissions might be absolutely essential to your + app. In that case, it might make sense to ask for all the permissions as soon + as the app launches. + + For example, if you make a photography app, the app would + need access to the device camera. When the user launches the app for the + first time, they won't be surprised to be asked to give permission to use the + camera. But if the same app also had a feature to share photos with the + user's contacts, you probably should not ask for that permission at + first launch. Instead, wait until the user tries to use the "sharing" feature + and ask for the permission then. +
+ ++ If your app provides a tutorial, it may make sense to request app's essential + permissions at the end of the tutorial sequence. +
+ +
+ The permissions screen shown by the system when you call
+ requestPermissions() says what permission your app wants,
+ but doesn't say why you want it. In some cases, the user may find that
+ puzzling. It's a good idea to explain to the user why your app wants the
+ permissions before you call
+ requestPermissions().
+
+ For example, a photography app might want to use location services, so it can
+ geotag the photos. A typical user might not understand that a photo can
+ contain location information, and would be puzzled why their photography app
+ wanted to know the location. So in this case, it's a good idea for the app to
+ tell the user about this feature before calling
+
+ requestPermissions().
+
+ As noted, one way to do this is to incorporate these requests into an app
+ tutorial. The tutorial can show each of the app's features in turn, and as it
+ does this, it can explain what permissions are needed. For example, the
+ photography app's tutorial demonstrate its "share photos with your contacts"
+ feature, then tell the user that they'll need to give permission for the app
+ to see the user's contacts, and then call
+ requestPermissions()
+ to get that access. Of course, some users will want to skip the tutorial, so
+ you'll still need to check for and request permissions during the app's
+ normal operation.
+
+ Until you are ready to use the new permissions model, you can opt out simply + by setting your app's + targetSdkVersion to 22 or less. If you do this, the system will use the + old permissions model. When the user downloads the app, they will be prompted + to grant all the permissions listed in the manifest. +
+ ++ With the M Developer Preview, users can turn off permissions for any + app from the app's Settings page, regardless of what SDK version the app + targets. For this reason, it's a good idea to follow the steps described in + "Prompting for Permissions on the M Preview" even if + your app doesn't fully support the new permissions model. +
+ ++ Note: If a user turns off permissions for a legacy app, the system + silently disables the appropriate functionality. When the app attempts to + perform an operation that requires that permission, the operation will not + necessarily cause an exception. Instead, it might return an empty data set or + otherwise signal an error. +
diff --git a/docs/html/preview/images/direct-share-screen.png b/docs/html/preview/images/direct-share-screen.png new file mode 100644 index 0000000000000..9e879e03f4b73 Binary files /dev/null and b/docs/html/preview/images/direct-share-screen.png differ diff --git a/docs/html/preview/images/direct-share-screen_2x.png b/docs/html/preview/images/direct-share-screen_2x.png new file mode 100644 index 0000000000000..3bbfa7d7d50e1 Binary files /dev/null and b/docs/html/preview/images/direct-share-screen_2x.png differ diff --git a/docs/html/preview/images/fingerprint-screen.png b/docs/html/preview/images/fingerprint-screen.png new file mode 100644 index 0000000000000..0bb49ef0ffdc2 Binary files /dev/null and b/docs/html/preview/images/fingerprint-screen.png differ diff --git a/docs/html/preview/images/fingerprint-screen_2x.png b/docs/html/preview/images/fingerprint-screen_2x.png new file mode 100644 index 0000000000000..25ce51a0001c9 Binary files /dev/null and b/docs/html/preview/images/fingerprint-screen_2x.png differ diff --git a/docs/html/preview/images/text-selection.gif b/docs/html/preview/images/text-selection.gif new file mode 100644 index 0000000000000..1d82fc65c8c7b Binary files /dev/null and b/docs/html/preview/images/text-selection.gif differ diff --git a/docs/html/preview/preview_toc.cs b/docs/html/preview/preview_toc.cs index fbf73f6bf1167..a0537184c9ec4 100644 --- a/docs/html/preview/preview_toc.cs +++ b/docs/html/preview/preview_toc.cs @@ -15,10 +15,34 @@ API Overview + + + + + + + + +