Separate declaration from approval
android.permission.SYSTEM_ALERT_WINDOW is the relevant manifest declaration for this capability. The app still needs to use the platform's special-access flow where required. A call to a generic runtime permission launcher is not the correct replacement.
The special-permissions guide describes the pattern: check access, explain the feature, open the appropriate settings screen and recheck when the app resumes.
Check before displaying an overlay
val allowed = Settings.canDrawOverlays(context)
For supported versions, use the documented overlay settings intent with your package when appropriate. Resolve or safely handle the settings activity; OEM interfaces can differ. Do not assume an activity result code means the user granted access.
Design the return path
| User action | Expected app behavior |
|---|---|
| Grants access | Recheck and offer to start the overlay feature |
| Cancels or presses Back | Keep the feature disabled without an error loop |
| Later revokes access | Stop or safely fail the next overlay operation |
| Device restricts the feature | Explain the limitation without suggesting a bypass |
The explanation should name the overlay's visible purpose. “Required for better experience” is not enough for a capability that can cover other applications.
Avoid deceptive or obstructive UI
Keep overlays dismissible and do not use them to imitate system dialogs, capture unrelated credentials or interfere with another app's security-sensitive controls. An approved permission does not authorize deceptive behavior.
Verify the final declaration and implementation
APKLint's Dangerous Permissions Checker can flag overlay access for review. It cannot assess every rendered overlay or verify a device's current grant. Test the complete feature on representative devices and confirm that the release handles denial and revocation without crashing or repeatedly redirecting to settings.
Keep a floating timer subordinate to the user's task
Suppose an app offers a small floating timer while another app is open. Explain that visible purpose before requesting special access, and let the user start and dismiss the overlay deliberately. A grant should enable the capability; it should not cause a hidden startup path to display a window at every future launch.
The Settings API reference documents the access check. Recheck the actual state after the settings flow. A successful activity launch, a callback or the user's return to your screen does not establish that overlay access was enabled.
Remove the window when the feature stops
Start the timer, rotate the device and stop it through the overlay's visible control. Verify that exactly one window remains during the supported transitions and that none remains after stopping. A configuration change should not register another window while leaving the earlier instance attached.
Test revocation while the feature is active and again before a new start. Handle a failed window operation by returning to a clear disabled state instead of crashing or reporting that the timer is still visible. Keep resource ownership explicit so cleanup can remove only the window belonging to that session.
Check the overlay on small and large screens, with enlarged text and alongside system navigation. Ensure the dismiss control remains reachable and the window does not obstruct essential actions in the underlying app. Test dragging or positioning limits so a saved position cannot place the only close control outside the usable display after rotation.
Keep the overlay visually identifiable as part of your application. Do not imitate a system permission prompt or solicit credentials for another app. Restrict any displayed information to what the timer feature needs, and avoid logging unrelated screen contents as a debugging shortcut.
When the feature can be served by an ordinary notification or an in-app surface, evaluate that narrower design before adding special access. If an overlay remains necessary, record the supported device versions and the exact denial, revocation and cleanup behavior tested. APK inspection can establish that the declaration exists; the rendered interaction and window lifecycle determine whether this particular feature behaves correctly.
Sources and further reading
Reference review: 29 September 2026. Examples illustrate the workflow; check your installed versions, release artifact and account-specific Console requirements before applying them. This guide is not a claim that APKLint executed your project or verified your private account.
Android inspection tools and practical release guides. About APKLint · Report a correction
