避坑指南：Android自定义悬浮窗/系统弹窗开发，那些WMS权限校验与WindowToken的坑
Android悬浮窗开发实战：WMS权限校验与WindowToken避坑指南
在移动应用开发中，悬浮窗功能因其独特的交互体验被广泛应用于视频播放器、快捷工具和系统辅助功能中。然而，从Android 8.0开始，Google逐步收紧了对系统窗口的管理策略，开发者常会遇到ADD_BAD_APP_TOKEN错误或窗口无法显示的权限问题。本文将深入解析WindowManagerService的窗口添加机制，揭示那些官方文档未曾明说的实现细节。
1. 系统窗口权限体系解析
Android的窗口管理系统采用分层权限控制，不同类型的窗口对应不同的权限要求。理解这套体系是避免开发陷阱的第一步。
关键权限矩阵对比：
| 窗口类型 (TYPE) | 所需权限 | 最低API要求 | 用户手动授权 | 特殊限制 |
|---|---|---|---|---|
| APPLICATION_OVERLAY | SYSTEM_ALERT_WINDOW | 26+ | 是 | 必须设置android:targetSdkVersion≥26 |
| TOAST | 无 | 1+ | 否 | 内容受限，不能自定义布局 |
| SYSTEM_ALERT | SYSTEM_ALERT_WINDOW | 1+ | 否(API<23) | 在后台时可能被系统移除 |
| PHONE | 无 | 1+ | 否 | 仅限通话场景使用 |
在代码层面，权限校验发生在两个关键环节：
unprivilegedAppCanCreateTokenWith()检查应用是否具备创建特定类型窗口的资格validateAddingWindowLw()验证窗口参数是否符合当前策略
// 典型权限检查代码路径 if (!mService.mAtmService.mAppOpsService.checkOperation( AppOpsManager.OP_SYSTEM_ALERT_WINDOW, callingUid, attrs.packageName)) { return WindowManagerGlobal.ADD_PERMISSION_DENIED; }提示：从Android 11开始，即使用户授予了SYSTEM_ALERT_WINDOW权限，应用在后台时仍然无法显示悬浮窗，这是为保护用户隐私新增的限制。
2. WindowToken机制深度剖析
WindowToken是连接应用窗口与系统服务的桥梁，理解它的工作原理能解决90%的窗口添加失败问题。
常见Token相关错误码：
ADD_BAD_APP_TOKEN：无效或缺失的窗口令牌ADD_BAD_SUBWINDOW_TOKEN：子窗口使用了错误的父窗口令牌ADD_NOT_APP_TOKEN：非应用窗口使用了Activity的Token
创建合规Token的实践方案：
- 对于Activity关联窗口：
// 使用Activity的WindowToken val params = WindowManager.LayoutParams( width, height, WindowManager.LayoutParams.TYPE_APPLICATION, flags, PixelFormat.TRANSLUCENT ) windowManager.addView(myView, params) // 自动使用Activity的Token- 对于系统级悬浮窗：
val params = WindowManager.LayoutParams( width, height, WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY, WindowManager.LayoutParams.FLAG_NOT_FOCUSABLE, PixelFormat.TRANSLUCENT ).apply { token = null // 系统窗口必须显式设置为null packageName = context.packageName } if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { params.token = myView.applicationWindowToken }- 跨进程窗口的特殊处理： 当需要从Service或广播接收器显示窗口时，必须确保：
- 持有有效的Context
- 正确设置packageName
- 处理不同Android版本的Token策略差异
3. 版本兼容性实战方案
Android各版本对窗口管理的修改往往导致兼容性问题，以下是关键变更点及应对策略：
Android 8.0+：
- 废弃TYPE_PHONE，强制使用TYPE_APPLICATION_OVERLAY
- 必须动态请求SYSTEM_ALERT_WINDOW权限
- 新增悬浮窗位置限制
Android 10+：
- 后台显示限制
- 必须设置android:showWhenLocked才能在全屏Activity上显示
Android 12+：
- 精确位置权限(ACCESS_FINE_LOCATION)成为必须
- 新增"显示在其他应用上层"的独立权限控制
兼容代码示例：
fun checkOverlayPermission(context: Context): Boolean { return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) { Settings.canDrawOverlays(context) } else { AppOpsManagerCompat.checkOpNoThrow( context, AppOpsManager.OP_SYSTEM_ALERT_WINDOW, Process.myUid(), context.packageName ) == AppOpsManager.MODE_ALLOWED } } fun requestOverlayPermission(activity: Activity, requestCode: Int) { if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) { val intent = Intent( Settings.ACTION_MANAGE_OVERLAY_PERMISSION, Uri.parse("package:${activity.packageName}") ) activity.startActivityForResult(intent, requestCode) } }4. 高级调试技巧与性能优化
当窗口仍然无法正常显示时，这些调试方法能快速定位问题根源：
- ADB命令诊断：
# 查看当前所有窗口层级 adb shell dumpsys window windows # 检查权限状态 adb shell appops get <package-name> SYSTEM_ALERT_WINDOW # 模拟权限授予 adb shell appops set <package-name> SYSTEM_ALERT_WINDOW allow- 日志过滤技巧： 在Logcat中过滤以下标签：
- WindowManager
- AppOps
- ActivityTaskManager
- 性能优化要点：
- 避免频繁添加/移除窗口
- 使用SurfaceView替代TextureView用于视频悬浮窗
- 合理设置FLAG_LAYOUT_NO_LIMITS减少布局计算
- 对于静态悬浮窗，考虑使用SYSTEM_ALERT类型减少权限要求
窗口类型选择决策树：
- 是否需要用户交互？ → 是：考虑对话框或Activity
- 是否需要全屏覆盖？ → 是：使用SYSTEM_ALERT(需权限)
- 是否仅需简单提示？ → 是：使用Toast
- 是否需长期显示？ → 是：TYPE_APPLICATION_OVERLAY
- 是否跨进程显示？ → 是：确保正确的Context和Token
在实现一个电商应用的"商品悬浮比价"功能时，我们发现TYPE_APPLICATION_OVERLAY在Android 12上会出现意外关闭。通过分析WMS源码，最终定位到是未正确处理FLAG_KEEP_SCREEN_ON导致的窗口优先级问题。这个案例告诉我们，即使遵循了所有官方规范，仍需要针对特定场景做深入测试。