Supporting display cutouts on edge-to-edge screens


Posted By Megan Potoski, Product Manager, Android System UI

Smartphones are quickly moving towards smaller bezels and larger aspect ratios. On these devices, display cutouts are a popular way to achieve an edge-to-edge experience while providing space for important sensors on the front of the device. There are currently 16 cutout devices from 11 OEMs already released, including several Android P beta devices, with more on the way.

These striking displays present a great opportunity for you to showcase your app. They also mean it’s more important than ever to make sure your app provides a consistently great experience across devices with one or two display cutouts, as well as devices with 18:9 and larger aspect ratios.

Examples of cutout devices: Essential PH-1 (left) and Huawei P20 (right).

Make your app compatible with display cutouts

With many popular and upcoming devices featuring display cutouts, what can you do to make sure your app is cutout-ready?

The good news is, for the most part your app should work as intended even on a cutout device. By default, in portrait mode with no special flags set, the status bar will be resized to be at least as tall as the cutout and your content will display in the window below. In landscape or fullscreen mode, your app window will be letterboxed so that none of your content is displayed in the cutout area.

However, there are a few areas where your app could have issues on cutout devices.

  • Watch out for any sort of hard-coding of status bar height — this will likely cause problems. If possible, use WindowInsetsCompat to get status bar height.
  • In fullscreen, be careful to consider when to use window vs. screen coordinates, as your app will not take up the whole screen when letterboxed. For example, if you use MotionEvent.getRawX/Y() to get screen coordinates for touch events, make sure to transform them to the view’s coordinates using getLocationOnScreen().
  • Pay special attention to transitions in and out of fullscreen mode.

Here are a few guidelines describing what issues to look out for and how to fix them.

Take advantage of the cutout area

Rendering your app content in the cutout area can be a great way to provide a more immersive, edge-to-edge experience for users, especially for content like videos, photos, maps, and games.

An example of an app that has requested layout in the display cutout.

In Android P we added APIs to let you manage how your app uses the display cutout area, as well as to check for the presence of cutouts and get their positions.

You can use layoutInDisplayCutoutMode, a new window layout mode, to control how your content is displayed relative to the cutout. By default, the app’s window is allowed to extend into the cutout area if the cutout is fully contained within a system bar. Otherwise, the window is laid out such that it does not overlap with the cutout. You can also set layoutInDisplayCutoutMode to always or never render into the cutout. Using SHORT_EDGES mode to always render into the cutout is a great option if you want to take advantage of the full display and don’t mind if a bit of content gets obscured by the cutout.

If you are rendering into the cutout, you can use getDisplayCutout() to retrieve a DisplayCutout that has the cutout’s safe insets and bounding box(es). These let you check whether your content overlaps the cutout and reposition things if needed.

<style name="ActivityTheme"> <item name="android:windowLayoutInDisplayCutoutMode"> default/shortEdges/never </item>
</style>

Attribute for setting layoutInDisplayCutoutMode from the Activity’s theme.

For devices running Android 8.1 (API 27), we’ve also back-ported the layoutInDisplayCutoutMode activity theme attribute so you can control the display of your content in the cutout area. Note that support on devices running Android 8.1 or lower is up to the device manufacturer, however.

To make it easier to manage your cutout implementation across API levels, we’ve also added DisplayCutoutCompat in the AndroidX library, which is now available through the SDK manager.

For more about the display cutout APIs, take a look at the documentation.

Test your app with cutout

We strongly recommend testing all screens and experiences of your app to make sure that they work well on cutout devices. We recommend using one of the Android P Beta Devices that features a cutout, such as the Essential PH-1.

If you don’t have a device, you can also test using a simulated cutout on any device running Android P or in the Android Emulator. This should help you uncover any issues that your app may run into on devices with cutouts, whether they are running Android 8.1 or Android P.

What to expect on devices with display cutouts

Android P introduces official platform support for display cutouts, with APIs that you can use to show your content inside or outside of the cutout. To ensure consistency and app compatibility, we’re working with our device manufacturer partners to mandate a few requirements.

First, devices must ensure that their cutouts do not negatively affect apps. There are two key requirements:

  • In portrait orientation, with no special flags set, the status bar must extend to at least the height of the cutout.
  • In fullscreen or landscape orientation, the entire cutout area must be letterboxed.

Second, devices may only have up to one cutout on each short edge of the device. This means that:

  • You won’t see multiple cutouts on a single edge, or more than two cutouts on a device.
  • You won’t see a cutout on the left or right long edge of the device.

