docs/html/preview/api-overview.jd

page.title=API Overview
page.keywords=preview,sdk,compatibility
sdk.platform.apiLevel=22-mnc
page.image=images/cards/card-key-changes_16-9_2x.png
@jd:body


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

<h2>In this document
    <a href="#" onclick="hideNestedItems('#toc44',this);return false;" class="header-toggle">
        <span class="more">show more</span>
        <span class="less" style="display:none">show less</span></a></h2>

<ol id="toc44" class="hide-nested">
  <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 &raquo;</a> </li>
</ol>

</div>
</div>

<p>The M Developer Preview gives you an advance look at the upcoming release
for the Android platform, which offers new features for users and app
developers. This document provides an introduction to the most notable APIs.</p>

<p>The M Developer Preview is intended for <strong>developer early
adopters</strong> and <strong>testers</strong>. If you are interested in
influencing the direction of the Android framework,
<a href="{@docRoot}preview/setup-sdk.html">give the M Developer Preview a
try</a> and send us your feedback!</p>

<p class="caution"><strong>Caution:</strong> Do not not publish apps
that use the M Developer Preview to the Google Play store.</p>

<p class="note"><strong>Note:</strong> This document often refers to classes and
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/m-developer-preview-reference.zip">
preview reference</a>.</p>

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

<p>Please see <a href="api-changes.html">Behavior Changes</a> for complete information.</p>

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

<pre>
&lt;uses-permission
        android:name="android.permission.USE_FINGERPRINT" /&gt;
</pre>

<p>The following snippet shows how you might listen for fingerprint events in your
{@code FingerprintManager.AuthenticationCallback} implementation.</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);
}

// 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()
        &amp;&amp; mFingerprintManager.hasEnrolledFingerprints();
}
</pre>

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

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

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

<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>
&lt;service android:name=".ChooserTargetService"
        android:label="&#64;string/service_name"
        android:permission="android.permission.BIND_CHOOSER_TARGET_SERVICE"&gt;
    &lt;intent-filter&gt;
        &lt;action android:name="android.service.chooser.ChooserTargetService" /&gt;
    &lt;/intent-filter&gt;
&lt;/service&gt;
</pre>

<p>For each activity that you want to expose to the {@code ChooserTargetService}, add a
{@code &lt;meta-data&gt;} element with the name
{@code "android.service.chooser.chooser_target_service"} in your app manifest.
</p>

<pre>
&lt;activity android:name=".MyShareActivity”
        android:label="&#64;string/share_activity_label"&gt;
    &lt;intent-filter>
        &lt;action android:name="android.intent.action.SEND" /&gt;
    &lt;/intent-filter>
&lt;meta-data
        android:name="android.service.chooser.chooser_target_service"
        android:value=".ChooserTargetService" /&gt;
&lt;/activity>
</pre>

<h2 id="voice-interactions">Voice Interactions</h2>
<p>
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=
  "{@docRoot}preview/reference.html">API Differences Report</a>.
</p>