更新记录

1.1.0（2026-08-25）

• 优化：OAID 改为原生混编反射实现（OaidHelper.kt），加密版/源码版只需放置 aar 并配置 MSA AppId 即可启用，无需修改源码；未集成时自动降级
• 新增：getDeviceIdentifierInfo 返回值增加 errorCode 错误码字段（0/1001/1002/1003/1999）
• 修复：本地 UUID 增加进程内缓存，避免并发调用生成多个不同 UUID（clearLocalUuid 同步清缓存）
• 修复：Android SharedPreferences 改用 apply() 异步写入，避免主线程卡顿
• 修复：OAID/ODID 全 0 判定增强，兼容 32 位无连字符全 0 等无效格式
• 修复：iOS 具体机型改用 UTSiOS.getModel()，不再返回笼统的 "iPhone"
• 修复：iOS 13 及以下 getIdfa 兼容 ASIdentifierManager（ATT 仅 iOS 14+）
• 修复：HarmonyOS preferences 实例缓存；marketName 为空时回退 deviceInfo.name
• 修复：Android 屏幕尺寸 Android 11+ 改用 WindowManager#getCurrentWindowMetrics
• 修复：package.json 修正 engines（uni-app-x ^4.0.0 / HBuilderX ^4.71.0）、平台兼容性（仅 uni-app-x App 三端）、删除空关键字

1.0.0（2026-08-24）

• 首次发布
• 支持 Android / iOS / HarmonyOS Next 三端
• 提供 getDeviceIdentifierInfo / getOaid / getIdfa / getDeviceBaseInfo / clearLocalUuid 五个 API
• 内置多级降级链路（Android：OAID->ANDROID_ID->UUID；iOS：IDFV->Keychain UUID；鸿蒙：ODID->OAID->UUID）
• Android 可选集成 MSA OAID SDK；iOS 通过 Keychain 实现卸载重装标识不变

平台兼容性

uni-app x(3.8.2)

其他

uts-device-id 跨端设备标识符（uni-app x / UTS 插件）

适用于 uni-app x（UTS 原生插件）的跨端设备标识插件。 支持 Android / iOS / HarmonyOS Next（鸿蒙） 三端，开箱即用，内置多级降级链路， 不依赖任何付费 SDK（OAID 需可选集成 MSA 免费 SDK）。

一、插件简介

在 uni-app x 工程中，一键获取设备匿名标识符（OAID / ANDROID_ID / IDFV / ODID）与 基础设备信息。适用于：

• 设备唯一标识 / 去重 / 激活统计
• 风控、账号安全、登录插件配套（可搭配 UniLogin 使用）
• 广告归因、灰度、埋点打点

核心设计：多级降级链路，任何一级失败自动降级到下一级，保证一定返回一个可用的主标识符。

二、安装 / 使用

1. 导入插件

将 uni_modules/kyokasanagi-devid 目录（连同 uni_modules 一起）复制到你的 uni-app x 工程根目录， 或通过 HBuilderX 插件市场安装。导入后插件会自动参与三端编译，无需额外配置即可使用 （Android 默认走 ANDROID_ID -> UUID；iOS 走 IDFV -> Keychain；鸿蒙走 ODID -> OAID -> UUID）。

2. 页面中引用

import {
  getDeviceIdentifierInfo,
  getOaid,
  getIdfa,
  getDeviceBaseInfo,
  clearLocalUuid
} from '@/uni_modules/kyokasanagi-devid'

// 获取设备标识符（主入口，自动降级）
const info = await getDeviceIdentifierInfo()
console.log('主标识:', info.mainId, '类型:', info.mainIdType)
console.log('OAID:', info.oaid, 'ANDROID_ID:', info.androidId, 'IDFV:', info.idfv, 'ODID:', info.odid)
console.log('本地UUID:', info.localUuid)

// 获取设备基础信息
const base = await getDeviceBaseInfo()
console.log(base.brand, base.model, base.system, base.platform, base.screenWidth, base.screenHeight)

// 清除本地 UUID（再次获取将生成新 UUID）
await clearLocalUuid()

⚠️ 请勿直接 import 插件 utssdk 内部各平台目录下的文件，统一从 @/uni_modules/kyokasanagi-devid 导入。

三、API 说明

getDeviceIdentifierInfo(): Promise<DeviceIdResult>

主入口。返回当前平台的主标识符及全部可用标识符。

getOaid(): Promise<string>

获取 Android 广告标识符（需集成 MSA，见下方配置，集成后自动生效）；非 Android 平台返回空串。

getIdfa(): Promise<IdfaResult>

获取 iOS 广告标识符 IDFA（独立接口，只读状态，不弹窗）。

getDeviceBaseInfo(): Promise<DeviceBaseInfoResult>

clearLocalUuid(): Promise<boolean>

清除本地持久化 UUID。清除后再次调用 getDeviceIdentifierInfo 会生成新的 UUID。

四、各平台配置

1. Android：可选集成 OAID（广告标识符）