Within these constraints, devices can place cutouts wherever they want.

Special mode

Some devices running Android 8.1 (API level 27) or earlier may optionally support a “special mode” that lets users extend a letterboxed fullscreen or landscape app into the cutout area. Devices would typically offer this mode through a toggle in the navigation bar, which would then bring up a confirmation dialog before extending the screen.

Devices that offer “special mode” allow users to optionally extend apps into the cutout area if supported by the app.

If your app’s targetSdkVersion is 27 or higher, you can set the layoutInDisplayCutoutMode activity theme attribute to opt-out of special mode if needed.

Don’t forget: larger aspect ratios too!

While you are working on cutout support, it’s also a great time to make sure your app works well on devices with 18:9 or larger aspect ratios, especially since these devices are becoming increasingly common and can feature display cutouts.

We highly encourage you to support flexible aspect ratios so that your app can leverage the full display area, no matter what device it’s on. You should test your app on different display ratios to make sure it functions properly and looks good.

Here are some guidelines on screens support to keep in mind as you are developing, also refer to our earlier post on larger aspect ratios for tips on optimizing. If your app can’t adapt to the aspect ratios on long screens, you can choose to declare a max aspect ratio to request letterboxing on those screens.

Thanks for reading, and we hope this helps you deliver a delightful experience to all your users, whatever display they may have!

AndroidX Development is Now Even Better


Posted by Aurimas Liutikas, software engineer on AndroidX team

AndroidX (previously known as Android Support Library) started out as a small set of libraries intended to provide backwards compatibility for new Android platform APIs and, as such, its development was strictly tied to the platform. As a result, all work was done in internal Google branches and then pushed to the public Android Open Source Project (AOSP) together with the platform push. With this flow, external contributions were limited to a narrow window of time where the internal and AOSP branches were close in content. On top of that, it was difficult to contribute — in order to do a full AndroidX build and testing, external developers had to check out >40GB of the full Android platform code.

Today, the scope of AndroidX has expanded dramatically and includes libraries such as AppCompat for easier UI development, Room for database management, and WorkManager for background work. Many of these libraries implement higher-level abstractions and are less tied to new revisions of the Android platform, and all libraries are designed with backwards compatibility in mind from the start. Several libraries, such as RecyclerView and Fragment, are purely AndroidX-side implementations with few ties to the platform.

Starting a little over two years ago, we began a process of unbundling — moving AndroidX out of Android platform builds into its own separate build. We had to do a great deal of work, including migrating our builds from make to Gradle as well as migrating all of our API tracking tools and documentation generation out of the platform build. With that process completed, we reached a point where a developer can now check out a minimal AndroidX project, open it in Android Studio, and build using the public SDK and public Android Gradle Plugin.

The Android developer community has long expressed a desire to contribute more easily to AndroidX; however, this was always a challenge due to the reasons described above. This changes today: AndroidX development is moving to public AOSP. That means that our primary feature development (except for top-secret integrations with the platform 😀) and bug fixes will be done in the open using the r.android.com Gerrit review tool and changes will be visible in the aosp/androidx-master-dev branch.

We are making this change to give better transparency to developers; it gives developers a chance to see features and bug fixes implemented in real-time. We are also excited about receiving bug fix contributions from the community. We have written up a short guide on how to go about contributing a patch.

In addition to regular development, AOSP will be a place for experimentation and prototyping. You will see new libraries show up in this repository; some of them may be removed before they ship, change dramatically during pre-alpha development, or merge into existing libraries. The general rule is that only the libraries on maven.google.com are officially ready for external developer usage.

Finally, we are just getting started. We apologize for any rough edges that you might have when contributing to AndroidX, and we request your feedback via the public AndroidX tracker if you hit any issues.

Final preview update, official Android P coming soon!


Posted By Dave Burke, VP of Engineering

Android P is almost here! As we put the finishing touches on the new platform, today we’re bringing you Android P Beta 4.

Beta 4 is the last preview milestone before we launch the official Android P platform later this summer. Take this opportunity to test your apps and publish updates, to make sure you offer a great experience for users transitioning to Android P!

What’s in this update?

Today’s Beta 4 update includes a release candidate build with final system behaviors and the official Android P APIs (API level 28), available since Beta 2. It includes everything you need to wrap up your testing in time for the upcoming official Android P release.

Get your apps ready for Android P

