Implement heads up notification panels

In Android 17 and higher, Scalable UI for heads-up notifications (HUNs) lets you customize the window management (positioning, background scrim, animations) of HUN panels using the Scalable UI framework with runtime resource overlays (RROs). This feature allows control over the container of the notification without affecting the internal content rendering.

Implementation

The implementation of Scalable UI for HUNs involves the following:

  • Public and system APIs: Introduces the HunWindow class and <HunPanel> XML tag parsing logic within the Scalable UI parsers.
  • Partner implementation:
    • Define a custom RRO overlay.
    • To create an XML file (for example, res/xml/hun_panel.xml), use the <HunPanel> root tag.
    • Define <Variant> elements to control bounds, gravity (TOP or BOTTOM), visibility, and background (scrim drawable).
    • Map variants to system events (for example, _System_Show_Panel) using <Transitions>.
  • New versus upgrading devices: This is a configuration change made by RROs. To upgrade devices to receive the new system image, create an appropriate RRO to define HUN behavior. This lets users deviate from the default.
  • Enable or disable: To enable or disable this feature, add or remove @xml/hun_panel from the window_states configuration.
  • Default settings: Alter default settings by applying your own RRO that overrides the system default configuration.

Requirements and validation

Use the following sequence to test enabling and disabling overlays:

adb shell cmd overlay disable --user current com.example.overlay.scalableUI.hun.bottom

If you enable or disable the RRO, the HUN is shown at the bottom or top, respectively.

Manual validation

  • Positioning: Verify HUNs appear at the specified gravity (TOP or BOTTOM) and bounds.
  • Interactions: Verify that swiping to dismiss works (if not dismissible, verify that the button works).
  • Animations: Verify transition animations between open and closed states.