更新记录

1.0.7（2026-06-18）

api优化

1.0.6（2026-06-11）

增加设备品牌信息返回

1.0.5（2026-05-13）

android oaid同步获取优化

平台兼容性

uni-app(5.0)

uni-app x(5.0)

hl-deviceid-uts

读取设备唯一标识、OAID、AndroidID、设备品牌信息的 UTS 插件，当前支持 Android、iOS、HarmonyOS。

功能

• 获取聚合后的设备标识信息 getDeviceIdentifierInfo()
• 获取聚合后的设备标识信息 getDeviceIdentifierInfoAsync()
• 获取设备唯一标识 getDeviceUniqueId()
• 获取 OAID
• 获取 AndroidID
• 获取 IDFV（通过 getDeviceIdentifierInfo().idfv 读取）
• 获取设备品牌信息（通过 getDeviceIdentifierInfo().brand / .model / .systemName / .systemVersion 读取）

安装与引用

import * as DeviceId from '@/uni_modules/hl-deviceid-uts'

使用示例

// Android / iOS 可以直接同步读取当前结果。
const info = DeviceId.getDeviceIdentifierInfo()

console.log('deviceUniqueId', info.deviceUniqueId)
console.log('deviceUniqueIdSource', info.deviceUniqueIdSource)
console.log('oaid', info.oaid)
console.log('androidId', info.androidId)
console.log('idfv', info.idfv)
console.log('oaidSupported', info.oaidSupported)
console.log('brand', info.brand)
console.log('model', info.model)
console.log('systemName', info.systemName)
console.log('systemVersion', info.systemVersion)

const deviceUniqueId = DeviceId.getDeviceUniqueId()
const oaid = DeviceId.getOAID()
const androidId = DeviceId.getAndroidID()

// Android 等待厂商 OAID 服务回调、HarmonyOS 首次获取 OAID 时，建议优先使用异步接口。
DeviceId.getDeviceIdentifierInfoAsync((asyncInfo) => {
  console.log('async oaid', asyncInfo.oaid)
  console.log('async deviceUniqueId', asyncInfo.deviceUniqueId)
  console.log('async source', asyncInfo.deviceUniqueIdSource)
})

返回结构

type DeviceIdentifierInfo = {
  platform: string
  deviceUniqueId: string
  deviceUniqueIdSource: string
  oaid: string | null
  androidId: string | null
  idfv: string | null
  oaidSupported: boolean
  brand: string
  model: string
  systemName: string
  systemVersion: string
}

字段说明

• deviceUniqueId Android 优先取 OAID，其次取 AndroidID，最后回退到插件持久化生成的 UUID。 iOS 优先取 IDFV，取不到时回退到插件持久化生成的 UUID。 HarmonyOS 优先取 OAID，取不到时回退到插件持久化生成的 UUID。
• deviceUniqueIdSource 标识 deviceUniqueId 的来源。 Android 可取 oaid、androidId、generated。 iOS 可取 idfv、generated。 HarmonyOS 可取 oaid、generated。
• oaid Android / HarmonyOS 设备上尝试读取 OAID；读取失败、未授权或当前环境不可用时返回 null。 iOS 固定返回 null。
• androidId Android 设备上返回 AndroidID；读取失败时返回 null。 iOS / HarmonyOS 固定返回 null。
• idfv iOS 端返回 UIDevice.current.identifierForVendor?.uuidString。 Android / HarmonyOS 固定返回 null。
• brand Android 返回 Build.BRAND（如 Xiaomi、HUAWEI、samsung）。 iOS 固定返回 Apple。 HarmonyOS 返回 deviceInfo.brand（如 HUAWEI）。
• model Android 返回 Build.MODEL（如 MI 10、VOG-AL00）。 iOS 返回设备硬件型号（如 iPhone14,2，通过 sysctlbyname("hw.machine") 读取）。 HarmonyOS 返回 deviceInfo.deviceModel。
• systemName Android 固定返回 Android。 iOS 返回 UIDevice.current.systemName（即 iOS）。 HarmonyOS 固定返回 HarmonyOS。
• systemVersion Android 返回 Build.VERSION.RELEASE（如 13）。 iOS 返回 UIDevice.current.systemVersion（如 17.0）。 HarmonyOS 返回 deviceInfo.osFullName（如 5.0.0）。

平台支持

