更新记录

1.0.3（2026-07-28）

• 新增 getAppInstallId() 和 getAppInstallIdSync()，可直接读取插件维护的应用安装 ID，不再依赖 ANDROID_ID / IDFV 的来源优先级。
• Android、iOS、HarmonyOS、Web、微信小程序和支付宝小程序统一返回 source=appInstallId、scope=app 的结构化结果。
• Web 与小程序存储不可用时复用进程级临时 ID，并返回 9050004 诊断；重置未持久化时明确返回失败，不伪造成功。
• uni-app 与 uni-app x 示例新增“读取安装标识”，重置后直接展示新安装 ID，形成读取、重置、再次读取的完整验收链路。
• 保持既有 privacy / stable / advertising 行为不变，不新增权限、三方 SDK、Manifest 或广告标识采集。

1.0.2（2026-07-28）

• HarmonyOS 本地安装 ID 改为使用应用沙箱 Preferences 持久化，杀进程或普通重启后继续返回同一标识。
• resetAppInstallId() 在新 ID 同步落盘后才返回成功；持久化存储不可用时返回失败并明确说明仅当前进程有效。
• 保持既有公共 API 和 Android / iOS / Web / 小程序行为不变，不接入 ODID、AAID、OAID，不新增权限或三方 SDK。
• 补充 HarmonyOS 重启验收提示、发布守卫和持久化专项守卫；最终跨进程稳定性仍需 HarmonyOS 真机安装新包验证。

1.0.1（2026-06-25）

• 对齐 uni-app x 示例页与 uni-app 示例页，补齐当前结果、能力矩阵、隐私优先、稳定标识、广告标识检测、重置安装标识和运行日志。
• 修复 uni-app x 示例页只能输出简单日志、缺少结构化状态展示的问题，便于真机调试设备标识来源、权限状态和策略诊断。
• 通过 Android USB 自定义基座验证：privacy / stable 均返回 ANDROID_ID，advertising 返回未集成 OAID SDK 的结构化诊断，reset 成功重置本地安装 ID 并自动刷新 privacy 结果。
• 本版本未修改公共 API、根入口、Android/iOS/Harmony/Web/小程序平台实现或 uni-app 示例。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

设备唯一标识 UTS插件

lizhao-device-id 是一个面向 uni-app / uni-app x 的设备唯一标识 UTS插件，用于在 Android、iOS、HarmonyOS 中获取可解释、可诊断、可重置边界清晰的设备标识。

功能特色

• 三端统一：Android / iOS / HarmonyOS 使用同一套 API。
• 结构化返回：不仅返回 id，还返回 source、scope、permissionStatus、resetHint、rawAvailable 等字段。
• Harmony 持久化：HarmonyOS 本地安装 ID 写入应用沙箱 Preferences，杀进程或普通重启后保持不变。
• 安装 ID 直读：可直接读取插件本地安装 ID，与重置 API 形成完整闭环，不受 ANDROID_ID / IDFV 来源优先级影响。
• 合规优先：默认不默认读取 IMEI、MEID、MAC、Serial、UDID 等高风险硬件标识。
• 广告标识隔离：OAID / IDFA 只在 advertising 策略中返回能力诊断，不默认集成广告 SDK。
• 可诊断：业务能清楚知道当前 ID 来自 AndroidId、IDFV、本地安装 ID，还是平台降级。

接入方式选择

最小可运行示例

import { getDeviceIdSync } from '@/uni_modules/lizhao-device-id'

// 默认 privacy 策略：优先返回平台合规作用域 ID，失败时回落本地安装 ID。
const result = getDeviceIdSync({
  strategy: 'privacy',
  includeRawId: false
})

console.log('设备标识', result.id, result.source, result.resetHint)

读取应用安装 ID

import { getAppInstallIdSync } from '@/uni_modules/lizhao-device-id'

// 安装级匿名标识不读取 ANDROID_ID、IDFV 或广告标识。
const result = getAppInstallIdSync()
console.log('应用安装 ID', result.id, result.source, result.resetHint)

应用安装 ID 适合匿名账号、本地缓存关联和安装级去重，但不能视为永久设备身份。主动调用 resetAppInstallId()、卸载应用或清除应用数据后，该值会变化。

异步回调示例

import { getDeviceId } from '@/uni_modules/lizhao-device-id'

// 兼容 uni API 风格：success / fail / complete 均可选。
getDeviceId({
  strategy: 'stable',
  success(res) {
    console.log('获取成功', res)
  },
  fail(err) {
    console.log('获取失败', err)
  },
  complete(res) {
    console.log('获取完成', res)
  }
})

能力诊断示例

