更新记录

1.0.0（2026-03-26）

首次发布跨端设备标识获取插件 支持Android、iOS、HarmonyOS三大平台 提供统一的异步/同步API接口 实现OAID、IDFA、ODID等常用设备标识获取 完善错误处理和缓存机制

平台兼容性

uni-app(4.0)

uni-app x(4.0)

其他

wt-device-id

简介

wt-device-id 提供跨端的设备标识获取能力，支持：

• Android：AndroidId、OAID
• iOS：IDFV、IDFA（ATT 授权）
• HarmonyOS：ODID、AAID

说明：不同平台的“统一入口 getDeviceId”策略不同，见下方平台说明。

支持的平台与返回策略

• Android
  • getDeviceId/getDeviceIdSync：返回 AndroidId（不自动取 OAID）
  • OAID 需要调用 getOaid/getOaidSync（getOaidSync 读取上次异步成功后的缓存）
• iOS
  • getDeviceId/getDeviceIdSync：返回 IDFV
  • 不支持 OAID（调用 getOaid/getOaidSync 会失败/返回空）
  • getIdfa 会根据授权状态触发 ATT，并在 30 秒内获取；getIdfaSync 仅在已授权时返回有效值
• HarmonyOS
  • getDeviceId/getDeviceIdSync：优先 ODID，失败则降级到 AAID

类型与回调

所有异步 API 的 options 结构为：

{
  success?: (result: { deviceId: string; idType: ...; success: boolean; errorMsg?: string }) => void
  fail?: (error: { deviceId: string; idType: ...; success: boolean; errorMsg?: string }) => void
  complete?: (result: { deviceId: string; idType: ...; success: boolean; errorMsg?: string }) => void
}

API 列表

通用

• getDeviceId(options)：异步获取通用设备 ID（Android=AndroidId，iOS=IDFV，Harmony=ODID>AAID）
• getDeviceIdSync()：同步获取通用设备 ID
• getDeviceInfo()：获取设备基本信息（品牌/型号/系统等）

Android

• getAndroidId(options) / getAndroidIdSync()
• getOaid(options)：异步获取 OAID（成功后会写入缓存）
• getOaidSync()：读取缓存（首次或未成功调用过 getOaid 时为空字符串）

iOS

• getIdfv(options) / getIdfvSync()
• getIdfa(options)：异步获取 IDFA（ATT 授权；超时兜底 30 秒）
• getIdfaSync()：仅在授权状态为“已授权”时返回有效 IDFA，否则返回空字符串
• checkIdfaAuthStatus()：返回授权状态（0 未决定 / 1 受限 / 2 拒绝 / 3 已授权）
• canGetIdfa()：是否可以直接获取 IDFA（等价于 checkIdfaAuthStatus()==3）
• requestTrackingAuthorization(callback)：主动请求 ATT 授权

HarmonyOS

• getOdid(options) / getOdidSync()
• getAaid(options)：获取 AAID
• getHarmonyDeviceId(options)：ODID > AAID 自动降级

调用示例

Android 获取 OAID（推荐）

import { getOaid, getOaidSync } from '@/uni_modules/wt-device-id'

// 异步获取并写入缓存
getOaid({
  success: (res) => {
    console.log('oaid=', res.deviceId)
    // 后续可同步读取缓存
    console.log('oaid sync=', getOaidSync())
  },
  fail: (err) => {
    console.log('oaid fail=', err.errorMsg)
  }
})

iOS 获取 IDFA

import { getIdfa } from '@/uni_modules/wt-device-id'

getIdfa({
  success: (res) => console.log('idfa=', res.deviceId),
  fail: (err) => console.log('idfa fail=', err.errorMsg)
})

注意事项

• getOaid/getOaidSync 仅 Android 支持；iOS 调用会失败/返回空。
• getOaidSync 依赖 getOaid 的异步成功缓存；未成功前为 ''。
• getIdfaSync 只有在 ATT 已授权时才会返回有效值，否则为 ''。
• 建议不要把 options.success/fail/complete 写成 async 函数（否则在某些桥接场景下可能导致回调绑定失败）。

开发文档

UTS 语法 UTS API插件 UTS uni-app兼容模式组件 UTS 标准模式组件 Hello UTS