📚 课程目录第2章权限声明雷区

2、权限声明雷区：Android/iOS权限配置不当导致采集失败，如何正确配置？

权限声明这事，看着简单，坑却不少。我见过太多团队，SDK集成了半天，数据就是不上报，最后发现是权限没配好。说白了，权限就像你家大门的钥匙——钥匙不对，数据进不来。

今天咱们就把Android和iOS两边的权限配置捋清楚。哪些必须加，哪些可以不加，加错了会怎样，我都会结合自己的踩坑经历跟你讲明白。

2.1 Android权限配置：别多配，也别少配

Android的权限模型这几年变了好几次。从6.0的运行时权限，到11的包可见性变化，再到13的通知权限——每次改动都直接影响SDK采集。

我个人习惯是：只声明SDK真正需要的权限。多配了，用户会怀疑你偷隐私；少配了，数据直接断流。

2.1.1 必须声明的权限

下面这几个，是大多数采集SDK的标配。你可以在AndroidManifest.xml里加上：

<!-- 网络访问，采集上报的基础 -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- 获取网络状态，判断WiFi还是移动数据 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- 获取WiFi状态，用于辅助定位和网络质量分析 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- 读取设备标识（IMEI/MEID等），用于设备唯一识别 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

⚠️ 注意：READ_PHONE_STATE 从 Android 10 开始，普通应用已经拿不到 IMEI 了。如果你的SDK还硬要这个权限，建议升级SDK版本，改用OAID或广告标识符。

2.1.2 可选但建议加的权限

这些权限不是必须的，但加了能提升采集的完整度：

权限	作用	不加的影响
ACCESS_FINE_LOCATION	精确定位，用于地域分析	只能靠IP粗略定位
ACCESS_COARSE_LOCATION	粗略定位（基站/WiFi）	同上，精度更低
CAMERA	扫码、AR场景采集	相关功能不可用
RECORD_AUDIO	语音采集	语音功能失效

嗯，这里要特别说一句：不要为了采集数据去申请不必要的敏感权限。我在项目中遇到过，某个第三方SDK偷偷申请了读取联系人权限，结果应用被应用商店直接下架。这个锅，最后还是开发者背。

2.1.3 Android 11+ 的包可见性

从Android 11开始，如果你需要查询设备上安装了哪些应用（比如用于竞品分析或渠道归因），必须在AndroidManifest里加：

<queries>
    <intent>
        <action android:name="android.intent.action.MAIN" />
    </intent>
</queries>

不加的话，queryIntentActivities() 返回的结果会是空的。我有个朋友，上线后发现应用安装来源数据全是0，排查了两天才发现是少了这个声明。

2.2 iOS权限配置：Info.plist里的一句话不能少

iOS这边相对简单，但有个特点：你必须在Info.plist里提供“使用说明”。光声明权限还不够，还得写清楚为什么要用。

举个例子，你要用定位：

<key>NSLocationWhenInUseUsageDescription</key>
<string>我们需要获取您的位置信息，用于为您推荐附近的优惠活动</string>

这段说明文字会直接展示给用户。写得不好，用户直接点“不允许”。

2.2.1 常用权限键值对

权限键（Key）	用途	说明文案示例
NSCameraUsageDescription	相机	用于扫描二维码和拍照上传头像
NSPhotoLibraryUsageDescription	相册	用于选择图片作为用户头像
NSLocationWhenInUseUsageDescription	前台定位	用于获取您的位置以推荐附近门店
NSLocationAlwaysAndWhenInUseUsageDescription	后台定位	用于记录运动轨迹（需同时声明前台定位）
NSMicrophoneUsageDescription	麦克风	用于语音搜索和录制短视频
NSUserTrackingUsageDescription	广告追踪（IDFA）	用于为您展示个性化广告（iOS 14+）

💡 小技巧：说明文案不要写“用于数据采集”这种大实话。用户看了会害怕。要写“用于为您推荐更合适的内容”这种对用户有价值的话。我试过，授权率能提升30%以上。

2.2.2 iOS 14+ 的IDFA权限

这个坑最大。iOS 14开始，获取IDFA（广告标识符）需要用户主动授权。如果你的SDK依赖IDFA做设备识别，必须加：

<key>NSUserTrackingUsageDescription</key>
<string>我们将使用您的IDFA来提供更精准的广告推荐</string>

而且，你需要在代码里调用 ATTrackingManager.requestTrackingAuthorization() 来弹出授权框。不弹的话，IDFA返回的全是0。

我记得有个项目，上线后iOS端的用户重合度分析完全不准。查了半天，发现是开发同学忘了加这个权限声明，SDK拿不到IDFA，所有用户都被识别成了同一个设备。

2.3 权限配置的常见踩坑点

下面这几个坑，我几乎每个都踩过。列出来，你对照检查一下：

Android权限声明了但没动态申请：Android 6.0+ 的危险权限，光在Manifest里写没用，运行时还得弹窗让用户同意。很多新手只配了Manifest，忘了写运行时申请代码。
iOS权限说明文案太敷衍：写“用于数据统计”这种，用户一看就拒绝。要写对用户的好处。
权限被用户拒绝后没有降级处理：用户拒绝定位，你的SDK就直接崩溃？这不行。要做好无权限时的兜底逻辑。
Android 13+ 的通知权限：如果你的SDK需要推送通知，Android 13开始要声明 POST_NOTIFICATIONS 权限。不加的话，通知弹不出来。
混淆规则把权限类给混淆了：有些权限相关的类名被混淆后，运行时反射找不到，权限申请直接失败。记得在proguard-rules.pro里加 -keep 规则。

  🔑 核心原则：权限配置的核心是“最小必要”原则。只申请SDK真正需要的权限，并且每个权限都要有明确的用户价值说明。多一个权限，多一分被用户拒绝的风险。

2.4 权限配置流程图

下面这张图，把权限配置的完整流程串起来了。从SDK初始化到用户授权，每一步都可能出问题：

2.5 避坑指南

最后，给你几个实战建议。这些都是我用真金白银换来的教训：

权限声明清单化：每次接入新SDK，先拉一张权限清单，对照着检查。我习惯用Excel列出来，哪个权限是哪个SDK用的，一目了然。
测试机覆盖全版本：Android 6.0、10、13、14，iOS 13、14、15、16、17，每个版本都要测。不同版本的权限行为不一样。
权限被拒后要有日志：用户拒绝权限时，SDK要打日志。这样线上出问题，你能快速定位是权限问题还是代码问题。
不要硬依赖敏感权限：我曾经有个SDK，没有定位权限就直接抛异常。后来改了，用IP定位做降级，数据完整度从60%提到了95%。
定期检查权限变更：Android和iOS每年都有新版本，权限模型也在变。建议每个大版本发布前，都重新过一遍权限配置。

📌 我的习惯：每次发布新版本前，我会在测试机上把所有权限都拒绝一次，看看SDK会不会崩溃。这个习惯帮我避免了好几次线上事故。

权限配置这事，说难不难，说简单也不简单。关键是要细心，把每个平台的规则都吃透。你按上面说的配，基本不会出大问题。