With the consumer launch coming soon, it’s important to test your app for compatibility with Android P. Just install your current app from Google Play on an Android P Beta device or emulator. As you work through the flows, make sure your app runs and looks great, and that it handles the Android P behavior changes properly.

Also watch for uses of non-SDK interfaces in your app. Android P restricts access to selected non-SDK interfaces, so you should reduce your reliance on them. See our recent post for details..

After you’ve made any necessary updates, we recommend publishing to Google Play right away without changing the app’s platform targeting. This lets you ensure a great experience for Android P users while you work on enhancing your app with Android P APIs and targeting.

Enhance your app with Android P features and APIs

When you’re ready, dive into Android P and learn about the new features and APIs that you can use in your apps, like multi-camera support, display cutout, enhanced notifications, ImageDecoder, TextClassifier, and others.

To build with the new APIs, just download the official API 28 SDK and tools into Android Studio 3.1, or use the latest version of Android Studio 3.2. Then update your project’s compileSdkVersion and targetSdkVersion to API 28. When you change your targeting, make sure your app supports all of the applicable behavior changes.

As soon as you’re ready, publish your APK updates that are compiled against, or optionally targeting, API 28. A common strategy is to use Google Play’s beta testing feature to get early feedback from a small group of users and then do a staged rollout to production.

Visit the Developer Preview site for details and documentation. Also check out this video and the Google I/O Android playlist for more on what’s new in Android P for developers.

How do I get Beta 4?

It’s easy – you can get Android P Beta 4 on Pixel devices by enrolling here. If you’re already enrolled in our Android Beta program, you’ll automatically get the Beta 4 update soon. As always, downloadable system images for Pixel devices are also available. Partners who are participating in the Android P Beta program will also be updating their devices to Beta 4 over the coming weeks.

What’s next?

Stay tuned for the official Android P launch coming soon! You can continue to share your feedback or requests in the meantime, and feel free to use our hotlists for platform issues, app compatibility issues, and third-party SDK issues.

Thanks for your feedback so far, and thank you to everyone who participated in our recent Reddit AMA on r/androiddev!

Updating your games for modern Android


Posted by Tom Greenaway, Senior Partner Developer Advocate

Last year we announced that starting from August 2018 Google Play will require all new apps and games to target a recent Android API level – set to API level 26 (Android 8.0 Oreo), or higher. Additionally, this requirement will extend to updates for existing apps and games starting from November 2018.

Every new Android version introduces changes that bring significant security and performance improvements – and enhance the user experience of Android overall. Updating your games to target the latest API level ensures that your users can benefit from these improvements, while still allowing your games to run on older Android versions.

Simple next steps:

  • Install the Android 8.0 Oreo SDK (API level 26) via Android Studio by navigating to (Tools > Android > SDK Manager > Android SDK > SDK Platforms).
  • Update your game to target API level 26 and see whether your game has any incompatibilities or issues as soon as possible. Update any external dependencies as necessary. Learn more about the incremental changes between versions of Android here.
  • If you are using an advertising network, SDK or plugin which is incompatible with API level 26, reach out to your contacts and find out their timeline for supporting target API level 26. The sooner they’re aware of these changes the better.
  • If you build your game with Unity, support for target API 26 is built into Unity 5.6.6 and beyond. Simply ensure the latest target API level is selected in your Android build settings for Unity (Build Settings > Android > Player Settings). For versions of Unity 5.6.5 and prior, consult this documentation which includes a workaround for versions dating back to 4.3.
  • For games built with Unreal, check your Android platform settings has the “Target SDK Version” set to 26.
  • If you use Cocos2D-X, check the target API level in the gradle.properties file that is generated.

Significant changes to be aware of:

  • Since API 23, we have required permissions be requested at runtime which helps streamline the app install process.
  • Since API 24, apps can no longer dynamically link against non-NDK libraries. If your app (including third-party static libraries) contains native code, you should only be using public NDK APIs.
  • If your game uses Android push notifications, the Google Play Services SDK in your game will need to be updated to version 10.2.1 or above for your game to support API level 26.
  • If your game uses opaque binary blobs (OBB), then your game must check if it can access the directory before attempting to access the OBB files themselves. We recommend explicitly requesting permission for access using the Runtime Permissions API, and gracefully handling cases wherein the permission is not granted. Additionally, add an entry in the manifest for the external storage access:
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    

Moving ahead

