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.
Sources and further reading
Reference review: 22 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
