To implement a consistent and high-quality user experience, and to prevent issues that lead to Compatibility Test Suite (CTS) failures, implement the core WindowManager (WM) principles described here. These principles apply to:
Android releases that use a multi-window architecture, which was started in Android 14 and continued in Android 15 with Scalable UI.
Android Scalable UI and your own custom implementations
By applying the principles, you'll proactively avoid most CTS compliance and functional test issues.
Terminology
- invariant
- A logical condition that remains true throughout the execution of an app that leads to structural integrity. An invariant acts as a boundary rule.
- special activity
- Also known as Auto UI activity or System UI activity, this critical app activity has a dedicated area on the screen that's either always visible or is visible most of the time, even when the user presses Home, such as a primary navigation or cluster app.
- standard activity
- Any standard app activity that isn't critical to the system's core user interface, such as a third-party media app launched from the app grid.
WM principles
To maximize CTS compliance, apply these principles in your WM implementations.
Use a stable configuration on activity launch
Launch every new standard activity with a single WM transition that sets its final position, size, and density. You must not trigger a second transition that changes the underlying task's window configuration (such as size or density) immediately after the first, as this causes a config change immediately after the activity is created.
Move standard activities to the stopped state
When the user navigates to the home task or home scene, you must move all running standard activities to the stopped state to maintain the predictable Android app lifecycle required by CTS tests.
Prevent the obscuring of standard activity content
Don't draw any custom decorations or UI elements that obstruct the content of
a standard activity. If you draw custom overlays (such as a custom climate
control bar), you must report the dimensions to the system with SystemOverlay
insets. For Android 15 and higher, use DecorPanel in Scalable UI.
Hide overlays on immersive mode request
When an app requests immersive mode, you must hide any temporary custom UI
elements and remove their SystemOverlayinsets. Persistent obstructions
interfere with an app's pixel expectations.
Apply rounded corners only at the display level
Apply rounded corners only at the display level using the appropriate resource
configurations in frameworks/base. Don't apply arbitrary rounded corners to
the surface of a standard activity.
Doing so interferes with UI element tests. As a temporary measure, you can specify the same rounded corner radius for the display as you apply to the surface of the standard activity.
Maintain app size on immersive mode request
When an app requests to enter immersive mode, don't resize the app's window. Doing so triggers a disruptive configuration change. Instead, to maximize the app, offer a user-controlled fullscreen button.