Remember, updating the target API level is just the first step – make sure your game is compatible with the behavior changes between your current target API level and API level 26. Check out further guidance on the changes in past versions of Android to help in your migration process. These policy changes are important for moving the Android ecosystem forward and keeping it healthy for our users – and yours.

How useful did you find this blog post?

How creating an Action can complement your Android app


Posted by Neto Marin – Actions on Google Developer Advocate

There are millions of apps in the Android ecosystem, so helping yours get discovered can require some investment. Your app needs to offer something that differentiates it from other similar apps to stand out to users.

Building a companion Action is a fast and simple way to increase your Android app’s potential reach by creating a new entrypoint from devices covered by the Google Assistant. This lets you bring your services to users without needing to install anything through voice, and can bring people into your app when it can provide more value.

Your companion Action complements your Android app’s experience by offering some of your services through the Google Assistant, which is available on more than 500 million devices including speakers, phones, cars, headphones, and more. Creating an Action provides a frictionless way for users to start engaging with your services wherever the Google Assistant is available.

Creating an Action for the Assistant will extend your brand presence, bringing your services to new devices and contexts as users interact with the Google Assistant.

Feature what your app does better

It is probably a mistake to try to rewrite all of your Android app as a conversational Action, since voice is a different modality with different constraints and usage patterns. Instead, you should start by selecting the most important or popular features in your app that translate well into a voice context and can be more easily accomplished there. Then, you can create your conversational experience to offer these features on Google Assistant devices. Check out the Conversation design site, which has several articles and guides about how to create a great voice UI.

Let’s take a look at a hypothetical example. Imagine you have a mobile commerce app. Some features include searching for products, navigating to different categories, adding payment information, and checking out. You could build an Action for the Assistant with most of the same functionality, but we encourage you to look for what makes the most sense in a conversational experience.

In this case, your Action could focus on everything that a user would want to know after they’ve purchased a product through your Android app or web page. You could offer a quick way to get updates about a purchase’s status (if you provide different states for payment/purchase process) and shipment information, or provide an interface for re-ordering a user’s favorite products. Then, your users would be able to ask something like, “Hey Google, ask Voice Store about my last purchase.”

Or, to reach users who have never made a purchase before, you could create an Action to offer exciting deals for common products. For example, you could create an Action that is invoked with, “Hey Google, ask Voice Store what are the deals on TVs today”.

As you can see, starting with a “hero” use case for your Action is an exciting way to introduce conversational features that complement your Android app, and it will take less time than you think.

At Google I/O 2018, we presented a talk, “Integrating your Android apps with the Google Assistant” which contains more details and examples for developers.

Delivering user’s purchases across surfaces

In-app purchases, subscriptions, and one-time products have proven successful for Android developers when it comes to monetization, allowing developers to offer different kinds of digital goods and additional value for paying users. These types of monetization are proven to drive user conversion and make the app more profitable.

Google Play Billing offers a series of tools, APIs, and documentation to help developers manage the subscription life-cycle, build server-side validation, and much more. If you are new to in-app billing, check out the Google Play Billing Overview page.

Now, Android developers can expand where users can access these goods or upgraded experiences by offering them through Actions, as well. This expansion is accomplished by honoring the user’s entitlements on Google Play across different surfaces and devices, reaching users when they can’t (or don’t want to) use an app, like while cooking or driving.

For non-Android platforms, you’ll need to ask your users to link their accounts. You can then use your user’s account history to identify what purchases they’ve made on other surfaces.

Check the Accessing Digital Purchases page for a step-by-step guide on how to enable access to the user’s purchases and request and parse the purchase data.

What’s next?

If you are not familiar with Actions on Google yet, start by checking out our overview page, which describes the platform in detail and tells you all you need to know to create your Actions for the Google Assistant.

Stay tuned for more posts about how to improve your Android app experience with Actions on Google.

Thanks for reading!

Android Emulator – AMD Processor & Hyper-V Support


Posted by Jamal Eason, Product Manager, Android

Since the major revamp of the Android Emulator two years ago, we have focused on delivering a fast and feature-rich emulator to help you build great app experiences for users. Today, the Android Emulator is the top device deployed to from Android Studio — more than 2x over physical Android devices. We are humbled to hear from many of you that the Android Emulator has come a long way, but we are not done yet.

