更新记录

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(3.8.2)

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（广告标识符，市场主流做法），按下面 4 步操作：

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. 开启启用开关：编辑 utssdk/app-android/index.uts，取消顶部 import { getOaidImpl } from './OaidHelper.uts' 的注释， 并取消 getDeviceIdentifierInfo / getOaid 中对应调用行的注释。
4. 真机验证：OAID 仅在设备"设置 > 隐私 > 广告与隐私 > 广告跟踪"开启时可能返回非全 0 值； 模拟器上 OAID 大概率不可用（此时插件自动降级到 ANDROID_ID / UUID）。

未放置 aar 时 OaidHelper.uts 不参与编译，不影响任何功能。

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 的 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. 本插件不做任何权限弹窗、不做任何网络上报、不收集用户行为数据。

六、降级策略说明

七、变更记录

见 changelog.md。

八、许可

见 license.md。