For AI agents: the complete documentation index is available at https://payhon.github.io/AppKernia/llms.txt, the full documentation bundle is available at https://payhon.github.io/AppKernia/llms-full.txt, and this page is available as Markdown at https://payhon.github.io/AppKernia/guide/mobile-permissions.md.

移动端权限中心

“我的 → 应用权限”只展示当前构建实际包含且业务正在使用的系统权限。当前完整接入通知和相机权限;照片、文件选择、麦克风、定位和蓝牙保留稳定定义,但在对应业务未启用前不会显示或提前申请。

页面加载和从系统设置返回时只查询状态,不主动弹出系统授权框。相机只在用户点击“扫一扫”或主动拍摄头像后申请,扫码固定不读取相册。拒绝通知或相机权限不会影响登录和站内消息。

稳定权限状态

状态含义
not_determined系统尚未询问用户
authorized已授权
limited平台提供临时或受限能力
denied用户拒绝;根据平台决定是否还能请求或只能打开设置
restricted受系统策略、家长控制或管理策略限制
unavailable当前平台、系统版本或构建不提供该能力

每项权限同时返回 can_requestcan_open_settings、平台说明和最近检查时间,页面据此显示“开启”或“前往系统设置”,而不是猜测平台行为。

开启 Push 的顺序

  1. 检查用户是否已完成法定隐私同意。
  2. 由用户主动点击后请求 OS 通知权限。
  3. 初始化当前构建和设备唯一可用的 Push Adapter。
  4. 获取可更新的厂商 Token。
  5. 幂等注册服务端设备绑定。
  6. 开启 Push 总开关,并保留服务安全与资讯运营两个独立订阅。

任一步失败都会保持或回滚开关状态,并显示可恢复错误。关闭总开关时先停用服务端绑定,再尽力注销本地 SDK Token,降低消息误投到上一个账号的风险。

平台行为

  • Android 13 及以上处理 POST_NOTIFICATIONS;打开设置时优先进入应用通知设置,失败后回退应用详情。
  • iOS 区分未决定、授权、临时或受限、拒绝,并优先使用通知专属设置入口。
  • HarmonyOS NEXT 通过通知管理能力查询、请求和打开设置;系统能力不足时才使用受控回退。
  • ak-push 把授权与设置操作委托给 ak-permissions,避免两套状态源。
  • 扫码同样把相机状态、请求和设置入口委托给 ak-permissions;详情见扫码能力

OS 权限状态首期不上传服务器。服务端只保存用户通知偏好和 Push 设备绑定;客户端从系统设置返回时在 onShow 刷新,并停用不再可用的绑定。

PermissionPort

uni_modules/ak-permissions 对业务层暴露:

  • listCapabilities()
  • getStatus(key)
  • request(key)
  • openSettings(key)
  • onStatusChanged(listener)

权限定义由编译期 Registry 管理。文件访问优先使用系统文件选择器,不因为预留“文件”能力就申请 Android 广泛存储权限。

公开配置兼容

Mobile 会对公开 App 配置中的 sharepushscanner 能力做运行时归一化。连接到尚未返回这些字段的旧版服务端时,对应能力会安全关闭,应用仍可启动;客户端不会把缺失字段当作已启用能力。

这种兼容只用于避免版本错配导致启动崩溃,不替代服务端升级。要启用 Push,公开配置、构建变体、厂商渠道和设备注册仍必须全部满足。

验收边界

HBuilderX 编译或模拟器启动不能替代物理设备验收。发布前需要在 iOS、GMS Android、国内厂商 Android 和 HarmonyOS NEXT 真机验证首次授权、拒绝、永久拒绝、设置恢复、升级、重装、账号切换、Token 更新和通知点击。

继续阅读推送渠道配置通知 API