Making the Android Emulator faster is one of the top priorities for the Android Studio team. Over the last few releases, we have launched quick boot & emulator snapshots for quickly starting and resuming emulator sessions in under 2 seconds. Up until now, our emulator experience has almost universally worked on macOS® and Linux computers. But for users of Microsoft® Windows® or the Microsoft® Hyper-V platform, our hardware accelerated speed enhancements for the Android Emulator only worked with computers with Intel® processors. Support for AMD® processors and Microsoft Hyper-V hypervisor are two long-standing user requests from the Android developer community that we are happy to address with this Android Emulator update.

Today, you can download the latest Android Emulator release, which is enabled to run x86 based Android Virtual Devices (AVD) on computers that use AMD processors. This exciting update makes the Android Emulator more accessible to a new set of Android app developers that were previously limited to software emulation, but can now have hardware accelerated performance. Moreover, for those of you who use Hyper-V to run your local app backend, the Android Emulator can now also coexist with other Hyper-V-backed applications on Windows® 10.

Thanks to a new Microsoft Windows Hypervisor Platform (WHPX) API and recent open-source contributions from Microsoft, even more Android app developers can take advantage of all the speed improvements and features in the Android Emulator.

Android Emulator running on Windows 10 with AMD Processor
Screenshot Configuration: Asus ROG Strix GL 702ZC, Processor: AMD® Ryzen 7 1700 Processor, Chipset: AMD 5350, Graphics: AMD® Radeon RX580

Support for these technologies was initially available in the v27.3.8 Android Emulator canary release and today we are releasing this set of preview features (AMD processor & Hyper-V support) on the stable channel for more feedback. Alongside this update, we have added additional speed improvements in loading emulator snapshots for those developers using the Intel® Hardware Accelerated Execution Manager (HAXM).

How to use

Linux

If you use Linux for Android app development, the Android Emulator will continue to use the native Kernel-based Virtual Machine (KVM) hypervisor for both Intel and AMD based computers for a fast and performant virtualization solution. An update to the v27.3.8 Android Emulator will offer you the new snapshots UI along with improvements to performance, reliability and resource usage.

macOS

For OS X v10.10 Yosemite and higher, the Android Emulator uses the built-in Hypervisor.Framework by default, and falls back to using the Intel Hardware Accelerated Execution Manager (HAXM) if Hypervisor.Framework fails to initialize (such as when running on OS X v10.9 or earlier). Once you update to the latest Android Emulator on macOS, you will also have access to the new snapshots UI along with under the hood performance and reliability improvements.

Android Emulator – Snapshots Extended Controls

Microsoft Windows

On Intel x86-based computers, the Android Emulator will continue to use Intel HAXM by default. Intel HAXM is a mature and open-sourced hypervisor solution developed by Intel. Thanks to on-going development by Intel, the fastest emulator performance on Windows is still with Intel HAXM. To download the latest Intel HAXM v7.2.0, check for updates in the Android SDK Manager.

If you have an AMD processor in your computer you need the following setup requirements to be in place:

  • AMD Processor – Recommended: AMD® Ryzen processors
  • Android Studio 3.2 Beta or higher – download via Android Studio Preview page
  • Android Emulator v27.3.8+ – download via Android Studio SDK Manager
  • x86 Android Virtual Device (AVD) – Create AVD
  • Windows 10 with April 2018 Update
  • Enable via Windows Features: “Windows Hypervisor Platform”

Windows Hypervisor Platform setting in Windows 10

If you want to use Hyper-V at the same time as the Android Emulator on your Intel processor-based computer, you will also need the same Android Studio and Android Emulator versions as listed above, but with the additional requirements:

  • Enable via Windows Features: “Hyper-V” – Only available for Windows 10 Professional/Education/Enterprise
  • Intel Processor : Intel® Core processor that supports Virtualization Technology (VT-x), Extended Page Tables (EPT), and Unrestricted Guest (UG) features. Additionally VT-x needs to be enabled in the BIOS.

For more setup tips and troubleshooting details, check out the documentation page.

Again, for existing Windows users who have an Intel-based processor, the Android Emulator will continue to use the faster and recommended Intel HAXM configuration. For those using AMD processors, and those who use Hyper-V hypervisors, this should be an exciting step forward to start using the Android Emulator.

Next Steps & Feedback

Download the latest Android Emulator from the Android Studio 3.2 Beta SDK Manager for the latest performance updates across all supported platforms that you are using. We are going to continue to invest in performance improvements for each of the platforms and we look forward to your feedback and feature requests.

If you find a bug or issue, feel free to file an issue. Connect with us — the Android Studio development team ‐ on our Google+ page or on Twitter.