Figure 1. Fullscreen activity showing a heads-up notification
The L 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.
The L Developer Preview is intended for developer early adopters and testers. If you are interested in influencing the direction of the Android framework, give the L Developer Preview a try and send us your feedback!
Caution: Do not not publish apps that use the L Developer Preview to the Google Play store.
Note: This document often refers to classes and methods that do not yet have reference material available on developer.android.com. These API elements are formatted in {@code code style} in this document (without hyperlinks). For the preliminary API documentation for these elements, download the preview reference.
If you have previously published an app for Android, be aware that your app might be affected by changes in the upcoming release.
The 4.4 release introduced a new, experimental Android runtime, ART. Under 4.4, ART was optional, and the default runtime remained Dalvik. With the L Developer Preview, ART is now the default runtime.
For an overview of ART's new features, see Introducing ART. Some of the major new features are:
Most Android apps should just work without change under ART. However, some techniques that work on Dalvik do not work on ART. For information about the most important issues, see Verifying App Behavior on the Android Runtime (ART). Pay particular attention if:
Notifications are drawn with dark text atop white (or very light) backgrounds to match the new material design widgets. Make sure that all your notifications look right with the new color scheme:
Figure 1. Fullscreen activity showing a heads-up notification
If you are currently adding sounds and vibrations to your notifications by using the {@link android.media.Ringtone}, {@link android.media.MediaPlayer}, or {@link android.os.Vibrator} classes, remove this code so that the system can present notifications correctly in Do not Disturb mode. Instead, use the {@link android.app.Notification.Builder} methods instead to add sounds and vibration.
Notifications now appear in a small floating window (also called a heads-up notification) when the device is active (that is, the device is unlocked and its screen is on). These notifications appear similar to the compact form of your notification, except that the heads-up notification also shows action buttons. Users can act on, or dismiss, a heads-up notification without leaving the current app.
Examples of conditions that may trigger heads-up notifications include:
If your app implements notifications under those scenarios, make sure that heads-up notifications are presented correctly.
Lockscreens in the L Developer Preview do not show transport controls for your {@link android.media.RemoteControlClient}. Instead, your app can provide media playback control from the lockscreen through a notification. This gives your app more control over the presentation of media buttons, while providing a consistent experience for users across the lockscreen and unlocked device.
The L Developer Preview introduces a new {@code android.app.Notification.MediaStyle} template which is recommended for this purpose. {@code MediaStyle} converts notification actions that you added with {@link android.app.Notification.Builder#addAction(int, java.lang.CharSequence, android.app.PendingIntent) Notification.Builder.addAction()} into compact buttons embedded in your app's media playback notifications.
If you are using the new {@code android.media.session.MediaSession} class (see Media Playback Control below), attach your session token with {@code Notification.MediaStyle.setMediaToken()} to inform the system that this notification controls an ongoing media session.
Call {@code Notification.Builder.setVisibility(Notification.VISIBILITY_PUBLIC)} to mark a notification as safe to show atop any lockscreen (secure or otherwise). For more information, see Lockscreen Notifications.
With the introduction of the new concurrent documents and activities tasks feature in the upcoming release (see Concurrent documents and activities in Recents screen below), the {@link android.app.ActivityManager#getRecentTasks ActivityManager.getRecentTasks()} method is now deprecated to improve user privacy. For backward compatibility, this method still returns a small subset of its data, including the calling application’s own tasks and possibly some other non-sensitive tasks (such as Home). If your app is using this method to retrieve its own tasks, use {@code android.app.ActivityManager.getAppTasks()} instead to retrieve that information.
The L Developer Preview introduces support for 64-bit systems and other preview NDK APIs. The 64-bit enhancement adds needed address space as Android usage diversifies and increases performance while still supporting existing 32-bit apps fully. Use of OpenSSL for cryptography in the platform is also faster. In addition, this release introduces new native audio and media NDK APIs and native OpenGL ES (GLES) 3.1 support.
To use this enhancement, download and install NDK Revision 10 from the Android NDK page. Refer to the Revision 10 release notes for more information about important changes and bug fixes to the NDK.
If you are using the NDK and want to use the features provided in the L Developer Preview, download the {@code android-ndk64-r10} package for your target platform. Due to a known issue, you must still download the 64-bit package even if you only want to compile apps for 32-bit systems. The package also includes the {@code gcc-4.9} compiler for both 32- and 64-bit apps. The L Developer Preview API library is located under the {@code platforms/android-L/} API directory.
The upcoming release adds support for Android's new material design style. You can create apps with material design that are visually dynamic and have UI element transitions that feel natural to users. This support includes:
To learn more about adding material design functionality to your app, see Material Design.
Lockscreens in the L Developer Preview have the ability to present notifications. Users can choose via Settings whether to allow sensitive notification content to be shown over a secure lockscreen.
Your app can control the level of detail visible when its notifications are displayed over the secure lockscreen. To control the visibility level, call {@code android.app.Notification.Builder.setVisibility()} and specify one of these values:
When {@code VISIBILITY_PRIVATE} is set, you can also provide a redacted version of the notification content that hides personal details. For example, an SMS app might display a notification that shows "You have 3 new text messages." but hides the message content and senders. To provide this alternative notification, first create the replacement notification using {@link android.app.Notification.Builder}. When you create the private notification object, attach the replacement notification to it through the {@code Notification.Builder.setPublicVersion()} method.
The L Developer Preview uses metadata associated with your app notifications to sort the notifications more intelligently. To set the metadata, call the following methods in {@code android.app.Notification.Builder} when you construct the notification:
In previous releases, the Recents screen could only display a single task for each app that the user interacted with most recently. Now your app can open more tasks as needed for additional concurrent activities for documents. This feature facilitates multitasking by letting users quickly switch between individual activities and documents from the Recents screen, with a consistent switching experience across all apps. Examples of such concurrent tasks might include open tabs in a web browser app, documents in a productivity app, concurrent matches in a game, or chats in a messaging app. Your app can manage its tasks through the {@code android.app.ActivityManager.AppTask} class.
To insert a logical break so that the system treats your activity as a new task, use {@code android.content.Intent.FLAG_ACTIVITY_NEW_DOCUMENT} when launching the activity with {@link android.app.Activity#startActivity(android.content.Intent) startActivity()}. You can also get this behavior by declaring the <activity> attribute {@code documentLaunchMode="intoExisting"} or {@code ="always"} in your manifest.
You can also mark that a task should be removed from the Recents screen when all its activities are closed. To do this, use {@code android.content.Intent.FLAG_ACTIVITY_AUTO_REMOVE_FROM_RECENTS} when starting the root activity for the task. You can also set this behavior for an activity by declaring the <activity> attribute {@code autoRemoveFromRecents=“true”} in your manifest.
To avoid cluttering the Recents screen, you can set the maximum number of tasks from your app that can appear in that screen. To do this, set the <application> attribute {@code android:maxRecent}. The current maximum that can be specified is 100 tasks per user.
The L Developer Preview updates the {@link android.webkit.WebView} implementation to Chromium M36, bringing security and stability enhancements, as well as bug fixes. The default user-agent string for a {@link android.webkit.WebView} running on the L Developer Preview has been updated to incorporate 36.0.0.0 as the version number.
Additionally, this release brings support for the WebAudio, WebGL, and WebRTC open standards. To learn more about the new features included in this release, see WebView for Android.
The L Developer Preview adds Java interfaces and native support for OpenGL ES 3.1. Key new functionality provided in OpenGL ES 3.1 includes:
The Java interface for OpenGL ES 3.1 on Android is provided with {@code GLES31}. When using OpenGL ES 3.1, be sure that you declare it in your manifest file with the {@code <uses-feature>} tag and the {@code android:glEsVversion} attribute. For example:
<manifest>
<uses-feature android:glEsVersion="0x00030001" />
...
</manifest>
For more information about using OpenGL ES, including how to check the device’s supported OpenGL ES version at runtime, see the OpenGL ES API guide.
In addition to OpenGL ES 3.1, this release provides an extension pack with Java interfaces and native support for advanced graphics functionality. These extensions are treated as a single package by Android. (If the {@code ANDROID_extension_pack_es31} extension is present, your app can assume all extensions in the package are present and enable the shading language features with a single {@code #extension} statement.
The extension pack supports:
The Java interface for the extension pack is provided with {@code GLES31Ext}. In your app manifest, you can declare that support for the extension pack is required, with the {@code <uses-feature>} tag, but the precise syntax is not finalized in the L Developer Preview.
The L Developer Preview introduces the new {@code android.hardware.camera2} API to facilitate fine-grain photo capture and image processing. You can now programmatically access the camera devices available to the system with {@code CameraManager.getCameraIdList()} and connect to a specific device with {@code CameraManager.openCamera()}. To start capturing images, create a {@code CameraCaptureSession} and specify the {@link android.view.Surface} objects for the captured images. The {@code CameraCaptureSession} can be configured to take single shots or multiple images in a burst.
To be notified when new images are captured, implement the {@code CameraCaptureSession.CaptureListener()} interface and set it in your capture request. Now when the system completes the image capture request, your {@code CameraCaptureSession.CaptureListener()} receives a call to {@code onCaptureCompleted()}, providing you with the image capture metadata in a {@code CaptureResult}.
To see an example of how to use the updated Camera API, refer to the {@code Camera2Basic} and {@code Camera2Video} implementation samples in this release.
This release includes the following changes to {@link android.media.AudioTrack}:
You can now build your own media controller app with the new {@code android.media.session.MediaController} class, which provides simplified transport controls APIs that replace those in {@link android.media.RemoteControlClient}. The {@code MediaController} class allows thread-safe control of playback from a non-UI process, making it easier to control your media playback service from your app’s user interface.
You can also create multiple controllers to send playback commands, media keys, and other events to the same ongoing {@code android.media.session.MediaSession}. When you add a controller, you must call {@code MediaSession.getSessionToken()} to request an access token in order for your app to interact with the session.
You can now send transport commands such as "play", "stop", "skip", and "set rating" by using {@code MediaController.TransportControls}. To handle in-bound media transport commands from controllers attached to the session, override the callback methods in {@code MediaSession.TransportControlsCallback}.
You can also create rich notifications that allow playback control tied to a media session with the new {@code android.app.Notification.MediaStyle} class. By using the new notification and media APIs, you will ensure that the System UI knows about your playback and can extract and show album art.
The L Developer Preview extends the Storage Access Framework to let users select an entire directory subtree, giving apps read/write access to all contained documents without requiring user confirmation for each item.
To select a directory subtree, build and send an {@code android.intent.action.OPEN_DOCUMENT_TREE} {@link android.content.Intent}. The system displays all {@link android.provider.DocumentsProvider} instances that support subtree selection, letting the user browse and select a directory. The returned URI represents access to the selected subtree. You can then use {@code DocumentsContract.buildChildDocumentsUriUsingTree()} and {@code DocumentsContract.buildDocumentUriUsingTree()} along with {@code ContentResolver.query()} to explore the subtree.
The new {@code DocumentsContract.createDocument()} method lets you create new documents or directories anywhere under the subtree. To manage existing documents, use {@code DocumentsContract.renameDocument()} and {@code DocumentsContract.deleteDocument()}. Check {@code DocumentsContract.Document.COLUMN_FLAGS} to verify provider support for these calls before issuing them.
If you're implementing a {@link android.provider.DocumentsProvider} and want to support subtree selection, implement {@code DocumentsProvider.isChildDocument()} and include {@code Documents.Contract.FLAG_SUPPORTS_IS_CHILD} in your {@code Root.COLUMN_FLAGS}.
The L Developer Preview also introduces new package-specific directories on shared storage where your app can place media files for inclusion in {@link android.provider.MediaStore}. The new {@code android.content.Context.getExternalMediaDirs()} returns paths to these directories on all shared storage devices. Similarly to {@link android.content.Context#getExternalFilesDir(java.lang.String) Context.getExternalFilesDir()}, no additional permissions are needed by your app to access the returned paths. The platform periodically scans for new media in these directories, but you can also use {@link android.media.MediaScannerConnection} to explicitly scan for new content.
The L Developer Preview provides new multi-networking APIs. These let your app dynamically scan for available networks with specific capabilities, and establish a connection to them. This is useful when your app requires a specialized network, such as an SUPL, MMS, or carrier-billing network, or if you want to send data using a particular type of transport protocol.
To select and connect to a network dynamically from your app follow these steps:
When the system detects a suitable network, it connects to the network and invokes the {@code NetworkCallbackListener.onAvailable()} callback. You can use the {@code android.net.Network} object from the callback to get additional information about the network, or to direct traffic to use the selected network.
Android 4.3 introduced platform support for Bluetooth Low Energy (BLE) in the central role. In the L Developer Preview, an Android device can now act as a Bluetooth LE peripheral device. Apps can use this capability to make their presence known to nearby devices. For instance, you can build apps that allow a device to function as a pedometer or health monitor and communicate its data with another BLE device.
The new {@code android.bluetooth.le} APIs enable your apps to broadcast advertisements, scan for responses, and form connections with nearby BLE devices. You must add the {@code android.permission.BLUETOOTH_ADMIN} permission in your manifest in order for your app to use the new advertising and scanning features.
To begin Bluetooth LE advertising so that other devices can discover your app, call {@code android.bluetooth.le.BluetoothAdvertiser.startAdvertising()} and pass in an implementation of the {@code android.bluetooth.le.AdvertiseCallback} class. The callback object receives a report of the success or failure of the advertising operation.
The L Developer Preview introduces the {@code android.bluetooth.le.ScanFilter} class so that your app can scan for only the specific types of devices it is interested in. To begin scanning for Bluetooth LE devices, call {@code android.bluetooth.le.BluetoothLeScanner.startScan()} and pass in a list of filters. In the method call, you must also provide an implementation of {@code android.bluetooth.le.ScanCallback} to report if a Bluetooth LE advertisement is found.
The L Developer Preview adds these enhancements to enable wider and more flexible use of NFC:
The L Developer Preview provides a new {@code android.app.job.JobScheduler} API that lets you optimize battery life by defining jobs for the system to run asynchronously at a later time or under specified conditions (such as when the device is charging). This is useful in such situations as:
A unit of work is encapsulated by a {@code android.app.job.JobInfo} object. This object provides an exact description of the criteria to be used for scheduling.
Use the {@code android.app.job.JobInfo.Builder} to configure how the scheduled task should run. You can schedule the task to run under specific conditions, such as:
For example, you can add code like this to run your task on an unmetered network:
JobInfo uploadTask = new JobInfo.Builder(mJobId, mServiceComponent)
.setRequiredNetworkCapabilities(JobInfo.NetworkType.UNMETERED)
.build();
JobScheduler jobScheduler =
(JobScheduler) context.getSystemService(Context.JOB_SCHEDULER_SERVICE)
jobScheduler.schedule(uploadTask);
To see an example of how to use the {@code JobScheduler} API, refer to the {@code JobSchedulerSample} implementation sample in this release.
The L Developer Preview provides several new developer tools and APIs to help you better measure and understand your app's power usage.
The {@code dumpsys batterystats} command allows you to generate interesting statistical data about battery usage on a device, organized by unique user ID (UID). The statistics generated by the tool include:
Use the {@code --help} option to learn about the various options for tailoring the output. For example, to print battery usage statistics for a given app package since the device was last charged, run this command:
$ adb shell dumpsys batterystats --charged <package-name>
The Battery Historian tool ({@code historian.par}) analyzes Android bug reports from the L Developer Preview and creates an HTML visualization of power-related events. It can also visualize power consumption data from a power monitor, and attempts to map power usage to the wake locks seen. You can find the Battery Historian tool in {@code <sdk>/tools}.
Figure 2.HTML visualization generated by the Battery Historian tool.
For best results, you should first enable full wake lock reporting, to allow the Battery Historian tool to monitor uninterrupted over an extended period of time:
$ adb shell dumpsys batterystats --enable full-wake-history
You should also reset battery statistics at the beginning of a measurement:
$ adb shell dumpsys batterystats --reset
To generate an HTML visualization:
$ historian.par [-p powerfile] bugreport.txt > out.html
Figure 3. Launcher screen showing managed apps (marked with a lock badge)
The L Developer Preview provides new functionality for running apps within an enterprise environment. A device administrator can initiate a managed provisioning process to add a co-present but separate managed profile to a device, if the user has an existing personal account. Apps that are associated with managed profiles will appear alongside non-managed apps in the user’s Launcher, Recent apps screen, and notifications.
To start the managed provisioning process, send {@code ACTION_PROVISION_MANAGED_PROFILE} in an {@link android.content.Intent}. If the call is successful, the system triggers the {@code android.app.admin.DeviceAdminReceiver. onProfileProvisioningComplete()} callback. You can then call {@code app.admin.DevicePolicyManager. setProfileEnabled()} to enable this managed profile.
If you are developing a Launcher app, you can use the new {@code android.content.pm.LauncherApps} class to get a list of launchable activities for the current user and any associated managed profiles. Your Launcher can make the managed apps visually prominent by appending a “work” badge to the icon drawable with {@code android.os.UserManager. getBadgeDrawableForUser()}.
To see an example of how to use the new functionality, refer to the {@code BasicManagedProfile} implementation sample in this release.
The L Developer Preview introduces a new task locking API that lets you temporarily restrict users from leaving your app or being interrupted by notifications. This could be used, for example, if you are developing an education app to support high stakes assessment requirements on Android. Once your app activates this mode, users will not be able to see notifications, access other apps, or return to the Home screen, until your app exits the mode.
To prevent unauthorized usage, only authorized apps can activate task locking. Furthermore, task locking authorization must be granted by a specially-configured device owner app, through the {@code android.app.admin.DevicePolicyManager.setLockTaskComponents()} method.
To set up a device owner, follow these steps:
$ adb root $ adb shell stop $ rm /tmp/device_owner.xml $ echo "<?xml version='1.0' encoding='utf-8' standalone='yes' ?>" >> /tmp/device_owner.xml $ echo "<device-owner package=\"<your_device_owner_package>\" name=\"*<your_organization_name>\" />" >> /tmp/device_owner.xml $ adb push /tmp/device_owner.xml /data/system/device_owner.xml $ adb reboot
Before using the task locking API in your app, verify that your activity is authorized by calling {@code DevicePolicyManager.isLockTaskPermitted()}.
To activate task locking, call {@code android.app.Activity.startLockTask()} from your authorized activity.
When task locking is active, the following behavior takes effect:
You can now render PDF document pages into bitmap images for printing by using the new {@code android.graphics.pdf.PdfRenderer} class. You must specify a {@link android.os.ParcelFileDescriptor} that is seekable (that is, the content can be randomly accessed) on which the system writes the the printable content. Your app can obtain a page for rendering with {@code openPage()}, then call {@code render()} to turn the opened {@code PdfRenderer.Page} into a bitmap. You can also set additional parameters if you only want to convert a portion of the document into a bitmap image (for example, to implement tiled rendering in order to zoom in on the document).
The L Developer Preview adds the following support for testing and accessibility:
Beginning in the L Developer Preview, users can more easily switch between all input method editors (IME) supported by the platform. Performing the designated switching action (usually touching a Globe icon on the soft keyboard) will cycle among all such IMEs. This change takes place in {@link android.view.inputmethod.InputMethodManager#shouldOfferSwitchingToNextInputMethod InputMethodManager.shouldOfferSwitchingToNextInputMethod()}.
In addition, the framework now checks whether the next IME includes a switching mechanism at all (and, thus, whether that IME supports switching to the IME after it). An IME with a switching mechanism will not cycle to an IME without one. This change takes place in {@link android.view.inputmethod.InputMethodManager#switchToNextInputMethod InputMethodManager.switchToNextInputMethod}.
To see an example of how to use the updated IME-switching APIs, refer to the updated soft-keyboard implementation sample in this release.
The following values are now supported in the {@code <uses-feature>} element, so you can ensure that your app is installed only on devices that provide the features your app needs.
<uses-feature android:name="android.software.leanback"
android:required="true" />
<uses-feature android:name="android.software.webview"
android:required="true" />
For a detailed view of all API changes in the L Developer Preview, see the API Differences Report.