diff options
Diffstat (limited to 'docs/html/preview/api-overview.jd')
| -rw-r--r-- | docs/html/preview/api-overview.jd | 358 |
1 files changed, 303 insertions, 55 deletions
diff --git a/docs/html/preview/api-overview.jd b/docs/html/preview/api-overview.jd index dde3c7b..b207e35 100644 --- a/docs/html/preview/api-overview.jd +++ b/docs/html/preview/api-overview.jd @@ -1,6 +1,6 @@ page.title=API Overview page.keywords=preview,sdk,compatibility -sdk.platform.apiLevel=22 +sdk.platform.apiLevel=23 @jd:body @@ -13,24 +13,24 @@ sdk.platform.apiLevel=22 <span class="less" style="display:none">show less</span></a></h2> <ol id="toc44" class="hide-nested"> - <li><a href="#">Important Behavior Changes</a> - <ol> - <li><a href="#">change 1</a></li> - <li><a href="#">change 2</a></li> - </ol> - </li> - <li><a href="#">Feature Group 1</a> - <ol> - <li><a href="#">change 1</a></li> - <li><a href="#">change 2</a></li> - </ol> - </li> - <li><a href="#">Feature Group 2</a> - <ol> - <li><a href="#">change 1</a></li> - <li><a href="#">change 2</a></li> - </ol> + <li><a href="#backup">Auto Backup for Apps</a></li> + <li><a href="#notifications">Notifications</a></li> + <li><a href="#authentication">Authentication</a> + <ul> + <li><a href="#fingerprint-authentication">Fingerprint Authentication</a></li> + <li><a href="#confirm-credentials">Confirm Credentials</a></li> + </ul> </li> + <li><a href="#direct-share">Direct Share</a></li> + <li><a href="#voice-interactions">Voice Interactions</a></li> + <li><a href="#bluetooth-stylus">Bluetooth Stylus Support</a></li> + <li><a href="#audio">New Audio Features</a></li> + <li><a href="#afw">New Android for Work Features</a></li> +</ol> + +<h2>API Differences</h2> +<ol> +<li><a href="">API level 22 to M »</a> </li> </ol> </div> @@ -54,65 +54,313 @@ methods that do not yet have reference material available on <a href="{@docRoot}">developer.android.com</a>. These API elements are formatted in {@code code style} in this document (without hyperlinks). For the preliminary API documentation for these elements, download the <a -href="http://storage.googleapis.com/androiddevelopers/preview/l-developer-preview-reference.zip">preview -reference</a>.</p> +href="http://storage.googleapis.com/androiddevelopers/preview/m-developer-preview-reference.zip"> +preview reference</a>.</p> -<h2 id="Behaviors">Important Behavior Changes</h2> +<h3>Important behavior changes</h3> -<p>If you have previously published an app for Android, be aware that your app - might be affected by changes in the upcoming release.</p> +<p>If you have previously published an app for Android, be aware that your app might be affected +by changes in M.</p> -<h3 id="id">Behavior Change 1</h3> +<p>Please see <a href="api-changes.html">Behavior Changes</a> for complete information.</p> -<p> - 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. +<h2 id="backup">Auto Backup for Apps</h2> +<p>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.</p> +<p>To learn how this feature works and how to configure what to back up on the file system, +see the <a href="">App Backup for Apps guide</a>.</p> + +<h2 id="notifications">Notifications</h2> +<p>M adds the following API changes for notifications:</p> +<ul> + <li>New {@code NotificationListenerService.INTERRUPTION_FILTER_ALARMS} filter level that + corresponds to the new <em>Alarms only</em> do not disturb mode.</li> + <li>New {@code Notification.CATEGORY_REMINDER} category value that is used to distinguish + user-scheduled reminders from other events + ({@link android.app.Notification#CATEGORY_EVENT}) and alarms + ({@link android.app.Notification#CATEGORY_ALARM}).</li> + <li>New {@code android.graphics.drawable.Icon} class which can be attached to your notifications + via the Notification.Builder.setIcon() and Notification.Builder.setLargeIcon() methods.</li> + <li>New {@code NotificationManager.getActiveNotifications()} method that allows your apps to + find out which of their notifications are currently alive.</li> +</ul> + +<h2 id="authentication">Authentication</h2> +<p>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 <a href="{@docRoot}training/articles/keystore.html">Android Keystore system</a>.</p> + +<h3 id="fingerprint-authentication">Fingerprint Authentication</h3> + +<p>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. </p> +<img src="{@docRoot}preview/images/fingerprint-screen_2x.png" +srcset="{@docRoot}preview/images/fingerprint-screen.png 1x, preview/images/fingerprint-screen_2x.png 2x" +style="margin:0 0 10px 20px" width="282" height="476" /> +<p>To use this feature in your app, first add the {@code USE_FINGERPRINT} permission in your +manifest.</p> -<h2 id="id">Feature Group 1</h2> +<pre> +<uses-permission + android:name="android.permission.USE_FINGERPRINT" /> +</pre> -<h3 id="id">Feature item 1</h3> +<p>The following snippet shows how you might listen for fingerprint events in your +{@code FingerprintManager.AuthenticationCallback} implementation.</p> -<p> - 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: -</p> +<pre> +// 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); +} -<h3 id="id">Feature item 2</h3> +// 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(); +} +</pre> -<p> - 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: -</p> +<h3 id="confirm-credentials">Confirm Credentials</h3> +<p>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.</p> -<h2 id="id">Feature Group 2</h2> +<p>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.</p> -<h3 id="id">Feature item 1</h3> +<p>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.</p> -<p> - 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: +<pre> +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); + } +} +</pre> + +<p>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.</p> + +<h2 id="direct-share">Direct Share</h2> + +<img src="{@docRoot}preview/images/direct-share-screen_2x.png" +srcset="{@docRoot}preview/images/direct-share-screen.png 1x, preview/images/direct-share-screen_2x.png 2x" +style="float:right; margin:0 0 20px 30px" width="312" height="385" /> + +<p>This release provides you with APIs to makes sharing intuitive and quick for users. You can now +define <em>deep links</em> that target a specific activity in your app. These deep links are +exposed to users via the <em>Share</em> 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.</p> + +<p>To enable sharing via deep links, you must define a class that extends the +{@code android.service.} <br> +{@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.</p> +<p>The following example shows how you might declare the {@code ChooserTargetService} in your +manifest.</p> +<br> +<br> +<br> +<pre> +<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> +</pre> + +<p>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. </p> -<h3 id="id">Feature item 2</h3> +<pre> +<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> +</pre> +<h2 id="voice-interactions">Voice Interactions</h2> <p> - 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 +<a href="https://developers.google.com/voice-actions/" class="external-link">Voice Actions</a>, +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.</p> +<p>To learn more about implementing voice actions, see the voice interaction API +<a href="https://developers.google.com/voice-actions/interaction/" +class="external-link">guide</a>. </p> +<h2 id="bluetooth-stylus">Bluetooth Stylus Support</h2> +<p>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.</p> + +<h2 id="audio">New Audio Features</h2> +<p>This release adds enhancements to audio processing on Android, including: </p> +<ul> + <li>Support for the <a href="http://en.wikipedia.org/wiki/MIDI" class="external-link">MIDI</a> +protocol, with the new {@code android.media.midi} APIs. Use these APIs to send and receive MIDI +events.</li> + <li>New {@code android.media.AudioRecord.Builder} and {@code android.media.AudioTrack.Builder} +classes to create digital audio capture and playback objects respectively, and configure audio +source and sink properties to override the system defaults.</li> + <li>API hooks for associating audio and input devices. This is particularly useful if your app +allows users to start a voice search from a game controller or remote control connected to Android +TV. The system invokes the new {@code android.app.Activity.onSearchRequested()} callback when the +user starts a search. To determine if the user's input device has a built-in microphone, retrieve +the {@link android.view.InputDevice} object from that callback, then call the new +{@code InputDevice.hasMic()} method.</li> + <li>New {@code android.media.AudioDevicesManager} class which lets you retrieve a list of all +attached source and sink audio devices. You can also specify an +{@code android.media.OnAudioDeviceConnectionListener} object if you want your app to be notified +when an audio device is connected or disconnected.</li> +</ul> + +<h2 id="afw">New Android for Work Features</h2> +<p>This release includes the following new APIs for Android for Work:</p> +<ul> + <li><strong>Enhanced controls for Corporate-Owned, Single-Use devices:</strong> The Device Owner +can now control the following settings to improve management of +Corporate-Owned, Single-Use (COSU) devices: + <ul> + <li>Disable or re-enable the keyguard with the +{@code DevicePolicyManager.setKeyguardEnabledState()} method.</li> + <li>Disable or re-enable the status bar (including quick settings, notifications, and the +navigation swipe-up gesture that launches Google Now) with the +{@code DevicePolicyManager.setStatusBarEnabledState()} method.</li> + <li>Disable or re-enable safe boot with the {@link android.os.UserManager} constant +{@code DISALLOW_SAFE_BOOT}.</li> + <li>Prevent the screen from turning off while plugged in with the + {@link android.provider.Settings.Global} constant {@code STAY_ON_WHILE_PLUGGED_IN}.</li> + </ul> + </li> + <li><strong>Silent install and uninstall of apps by Device Owner:</strong> A Device Owner can now +silently install and uninstall applications using the {@link android.content.pm.PackageInstaller} +APIs, independent of Google Play for Work. You can now provision devices through a Device Owner that +fetches and installs apps without user interaction. This feature is useful for enabling one-touch +provisioning of kiosks or other such devices without activating a Google account.</li> +<li><strong>Silent enterprise certificate access: </strong> When an app calls +{@link android.security.KeyChain#choosePrivateKeyAlias(android.app.Activity,android.security.KeyChainAliasCallback,java.lang.String[],java.security.Principal[],java.lang.String,int,java.lang.String) choosePrivateKeyAlias()}, +prior to the user being prompted to select a certificate, the Profile or Device Owner can now call +the {@code DeviceAdminReceiver.onChoosePrivateKeyAlias()} method to provide the alias silently to +the requesting application. This feature lets you grant managed apps access to certificates +without user interaction.</li> +<li><strong>Auto-acceptance of system updates.</strong> By setting a system update policy with +{@code DevicePolicyManager.setSystemUpdatePolicy()}, a Device Owner can now auto-accept a system +update, for instance in the case of a kiosk device, or postpone the update and prevent it being +taken by the user for up to 30 days. Furthermore, an administrator can set a time window in which an +update must be taken, for example during the hours when a kiosk device is not in use. When a +system update is available, the system checks if the Work Policy Controller app has set a system +update policy, and behaves accordingly. +</li> +<li> +<strong>Delegated certificate installation.</strong> A Profile or Device Owner can now grant a +third-party app the ability to call these {@link android.app.admin.DevicePolicyManager} certificate +management APIs: +<ul> + <li>{@link android.app.admin.DevicePolicyManager#getInstalledCaCerts(android.content.ComponentName) +getInstalledCaCerts()}</li> + <li>{@link android.app.admin.DevicePolicyManager#hasCaCertInstalled(android.content.ComponentName,byte[]) +hasCaCertInstalled()}</li> + <li>{@link android.app.admin.DevicePolicyManager#installCaCert(android.content.ComponentName,byte[]) +installCaCert()}</li> + <li>{@link android.app.admin.DevicePolicyManager#uninstallCaCert(android.content.ComponentName,byte[]) +uninstallCaCert()}</li> + <li>{@link android.app.admin.DevicePolicyManager#uninstallAllUserCaCerts(android.content.ComponentName) +uninstallAllUserCaCerts()}</li> + <li>{@link android.app.admin.DevicePolicyManager#installKeyPair(android.content.ComponentName,java.security.PrivateKey,java.security.cert.Certificate,java.lang.String) +installKeyPair()}</li> +</ul> +</li> +<li><strong>Enterprise factory reset protection.</strong> When provisioning a Device Owner, you can +now configure parameters for bypassing Factory Reset Protection (FRP), by setting the +{@code DeviceManagerPolicy.EXTRA_PROVISIONING_RESET_PROTECTION_PARAMETERS} bundle. An NFC Programmer +app can provide these parameters after a device has been reset to bypass FRP and provision the device, +without requiring the previously configured Google account. If you don't modify these parameters, +FRP remains in-place and prevents the device from being activated without the previously activated +Google credentials.</li> +<li><strong>Data usage tracking.</strong> A Profile or Device Owner can now query for the data +usage statistics visible in <em>Settings > Data</em> usage by using the new +{@code android.app.usage.NetworkStatsManager} methods. Profile Owners are automatically granted +permission to query data on the profile they manage, while Device Owners get access to usage data +of the managed primary user.</li> +</ul> <p class="note"> For a detailed view of all API changes in the M Developer Preview, see the <a href= |