XXPermissions项目中targetSdk<31应用的蓝牙权限适配问题解析

在Android开发中，权限管理一直是开发者需要重点关注的领域。近期在XXPermissions权限管理框架中发现了一个值得注意的问题：当应用的targetSdkVersion低于31时，在高版本Android系统（特别是Android 12及以上）上申请BLUETOOTH_CONNECT权限会出现兼容性问题。

问题现象

开发者在使用XXPermissions框架时发现，在realme GT5 Pro（基于Android 14）设备上，当应用的targetSdkVersion设置为28时，尝试申请BLUETOOTH_CONNECT权限会出现两种异常情况：

1. 直接调用蓝牙功能时会抛出SecurityException，提示需要BLUETOOTH_CONNECT权限
2. 使用XXPermissions动态申请该权限时，又会抛出IllegalStateException，提示targetSdkVersion必须大于等于31

这种矛盾的情况让开发者陷入两难：不申请权限无法使用蓝牙功能，申请权限又被系统拒绝。

问题根源

这个问题的本质在于Android权限系统的演进。从Android 12（API 31）开始，Google对蓝牙权限进行了重大调整：

1. 引入了新的运行时权限BLUETOOTH_CONNECT和BLUETOOTH_SCAN
2. 废弃了旧的BLUETOOTH和BLUETOOTH_ADMIN权限
3. 要求targetSdkVersion≥31的应用必须使用新权限

然而，对于targetSdkVersion<31的旧应用，系统会保持向后兼容性，理论上应该允许继续使用旧权限。但在某些厂商定制系统（如OPPO/realme的ColorOS）上，这种兼容性处理可能不够完善，导致即使targetSdkVersion较低的应用也需要申请新权限。

解决方案

XXPermissions框架在18.65版本中对此问题进行了优化处理，主要改进包括：

1. 智能权限映射：对于targetSdkVersion<31的应用，框架会自动识别系统版本，在Android 12+设备上正确申请BLUETOOTH_CONNECT权限，同时保持对旧系统的兼容。

2. 蓝牙扫描权限处理：针对BLUETOOTH_SCAN权限，框架强制要求开发者明确声明是否用于定位目的：

   • 如果蓝牙扫描不涉及定位，必须添加android:usesPermissionFlags="neverForLocation"属性
   • 如果涉及定位功能，则需要同时申请ACCESS_FINE_LOCATION权限

3. 向下兼容机制：在Android 11及以下设备上，框架会自动将BLUETOOTH_SCAN权限请求转换为ACCESS_FINE_LOCATION权限请求，确保功能正常使用。

最佳实践建议

对于需要处理蓝牙权限的开发者，建议遵循以下实践：

1. 清单文件配置：

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" 
                 android:usesPermissionFlags="neverForLocation"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

2. 代码中申请权限：

XXPermissions.with(this)
    .permission(Permission.BLUETOOTH_CONNECT)
    .permission(Permission.BLUETOOTH_SCAN)
    .request(...);

3. targetSdkVersion升级：虽然框架提供了兼容方案，但长期来看，建议尽快将targetSdkVersion升级至31或更高版本，以符合Google Play的要求并确保最佳兼容性。

总结

Android权限系统的每次重大更新都可能带来兼容性挑战。XXPermissions框架通过智能权限映射和运行时判断，有效解决了低targetSdk应用在高版本系统上的蓝牙权限问题。开发者应当理解这些变化背后的设计意图，并在应用中正确实现权限申请逻辑，以保障用户体验和应用功能的完整性。