权限与隐私合规:上架审核要点
本篇要点:能判断一个权限该不该申请、该在哪一刻申请、有没有等价控件可以不申请,并把隐私类驳回的常见原因在上架前逐条消掉。 前置:《系统能力:媒体、权限与后台任务》的系统能力(媒体、相机、后台任务)已经用过运行时权限。这一章不再讲"怎么调接口",讲"什么时候调会被判不合格"。
为什么需要它
《构建与发布:hvigor、多模块与上架》的最后一步是提审。真实世界里,鸿蒙应用被驳回很少是"功能有问题",回退意见绝大多数集中在一件事上——在错误的时间、以错误的粒度,拿了其实不需要的数据。
三条真实的驳回原文,症状各不相同,根因是同一个:
应用在用户同意隐私政策前存在网络请求行为(统计 SDK 在EntryAbility.onCreate里初始化)权限使用场景描述不清晰,未说明具体用途(reason写的是"为了提供更好的服务")应用存在超范围收集个人信息的行为(登录 token 明文写在preferences里)
审核方不读你的源码。它只核对三样东西:module.json5 里声明了什么、系统弹窗上那行 reason 怎么写的、真机冷启动前十秒做过什么。代码逻辑再干净,这三样对不上就是驳回。
截至 2026 年 11 月,本篇基线取 HarmonyOS 26.0.0(API 26,2026 年 8 月 29 日 Release);26.0.1 属于尝鲜增量,不建议作为上架基线。权限清单、授权类别与安全控件时限以 HarmonyOS 开发者文档中心 应用权限管理分区的当前版本为准。
核心概念
一、权限按授予方式分三类,判定错了要重做功能
system_grant(系统授权)安装即授予,只需在配置里声明,例如 INTERNET、GET_NETWORK_INFO。user_grant(用户授权)走运行时申请,弹窗、文案、时机全部被核,例如 CAMERA、LOCATION、APP_TRACKING_CONSENT。manual_settings(手动设置)需要用户自己到设置页开,典型是后台位置。
还有一类是受限权限(ACL,Access Control List):普通应用的 APL(Ability Privilege Level)不够,必须把等级提到 system_basic 及以上,并配套发布 Profile 才能用,例如读取剪贴板的 READ_PASTEBOARD。
类比:system_grant 是入住就发的门禁卡,user_grant 是每次都要敲的门,manual_settings 是要本人去机房合的总闸。
判定顺序是固定的:先问"有没有等价控件可以不申请"(第四节展开),再问"能不能降到更轻的长时任务",最后才落到申请哪一类。把 user_grant 写成 system_grant 不会报错,只会在运行时拿到一个恒为拒绝的结果。
二、声明三元组:name、reason、usedScene
三个字段各管一件事。name 是权限名;reason 是弹窗上给用户看的那句话,它引用字符串资源,参与上架校验;usedScene 说明"在哪个 Ability、什么时机用",其中 when 只接受 inuse 与 always 两个值,abilities 必须写真实存在的组件名。
反例:abilities 里写了个 MainAbility,而工程里实际叫 EntryAbility。编译不报错,校验直接不过。这类错误只能靠对齐检查,没有提示。
多 HAP 场景下 entry 的声明对整个应用生效,feature 不必重复声明。
申请电话、信息、日历、通讯录、通话记录这五个权限组时,界面按监管要求会同时展示组内子权限,文案必须写成"包括子权限 A 和子权限 B,用于某事",否则判为用途描述不完整。代价是维护成本:每新增一个 user_grant 权限,要同步 4–6 份语种资源。
三、授权状态是三态,不能缓存
系统的授权状态有三个:未决定、已授权、已拒绝。关键的一条是——用户拒绝过一次之后,再调 requestPermissionsFromUser 不会弹窗,接口直接返回拒绝。想再引导,只能换 requestPermissionOnSetting(API 12 起提供),由系统弹出跳转设置的对话框。
由此有两条结论。第一,授权结果不要写进 preferences 然后复用,用户可能在设置页把它收回去,缓存的结果会变成谎话;每次访问前调 checkAccessToken,多一次 IPC 查询,量级在毫秒。第二,申请时机要落在功能触发点,不要在 aboutToAppear 里一次申请三项以上——首启批量申请会让权限入口长期被拒,这是驳回意见里的高频项。
完整时序如图 10-1 所示。
图 10-1 一次完整的授权判定时序(扫码场景)
如图 10-1 所示,从冷启动到用户点"同意"之间,应用不该有任何网络请求、不该读任何设备标识。这条要求把 EntryAbility.onCreate 拆成了两段:同意之前只做 UI 装配,同意之后才初始化统计、推送、崩溃上报三类 SDK。
四、安全控件:用户点一下,换掉一个权限
能拿到等价控件的场景就不要申请权限。这是驳回率下降最快的一层——审核方看到的申请数量直接减少了。
| 场景 | 硬申请 | 推荐路径 | 代价 |
|---|---|---|---|
| 读取剪贴板 | READ_PASTEBOARD(ACL,要提 APL) | PasteButton 粘贴控件 | 用户需点一下控件 |
| 保存图片到相册 | WRITE_MEDIA | SaveButton 保存控件 | 授权有临时时限 |
| 选择相册文件 | READ_MEDIA | 系统 PhotoPicker | 要处理返回 URI 的生命周期 |
| 扫码 | CAMERA | 无等价控件 | reason 必须写"用于扫码" |
安全控件(security component)的原理是"用户的一次点击即视为一次授权",系统给一个短时授权窗口,过期自动收回。这个窗口有时限,而官方两处文档的口径不一致:粘贴控件页写"持续到灭屏、切后台或退出",安全控件概述页写"进入后台 10 秒后回收";SaveButton 在 API 19 及之前授权 10 秒,API 20 起为 1 分钟。
设计时按 10 秒的保守值算。顺着这个约束往下推,会得到一个干脆的结论:「后台定时读剪贴板」这类需求在新模型下没有成立条件,不要试图用长时任务绕过它——绕过本身就是一条驳回理由。
五、敏感数据落盘:preferences 不是保险箱
preferences 是明文的。token、手机号、证件号写进去,等于把凭据摆在一个能被备份、能被读出的文件里。
正确的容器是 Asset Store Kit(资产存储服务):加解密交给通用密钥库系统在安全环境完成,算法 AES256-GCM,并支持基于锁屏状态的访问控制。三个字段决定它的安全等级:ACCESSIBILITY 设为 DEVICE_UNLOCKED 表示仅解锁后可读;REQUIRE_PASSWORD_SET 为 true 表示设备未设锁屏密码时不可写入;IS_PERSISTENT 控制卸载后是否保留。
有一条要说清:不建议为了"换机保留登录态"把 IS_PERSISTENT 置为 true。置真需申请 ohos.permission.STORE_PERSISTENT_DATA 并说明理由,换来的只是卸载不清除;而登录态的正确做法是重新认证,不是延长本地留存。
另外三个约束:ALIAS 与 DATA_LABEL 开头的附属属性默认不加密,不得放敏感值;批量查询受 IPC 缓冲限制,超过 40 条要分批;API 21 起卸载会清除非群组数据,群组数据要等组内应用全部卸载才清除,否则卸载重装后仍有残留。
数据能不能出设备,判定顺序是四步:能不采集就不采集(端侧计算优先);必须采集就本地加密、最小留存;必须上传则单独取得同意;涉及出境再走安全评估。跨设备同步权限 DISTRIBUTED_DATASYNC 本身是 user_grant,跨设备传数据属于要用户逐次确认的行为,不能当成系统能力直接调用。
动手实践
五步,从声明改到存储,最后用五条量化口径验收。
第一步,把声明写对。 打开 entry/src/main/module.json5:
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "$string:reason_approximately_location",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
},
{
"name": "ohos.permission.CAMERA",
"reason": "$string:reason_camera",
"usedScene": { "abilities": ["ScanAbility"], "when": "inuse" }
},
// system_grant 权限不写 reason / usedScene,写了也不参与上架校验
{ "name": "ohos.permission.INTERNET" }
]
}
}运行结果:hvigorw assembleHap 通过;提审预检里 CAMERA 与 APPROXIMATELY_LOCATION 各有一条用途说明,INTERNET 没有。把 ScanAbility 改成不存在的 ScanPage,编译仍通过,但上架校验会报组件名不存在。
第二步,写一个不缓存的权限工具。 新建 entry/src/main/ets/common/PermissionUtil.ets:
import { abilityAccessCtrl, bundleManager, common, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export async function ensurePermission(
context: common.UIAbilityContext, permission: Permissions): Promise<boolean> {
const atManager = abilityAccessCtrl.createAtManager();
const info = await bundleManager.getBundleInfoForSelf(
bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION);
const tokenId = info.appInfo.accessTokenId;
// 每次都查,不读缓存
if (await atManager.checkAccessToken(tokenId, permission)
=== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
return true;
}
const res = await atManager.requestPermissionsFromUser(context, [permission]);
if (res.authResults[0] === 0) {
return true;
}
// 拒绝一次后上面这行不会再弹窗,只能走设置弹窗
try {
const setting = await atManager.requestPermissionOnSetting(context, [permission]);
return setting[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
} catch (e) {
const err = e as BusinessError;
console.error(`requestPermissionOnSetting failed: ${err.code}, ${err.message}`);
return false;
}
}运行结果:首次调用弹出系统权限弹窗,标题下方就是 reason_camera 的文案;点"允许"返回 true。点"拒绝"后再调一次不会再弹窗,而是弹出跳转设置的对话框;用户在设置页开启后返回,函数返回 true。
这里有一处只有实际调过才会碰到:在 onWindowStageCreate 里申请权限,必须等 loadContent 的异步回调返回之后再调,否则直接失败;错误码笼统,表现很像"权限未声明"。
第三步,用控件换掉权限。 保存图片到相册不要申请 WRITE_MEDIA,改用 SaveButton:
@Entry
@Component
struct SavePhoto {
build() {
Column() {
SaveButton({ text: '保存到相册', icon: SaveIconStyle.FULL_FILLED })
.onClick(async (event: ClickEvent, result: SaveButtonOnClickResult) => {
if (result === SaveButtonOnClickResult.SUCCESS) {
return; // 临时授权已生效,可直接写入相册
}
// 授权失败就什么都不做,绝不在这里再申请 WRITE_MEDIA
})
}
}
}运行结果:页面出现系统风格的"保存到相册"按钮;点击后返回 SUCCESS,随后的写相册操作成功,全程没有权限弹窗。切到后台停留 10 秒再回来,同一个按钮的授权已失效,需要重新点击——按保守值设计,不要假设它有更长的窗口。
第四步,把 token 挪进 Asset。 新建 entry/src/main/ets/common/SessionStore.ets:
import { asset } from '@kit.AssetStoreKit';
import { util } from '@kit.ArkTS';
const encoder = new util.TextEncoder();
export async function saveSessionToken(token: string): Promise<void> {
const attr: asset.AssetMap = new Map();
attr.set(asset.Tag.SECRET, encoder.encodeInto(token));
attr.set(asset.Tag.ALIAS, encoder.encodeInto('session_token'));
attr.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_UNLOCKED);
attr.set(asset.Tag.REQUIRE_PASSWORD_SET, true);
attr.set(asset.Tag.IS_PERSISTENT, false);
await asset.add(attr);
}运行结果:返回 undefined 即写入成功;在设备锁屏状态下读取会失败,解锁后成功。把 IS_PERSISTENT 改成 true 而不申请 STORE_PERSISTENT_DATA,asset.add 会返回授权错误码。
第五步,五条口径逐项验收。 不做定性描述,只跑命令看数字:
# 1) user_grant 权限的 reason 数量应与声明数一致
grep -c '"reason"' entry/src/main/module.json5
# 2) 敏感字段是否还留在 preferences
grep -rniE "token|phone|idCard" entry/src/main/ets/ | grep -i preference
# 3) 是否还在硬申请受限权限
grep -nE "READ_PASTEBOARD|WRITE_MEDIA|READ_MEDIA" entry/src/main/module.json5运行结果:第 1 条输出 2;第 2、3 条都没有输出。再加上两条非命令项:冷启动到点击"同意"期间网络请求数为 0(抓包 3 次均成立),每个权限能走通"首次申请→拒绝→二次引导→设置页开启"四步。五项全过才算一期完成,一期的时间口径是上架前 T-10 个工作日。
还有一条与代码无关、但会直接驳回的项:应用必须有账号注销入口和对应的数据处理说明,只提供"退出登录"不算。
常见误解
"reason 是给开发者看的注释,随便写写。" 它是弹窗上用户唯一会读的那句话,也是审核方唯一能直接读到的人话。含"提供更好的服务""优化体验"这类空泛句式,判为用途不清晰,返工 1–2 天。可用的写法是"用于扫码拍照"这种句式,长度控制在 72 字符以内。
"被拒了再调一次接口就会再弹。" 不会。系统只在用户未决定时弹窗,拒绝之后接口静默返回拒绝。想再要一次机会,只能走 requestPermissionOnSetting,而它弹的是"跳转设置"对话框,不是权限弹窗。这条如果不清楚,很容易写成"循环申请直到用户同意",表现是按钮点了没反应。
"权限一次申请完更省事,用户少被打断。" 首启一次申请三项以上,是权限入口被长期拒绝的主要原因。用户在还不知道你要干什么的时候,倾向全点拒绝,而拒绝不可逆,只能去设置页改;等到真正需要时,弹窗已经不会出现了。
小结
- 审核方只看三样:
module.json5的声明、弹窗上的reason、冷启动前十秒的行为。 - 权限按授予方式分
system_grant、user_grant、manual_settings,受限权限要走 ACL 提 APL。类别判错的代价是功能写完才发现没有开放范围。 - 声明三元组里
reason参与上架校验,usedScene.when只接受inuse与always。 - 授权状态不可缓存,被拒后必须换
requestPermissionOnSetting;申请时机落在功能触发点,同意之前不初始化任何会联网的 SDK。 - 能用
PasteButton、SaveButton、PhotoPicker 换掉的权限就换掉,临时授权窗口按 10 秒保守估算。 - token 一类凭据进 Asset Store Kit,
IS_PERSISTENT保持false;ALIAS与DATA_LABEL附属属性默认不加密。
相关主题
合规这一关过了,应用能上架了,但上架不等于够用——一个 4 MB 数据的压缩要 2.8 秒,用户还是会以为它卡死了。《进阶:NAPI 原生扩展与高性能互操作》讲 NAPI 原生扩展与高性能互操作:把 C/C++ 接进 ArkTS,讲清 napi_value 为什么不能存、原生线程怎么投递、崩溃栈怎么还原成行号。那一章也会提醒你,多数情况下先重构调用粒度比换语言更有效。