• 当前支持 Android、iOS、HarmonyOS。
• getDeviceIdentifierInfoAsync() 在 Android / HarmonyOS 端会异步读取 OAID；iOS 当前是对同步结果的回调封装，方便前端统一调用方式。

调用建议

• Android：可直接调用 getDeviceIdentifierInfo()、getDeviceUniqueId()、getOAID()、getAndroidID()；如果希望等待厂商 OAID 服务回调，建议使用 getDeviceIdentifierInfoAsync()。
• iOS：可直接调用 getDeviceIdentifierInfo() 或 getDeviceUniqueId()，返回的 deviceUniqueId 默认来自 IDFV。
• HarmonyOS：首次获取 OAID 建议调用 getDeviceIdentifierInfoAsync()，因为读取前需要检查/请求 APP_TRACKING_CONSENT 权限。
• HarmonyOS：getDeviceIdentifierInfo()、getDeviceUniqueId()、getOAID() 是同步读取当前缓存/回退值；如果还没有调用过异步接口，可能先返回本地生成的 UUID 或 null。
• 前端展示时建议只展示有值字段；oaid === null 表示当前没有拿到可用 OAID，不代表接口异常。

Android 说明

• Android 端优先读取 OAID，读取不到时回退到 AndroidID，再取不到时回退到插件本地生成并持久化保存的 UUID。
• Android 端集成本地 Android_CN_OAID-4.2.16.aar，文件位于 utssdk/app-android/libs/。
• OAID 厂商适配由 Android_CN_OAID 提供，当前覆盖华为、荣耀、小米 / Redmi / 黑鲨、vivo、OPPO / 一加 / realme、三星、联想 / 摩托罗拉、华硕、魅族、努比亚、酷派、360OS，以及 Coosea、Freeme、MSA / GMS 等通道。
• Android 端 getDeviceIdentifierInfoAsync() 会调用 Android_CN_OAID 的原生异步回调，适合三星、联想、华硕、OPPO / 一加、酷派等需要绑定系统服务的厂商通道。
• 当前 Android 工程内置的 oaid_sdk_1.0.25.aar 已包含华为 com.huawei.hms.ads.identifier.AdvertisingIdClient，插件不再额外声明 com.huawei.hms:ads-identifier，避免重复类冲突。
• 荣耀设备读取 OAID 需要 com.hihonor.mcs:ads-identifier，插件已在 utssdk/app-android/config.json 中声明对应依赖和荣耀 Maven 仓库。
• 如果运行包缺少 com.huawei.hms.ads.identifier.AdvertisingIdClient 或 com.hihonor.ads.identifier.AdvertisingIdClient，对应设备会跳过 OAID 读取并回退到 AndroidID/generated，避免因为类缺失导致应用崩溃。
• 各厂商系统可能因为区域版本、隐私设置、系统服务缺失或用户关闭广告标识而返回空值；这种情况下插件会继续按 AndroidID/generated 回退。

iOS 说明

• iOS 端 deviceUniqueId 默认取 IDFV，即 UIDevice.current.identifierForVendor?.uuidString。
• 当 IDFV 不可用时，会回退到插件本地生成并持久化保存的 UUID。
• iOS 端 getOAID()、getAndroidID() 固定返回 null。
• IDFV 属于 Vendor 维度标识；同一设备上同一开发者账号下的 App 通常一致。
• 如果当前 Vendor 下的所有 App 都被卸载后重新安装，IDFV 可能变化。

HarmonyOS 说明

• HarmonyOS 端优先通过 Ads Kit 的 identifier.getOAID() 读取 OAID，失败时回退到本地 @hw-ads/ohos-oaid 桥接能力。
• 获取 OAID 需要声明 ohos.permission.APP_TRACKING_CONSENT 权限，插件已在 utssdk/app-harmony/module.json5 中声明，并在 resources/base/element/string.json 中补充权限用途说明。
• getDeviceIdentifierInfoAsync() 会检查并请求 APP_TRACKING_CONSENT 后读取 OAID；建议 HarmonyOS 端优先使用异步接口获取最新 OAID。
• 异步接口获取成功后会缓存结果，后续同步调用 getDeviceIdentifierInfo()、getDeviceUniqueId()、getOAID() 会返回最近一次缓存结果。
• 如果用户未授权、关闭跨应用关联/跟踪，或系统返回 00000000-0000-0000-0000-000000000000，插件会按无效 OAID 处理，并回退到本地生成的 UUID。
• HarmonyOS 端固定不返回 AndroidID 和 IDFV，对应字段为 null。