import { getDeviceIdCapability } from '@/uni_modules/lizhao-device-id'

// 用于上线前展示平台能力，也适合写入售后诊断日志。
const capability = getDeviceIdCapability()
console.log(capability.platform, capability.sources, capability.message)

API

getDeviceId(options)

说明 异步获取设备标识。

支持平台 Android / iOS / HarmonyOS / Web / 微信小程序 / 支付宝小程序

参数

返回值

getDeviceIdSync(options)

说明 同步获取设备标识。

参数

返回值

getAppInstallId(options)

说明 异步读取插件维护的应用安装 ID，不经过 ANDROID_ID、IDFV 或广告标识来源优先级。

支持平台 Android / iOS / HarmonyOS / Web / 微信小程序 / 支付宝小程序

参数

返回值

异步方法无直接返回值，结果通过回调返回。成功结果的 source 固定为 appInstallId，scope 固定为 app。

getAppInstallIdSync()

说明 同步读取插件维护的应用安装 ID。

参数

返回值

resetAppInstallId()

说明 重置插件本地安装 ID，不影响 AndroidId、IDFV、ODID、AAID、OAID、IDFA 等平台标识。

参数

返回值

getDeviceIdCapability()

说明 获取当前平台的设备标识能力矩阵。

参数

返回值

错误码

支持平台

所有已支持平台均可通过 getAppInstallId() 或 getAppInstallIdSync() 绕过平台设备标识优先级，直接读取当前插件本地安装 ID。

三端策略说明

Android

• privacy / stable：优先返回 Android Settings.Secure.ANDROID_ID。
• advertising：返回 OAID 能力诊断，不默认集成 OAID SDK。
• 不默认读取 IMEI、MEID、MAC、Serial。

iOS

• privacy / stable：优先返回 UIDevice.current.identifierForVendor。
• advertising：返回 IDFA / ATT 能力诊断，不默认请求跟踪授权。
• 不使用私有 API，不读取 UDID。

HarmonyOS

• privacy / stable：返回应用沙箱持久化的本地安装 ID；杀进程或普通重启后保持，卸载应用或清除应用数据后重置。
• advertising：返回 OAID 能力诊断，需业务按平台权限和 Kit 能力单独接入。
• 不伪造系统 ODID、AAID 或 OAID 成功结果。
• 如果 Preferences 上下文或落盘能力不可用，插件会明确返回运行期降级诊断；resetAppInstallId() 不会伪造持久化成功。

HarmonyOS 持久化验收

HarmonyOS 真机需要重新原生联编并安装新包，然后按以下顺序验证：

1. 调用 privacy 或 stable，记录当前 ID。
2. 杀进程并重新启动应用，再次调用并确认 ID 不变。
3. 调用 resetAppInstallId()，确认返回新的 ID。
4. 再次杀进程重启，确认 reset 后的新 ID 保持不变。

静态守卫、LSP、appResource 和生成 ArkTS 抽查只能证明代码与构建链路成立，不能替代真机跨进程持久化验收。

隐私与合规说明

本插件默认不默认读取 IMEI、MEID、MAC、Serial、UDID 等高风险硬件标识。业务如需广告归因，应使用 advertising 策略作为入口，并按 Android、iOS、HarmonyOS 的隐私政策、权限授权和应用市场审核要求单独接入。

• 不默认读取 IMEI。
• 不默认读取 MEID。
• 不默认读取 MAC。
• 不默认读取 Serial。
• 不默认读取 UDID。

自定义基座说明

新增或修改 utssdk/app-android、utssdk/app-ios、utssdk/app-harmony 里的原生 UTS 逻辑后，需要重新运行对应平台原生联编或重新打对应平台自定义基座。仅同步 wgt 或 appResource 不能替换旧基座里已编译的 UTS 原生部分。

uni-app x 示例验证记录

example/uniappx/index.uvue 已对齐 uni-app 示例页，覆盖当前结果、能力矩阵、隐私优先、稳定标识、广告标识检测、重置安装标识和运行日志。

2026-06-25 Android USB 自定义基座复测结果：

• privacy：返回 ANDROID_ID，permissionStatus=notRequired，supported=true。
• stable：返回同一 ANDROID_ID，用于验证稳定标识策略。
• advertising：返回 supported=false、source=oaid、permissionStatus=sdkMissing、errCode=9050003，符合未默认集成 OAID SDK 的预期。
• resetAppInstallId()：返回 success=true，随后自动刷新 privacy 结果；ANDROID_ID 不受本地安装 ID 重置影响。
• logcat 未发现插件级 FATAL EXCEPTION、ClassCastException、NoClassDefFoundError。

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。