默认 不集成，Android 开箱即用（ANDROID_ID -> UUID）。 插件内置反射式 OAID 调用（OaidHelper.kt），编译期不依赖 MSA SDK， 未集成时自动降级、不影响任何功能。加密版 / 源码版均可启用 OAID，只需：

1. 获取 MSA OAID SDK：在移动安全联盟 MSA 注册并申请 AppId，下载 OAID SDK 的 aar（常见文件名如 msa_mdid_1.0.23.aar）， 放入 uni_modules/kyokasanagi-devid/utssdk/app-android/libs/ 目录。
2. 配置 AppId：编辑 utssdk/app-android/AndroidManifest.xml，取消注释并填入 AppId：

   <application>
    <meta-data android:name="com.bun.miitmdid.APPID" android:value="你的MSA AppId" />
   </application>

3. 真机验证：OAID 仅在设备"设置 > 隐私 > 广告与隐私 > 广告跟踪"开启时可能返回非全 0 值； 模拟器上 OAID 大概率不可用（此时插件自动降级到 ANDROID_ID / UUID）。

无需修改任何源码。未放置 aar 时 OaidHelper.kt 的反射调用在运行时自动捕获异常并降级， 不影响编译与功能。

2. iOS：IDFA / ATT 授权

• 插件已在 app-ios/config.json 中声明依赖 AdSupport、AppTrackingTransparency、Security。
• 插件 不会主动弹 ATT 授权窗。需要 IDFA 时，请在宿主业务层（用户同意隐私政策后）调用 系统 ATT 授权：

  import { ATTrackingManager } from 'AppTrackingTransparency'
  // 在宿主中先弹自定义隐私说明，用户同意后再请求：
  const status = await ATTrackingManager.requestTrackingAuthorization()

• 授权后调用 getIdfa() 即可拿到 IDFA；未授权返回 status=0/2。
• 兼容性：iOS 13 及以下没有 ATT（AppTrackingTransparency）框架，getIdfa() 自动走 ASIdentifierManager 的 isAdvertisingTrackingEnabled（该 API 在 iOS 14 后废弃）； iOS 14+ 才返回 ATT 授权状态。
• iOS 的 IDFV 与 Keychain UUID 获取 不需要任何授权，开箱即用。
• 插件附带 NSUserTrackingUsageDescription 文案（app-ios/Info.plist），可自行修改。

3. HarmonyOS：ODID / OAID 权限

• 插件已在 utssdk/app-harmony/module.json5 中声明 ohos.permission.APP_TRACKING_CONSENT（ODID / OAID 读取所需）。
• 插件本身不弹授权框。宿主需在业务层（用户同意隐私政策后）通过能力访问控制 申请该权限（或由系统在首次调用时引导授权），未授权时插件自动降级到本地 UUID。
• ODID / OAID 依赖鸿蒙系统 API（@kit.DeviceInfoKit / @kit.AdsKit）支持， 建议在真机上验证；若目标 API level 不支持，可改用 @ohos.identifier.odid / @ohos.ads.oaid。

五、合规与隐私说明（重要）

1. 不获取任何硬件永久标识：本插件不提供、不承诺 IMEI / 序列号 / MAC 等 不可重置的硬件标识，符合各大应用商店隐私合规要求。
2. 所有标识均可重置：
   • ANDROID_ID：恢复出厂设置 / 部分系统"重置广告标识"后会变化；
   • OAID / IDFA / ODID：用户在系统设置中可重置；
   • 本地 UUID：卸载重装会变化（iOS 的 Keychain UUID 除外，卸载重装不变）。
3. 隐私政策申报：在你的 App 隐私政策中声明你使用了哪些标识符及用途。
4. 授权时机：涉及 IDFA（iOS）/ ODID / OAID（鸿蒙）时，请务必在用户同意隐私政策后 再触发授权与读取，建议封装"同意 -> 授权 -> 读取"流程。
5. 本插件不做任何权限弹窗、不做任何网络上报、不收集用户行为数据。

六、降级策略说明

七、真机验证清单

发布 / 集成前建议在真机逐项验证：

• [ ] Android：getDeviceIdentifierInfo() 返回 mainIdType=ANDROID_ID（默认链路）
• [ ] Android：集成 MSA aar + 配置 AppId 后，开启"广告跟踪"返回 mainIdType=OAID
• [ ] Android：关闭"广告跟踪"或未集成 aar 时，自动降级且不报错
• [ ] iOS：返回 mainIdType=IDFV；getIdfa() 未授权返回 status=0/2，授权后返回 status=3 与 IDFA
• [ ] iOS：清除本地 UUID 后再次获取生成新的 Keychain UUID；卸载重装后 Keychain UUID 不变
• [ ] HarmonyOS：授权后返回 mainIdType=ODID；未授权自动降级到本地 UUID
• [ ] 三端：连续多次调用 getDeviceIdentifierInfo() 返回同一主标识（进程内缓存一致）
• [ ] 三端：getDeviceBaseInfo() 返回品牌 / 型号 / 系统 / 屏幕尺寸

八、变更记录

见 changelog.md。

九、许可

见 license.md。