更新记录

1.0.0(2026-11-17)

支持 iOS、鸿蒙 通用的持久化保存方案,即卸载重装后依然可以读取卸载前保存的数据。

1、增加对鸿蒙的支持 2、增加 安卓、iOS、鸿蒙 生成唯一ID并持久保存。


平台兼容性

uni-app(5.26)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
- - - - - - 11.0 16 √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

shiji-keychain 设备稳定 ID(iOS Keychain / Android ID / 鸿蒙 AssetStore)

简介

UTS 插件,为 uni-app 提供卸载重装后保持不变的设备稳定 ID(刷机/恢复出厂除外),用于设备数据统计等需要设备级唯一关联键的场景。

端 机制 卸载重装
iOS Keychain(kSecClassGenericPassword,首次固化、后续读取) ✅ 不变
Android Android ID(Settings.Secure.ANDROID_ID,签名不变则不变) ✅ 不变
鸿蒙 AssetStore(IS_PERSISTENT = true,系统级资产存储,卸载保留) ✅ 不变(需 ohos.permission.STORE_PERSISTENT_DATA 权限)

API

getStableId(service: string, account: string): StableIdResult

读取三端稳定设备 ID。

  • service / account:Keychain/AssetStore 的命名空间参数(自定义业务标识即可,如 'OGS-ElectronicMenu' / 'deviceId')
import { getStableId } from '@/uni_modules/shiji-keychain'

const res = getStableId('OGS-ElectronicMenu', 'deviceId')
if (res.success) {
  console.log('稳定设备 ID:', res.id, '来源:', res.source)
}

saveStableId(service: string, account: string, id: string): boolean

显式保存稳定 ID(iOS 写 Keychain;Android 为系统管理 no-op;鸿蒙写 AssetStore + 本地备份)。

ID 来源标识(res.source)

source 说明
KEYCHAIN iOS Keychain 命中(卸载重装前固化过)
IDFV iOS 首次安装(Keychain 空,取 IDFV 并固化)
ANDROID_ID Android 系统 ID
LOCAL_UUID 鸿蒙本地生成的 UUID(AssetStore 不可用时兜底,卸载会变)

注意事项

  • iOS:Keychain 数据卸载重装不丢,恢复出厂/抹除所有内容会清(系统限制)
  • iOS:仅声明 kSecAttrAccessibleAfterFirstUnlock,单 App 读写自身 Keychain 免授权(无需 Keychain Sharing entitlements)
  • Android:换签名重新打包会导致 Android ID 变化(SSAID 机制)
  • 鸿蒙:卸载重装 ID 会变(系统不提供跨卸载标识给第三方 app),设备级统计需 shopId 口径兜底
  • 普通 uni-app 项目(非 uni-app x)调用需 uni.requireUTSPlugin('shiji-keychain') 或 uni_modules import(HBuilderX 4.66+)

使用建议

设备数据统计等场景,推荐后端同时按 deviceId 与 shopId 双维度聚合——shopId 跟随门店永不变化,可作为 ID 断档(重装/换机)时的统计兜底。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。