更新记录

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 后:

  1. 在插件详情页 试用/购买 并绑定当前 AppID 工程
  2. manifest.json 配置 AppID
  3. 按下文「平台配置」补齐宿主声明
  4. 制作自定义调试基座 → 运行到自定义基座(真机)

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。


点击下载体验
扫码体验
扫码体验

隐私、权限声明

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

Android:无额外权限(OAID 经 MSA SDK);iOS:ATT(仅广告 ID);HarmonyOS:STORE_PERSISTENT_DATA + APP_TRACKING_CONSENT

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

插件不联网上报;仅在本地读取/生成标识并返回给调用方

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

可选读取 OAID/IDFA,仅在调用方 setPrivacyAgreed(true) 之后

暂无用户评论。