更新记录
1.0.1(2026-11-17)
-优化
1.0.0(2026-11-16)
-uuid
平台兼容性
uni-app(5.14)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| √ | √ | × | × | √ | - | 5.0 | 12 | √ |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | × | × | × |
uni-app x(4.0)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | 5.0 | 12 | √ | - |
ly028-uuid
uni-app / uni-app x 三端设备标识 UTS 插件:稳定设备码、安装码、业务隔离码、广告标识(OAID / AAID / IDFA),以及多源诊断与能力查询。支持 Android / iOS / HarmonyOS。
不提供 IMEI、MEID、Widevine、PseudoID。广告相关接口须在用户同意隐私后调用。
点击下载体验
扫码体验
Android OAID 说明(接入方无需改 enableOAID)
本插件 不内置 oaid_sdk aar,也 不要求 "enableOAID": false。
云打包保持默认即可:基座自带 base_old_oaid_*;插件运行时反射调用 com.bun.miitmdid.*,避免 Duplicate class,也避免编译期 Unresolved。
| 你需要做的 | 说明 |
|---|---|
| 自定义基座 / 云打包 | 标准基座不含本插件原生代码 |
保持 enableOAID 默认 |
一般不用改;Google Play(AAB) 渠道基座可能无 OAID |
| 用本插件 API | getAdvertisingId / getIdCodes(也可继续用 plus.device.getOAID) |
平台支持
| 工程类型 | Android | iOS | HarmonyOS |
|---|---|---|---|
| uni-app App | ✅ | ✅ | ✅ |
| uni-app x App | ✅ | ✅ | ✅ |
| 能力 | Android | iOS | HarmonyOS |
|---|---|---|---|
| 稳定设备码 | ✅ ANDROID_ID | ✅ Keychain | ✅ Asset 持久化 |
| 安装码 / 业务隔离码 | ✅ | ✅ | ✅ |
| 广告标识 | ✅ OAID → AAID | ✅ IDFA(ATT) | ✅ OAID(可降级 ODID) |
| 多源码表 / 快照 / 能力 | ✅ | ✅ | ✅(无 AAID) |
| Keychain 共享组 | — | ✅ | — |
| 降级 ID Keystore 加密 | ✅ | — | — |
- 环境:uni-app 建议 HBuilderX 3.7.2+;uni-app x 建议 4.0+(鸿蒙建议 4.31+)
- 调试:UTS 原生插件必须进入 自定义调试基座 或 正式云打包包体;普通标准基座不含本插件原生代码
功能一览
| 功能 | API | 说明 |
|---|---|---|
| 稳定设备码 | getStableDeviceId |
卸载重装尽量不变;适合绑定设备(勿单独当账号凭证) |
| 本次安装码 | getInstallId / resetInstallId |
仅本次安装有效,可重置 |
| 业务隔离码 | getNamespacedId / resetNamespacedId |
按租户 / 业务线分开存 |
| 广告标识 | getAdvertisingId |
Android:OAID,失败回落 AAID;iOS:IDFA;鸿蒙:OAID。需先同意隐私 |
| 多源诊断 | getIdCodes |
一次返回 OAID / AAID / AndroidID / GUID |
| 是否支持 OAID | isOaidSupported / isOaidSupportedAsync |
同步只读缓存;异步给出探测结果 |
| 多源快照 | getIdSnapshot |
给服务端做多源融合的一包数据 |
| 能力查询 | getCapability |
当前环境有哪些标识可用、是否需同意 |
| 隐私门控 | setPrivacyAgreed / isPrivacyAgreed |
未同意前不读广告标识 |
| 预热 | prefetch |
预热稳定码 / 安装码(不碰广告) |
| 清理(测试) | clearAll |
清安装码 / 命名空间 / 本地降级码 |
| Keychain 共享 | setKeychainAccessGroup |
iOS 多 App 共享稳定码(1.2.0) |
| 加密存储 | setSecureStorageEnabled |
Android 降级稳定码 Keystore 加密(1.2.0) |
| 多语言 | setLocale / getLocale |
error / tip 等文案:en / zh-Hans |
读取接口均提供 回调版 与 Sync 同步版(广告标识建议用回调版)。另提供 js_sdk Promise 封装。
选哪个接口
| 你的需求 | 调用 |
|---|---|
| 卸载重装后尽量还是同一个 ID | getStableDeviceId |
| 只绑定本次安装 | getInstallId |
| 多业务互不影响 | getNamespacedId('bizA') |
| 广告投放 / OAID / AAID / IDFA | 先 setPrivacyAgreed(true),再 getAdvertisingId |
| 一次拿 OAID + AAID + AndroidID + GUID | getIdCodes |
| 服务端要多种 ID | getIdSnapshot |
| 看当前能不能取到某类 ID | getCapability / isOaidSupportedAsync |
| 退出登录 / 注销时清理本地 ID | clearAll |
快速开始
1. 安装
在 DCloud 插件市场 搜索 ly028-uuid,导入到项目 uni_modules 后:
- 在插件详情页 试用/购买 并绑定当前 AppID 工程
manifest.json配置 AppID- 按下文「平台配置」补齐宿主声明
- 制作自定义调试基座 → 运行到自定义基座(真机)
2. 最小示例(回调)
import {
setPrivacyAgreed,
prefetch,
getStableDeviceId,
getAdvertisingId,
setLocale
} from '@/uni_modules/ly028-uuid'
setLocale('zh-Hans') // 可选,默认 en
prefetch() // 可选:启动时预热稳定码 / 安装码
// 用户同意隐私政策后
setPrivacyAgreed(true)
getStableDeviceId((r) => {
console.log(r.id, r.source, r.maySurviveReinstall, r.subCode)
})
getAdvertisingId((r) => {
// source: oaid | aaid | idfa | odid | unavailable
console.log(r.id, r.source, r.error, r.subCode)
})
3. Promise(js_sdk)
import uuid from '@/uni_modules/ly028-uuid/js_sdk/index.js'
await uuid.setPrivacyAgreed(true)
const stable = await uuid.getStableDeviceId()
console.log(stable.id, stable.source)
兼容旧接口:getDeviceUuid(等同 getStableDeviceId,新项目请勿使用)。
返回值 DeviceIdResult
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 标识值;不可用时为空串 |
platform |
string | android / ios / harmony |
source |
string | 来源,见下表 |
scope |
string | app / install / advertising / vendor / unknown |
stabilityLevel |
string | reinstallBestEffort / install / advertising / unknown |
maySurviveReinstall |
boolean | 是否尽力跨卸载保留 |
resetHint |
string | 可能变化的条件说明 |
privacyRequired |
boolean | 是否依赖隐私同意 |
error |
string | 失败或降级说明(语言随 setLocale) |
cached |
boolean | 是否来自内存缓存 |
timestamp |
number | 毫秒时间戳 |
subCode |
number? | 见下表 |
subCode
| 值 | 含义 |
|---|---|
0 |
成功 |
400 |
参数错误 |
404 |
暂未取到(探测中 / 结果为空) |
409 |
未同意隐私 |
422 |
已降级(如本地 UUID、ODID) |
500 |
内部错误 |
501 |
当前环境不支持 |
常见 source
| source | 含义 |
|---|---|
android_id |
Android 稳定码 |
stable_fallback |
Android 降级稳定码 |
keychain |
iOS 稳定码 |
asset |
鸿蒙稳定码 |
install / namespaced |
安装级 / 命名空间 |
oaid / aaid / idfa / odid |
广告或开发者标识 |
unavailable / ads_pending / unsupported |
暂不可用 |
API 说明
隐私与预热
| 方法 | 说明 |
|---|---|
setPrivacyAgreed(agreed) |
设置是否已同意隐私;为 false 时不读广告标识 |
isPrivacyAgreed() |
读取当前隐私同意状态 |
prefetch() |
预热稳定码、安装码;不会请求广告标识或弹出 ATT |
三类设备码
| 方法 | 说明 |
|---|---|
getStableDeviceId(cb) / getStableDeviceIdSync() |
稳定设备码 |
getInstallId(cb) / getInstallIdSync() |
本次安装码 |
resetInstallId() |
重置安装码,返回新值;不影响稳定码 |
getNamespacedId(ns, cb) / getNamespacedIdSync(ns) |
业务隔离码 |
resetNamespacedId(ns) |
仅重置该命名空间 |
| 平台 | 稳定码行为摘要 |
|---|---|
| Android | 同签名 + 同用户下卸载重装尽量不变;恢复出厂或换签名会变 |
| iOS | 同 Bundle/Team 卸载重装尽量不变;抹机或换 Bundle/Team 会变 |
| Harmony | 需持久化权限;刷机 / 恢复出厂会变 |
广告标识
| 方法 | 说明 |
|---|---|
getAdvertisingId(cb) / getAdvertisingIdSync() |
读取广告标识;请用回调版 |
isOaidSupported() |
只读缓存,不阻塞;无缓存返回 false(可后台预热) |
isOaidSupportedAsync(cb) |
后台探测后回调;iOS 恒为 false |
| 平台 | 成功时 source | 说明 |
|---|---|---|
| Android | oaid,失败回落 aaid |
需自定义基座;无 GMS 时可能只有 OAID |
| iOS | idfa |
可能弹出跟踪授权 |
| Harmony | oaid,失败可降为 odid |
需跟踪授权;鸿蒙 无 AAID |
未同意隐私时返回 subCode=409。本机无 OAID 且无 AAID 时可能为 501。
诊断
getIdCodes(cb) / getIdCodesSync()
| 字段 | 说明 |
|---|---|
supportedOAID |
是否支持 OAID |
OAID |
开放匿名设备标识 |
AAID |
Android=谷歌广告 ID;iOS 可承载已授权 IDFA;鸿蒙为空 |
AndroidID |
仅 Android;其他平台空串 |
GUID |
等同安装码 |
tip |
补充说明 |
privacyAgreed |
当前是否已同意隐私 |
不返回 IMEI、MEID、Widevine、PseudoID。
getIdSnapshot(cb) / getIdSnapshotSync()
一次返回稳定码、安装码、广告标识及 sources(如 androidId / oaid / gaid / idfa 等),便于上报服务端。
getCapability(cb) / getCapabilitySync()
返回 items[]:每项含 key、available、needConsent、detail(如 ok / need_consent / unsupported / no_gms / init_code=)。
配置与测试
| 方法 | 平台 | 说明 |
|---|---|---|
setKeychainAccessGroup(group) |
仅 iOS | 首次读取稳定码之前调用;group 须出现在宿主 keychain-access-groups(含 Team ID) |
setSecureStorageEnabled(enabled) |
主要 Android | 降级稳定码是否用 Keystore 加密保存;默认关闭 |
clearAll() |
全平台 | 清安装码 / 命名空间 / 本地降级码;保留隐私状态与系统级稳定码 |
setLocale(locale) / getLocale() |
全平台 | 'en'(默认)或 'zh-Hans' |
兼容
| 方法 | 说明 |
|---|---|
getDeviceUuid(cb) / getDeviceUuidSync() |
已废弃,等同 getStableDeviceId |
三端行为摘要
| API | Android | iOS | HarmonyOS |
|---|---|---|---|
| 稳定码 | ANDROID_ID;不可用时本地 UUID(可 Keystore) | Keychain UUID | Asset;失败可降级 ODID |
| 安装 / 命名空间 | 本地存储 | 本地存储 | Preferences |
| 广告标识 | OAID → AAID(GAID) | ATT 后 IDFA | OAID;未授权可降级 ODID |
| AAID | 需 GMS + 广告标识依赖 | — | 不支持 |
平台配置与隐私
通用
- 在应用隐私政策中说明会使用设备标识 / 广告标识(按你实际调用的接口声明)
- 广告相关:先完成 App 隐私弹窗,再
setPrivacyAgreed(true)
Android
- OAID:反射调用基座自带 MSA(插件 libs / config.json 勿再加 oaid,否则 Duplicate);无需关
enableOAID - AAID 回落:
config.json已声明play-services-ads-identifier;无 GMS 可能只有 OAID - targetSdk ≥ 33:
AD_ID已由插件 Manifest 合并
iOS
- 读取 IDFA:宿主
Info.plist配置NSUserTrackingUsageDescription - Keychain 多 App 共享:宿主开启 Keychain Sharing,并在首次读稳定码前调用
setKeychainAccessGroup('TEAMID.com.example.shared')
HarmonyOS
- 稳定码持久化:宿主申请
ohos.permission.STORE_PERSISTENT_DATA(如需要) - 广告标识:用户授予
ohos.permission.APP_TRACKING_CONSENT;未授权时系统可能返回全 0,插件可降级 ODID(subCode=422)
明确不提供
IMEI、MEID、Widevine ID、PseudoID;鸿蒙无广告意义的 AAID 公开 API。
稳定性边界(请知悉)
| 场景 | 可能变化的标识 |
|---|---|
| 恢复出厂 / 刷机 | 稳定码、安装码、广告标识等 |
| 更换应用签名 / BundleId / Team | 稳定码 |
| 用户在系统设置重置广告标识 | 广告标识 |
| 卸载重装 | 安装码、业务隔离码会变;稳定码尽力保持 |
请勿仅用客户端设备标识作为账号登录或付费权益的唯一凭证。
常见问题
Q:云打包 Duplicate class ... miitmdid?
A:插件或其它模块又打进了 oaid_sdk。本插件不带该 aar;请删掉重复依赖,并保持 enableOAID 默认(本方案不关基座)。
Q:标准基座里调用没反应 / 报错?
A:必须使用自定义调试基座或云打包正式包,标准基座不包含 UTS 插件原生代码。
Q:获取广告 ID 返回 subCode=409?
A:尚未 setPrivacyAgreed(true)。请先完成隐私弹窗再打开门控。
Q:Android 返回 501 或不支持?
A:本机无可用 OAID,且 AAID(GMS)也读不到。模拟器、无厂商 OAID、无 Google 服务的环境较常见。可先看 getCapability 中 oaid / aaid 的 detail。
Q:iOS 拿不到 IDFA?
A:检查是否配置了 NSUserTrackingUsageDescription,以及用户是否在 ATT 弹窗中允许跟踪。
Q:鸿蒙 OAID 全 0 或变成 ODID?
A:多为未授予跟踪权限;插件会降级 ODID,并可能带 subCode=422。
Q:isOaidSupported() 一直是 false?
A:同步版只读缓存。请用 isOaidSupportedAsync,并确保已同意隐私。iOS 上该能力恒为 false(广告走 IDFA)。
Q:clearAll 会清掉稳定码吗?
A:不会清 ANDROID_ID / Keychain / Asset 等系统级稳定码,也不会改隐私同意状态。
更新日志
详见同目录 changelog.md。当前版本 1.2.0。
点击下载体验
扫码体验

收藏人数:
购买源码授权版(
试用
使用 HBuilderX 导入示例项目
赞赏(0)
下载 933
赞赏 0
下载 12768972
赞赏 1959
赞赏
京公网安备:11010802035340号