更新记录

1.0.0（2026-06-15） 下载此版本

首次上传

平台兼容性

uni-app

uni-app x(5.07)

其他

APP-AndroidId-IDFV-ODID（apex-gu-cheng）操作文档

模块名称： 跨端设备标识获取
版本： 1.0.0
模块 ID： APP-AndroidId-IDFV-ODID
目录名称： apex-gu-cheng
插件类型： UTS 原生插件（uni_modules）
最低引擎要求： HBuilderX 3.6.8+ / uni-app 3.1.0+ / uni-app-x 3.1.0+

目录

• 1. 概述
• 2. 支持的平台
• 3. 模块结构
• 4. 安装与集成
• 5. API 参考
• 6. 使用示例
• 7. 平台行为说明
• 8. 隐私与安全说明
• 9. 常见问题与排查
• 10. 更新日志

1. 概述

本模块是一个 uni-app UTS 原生插件，用于在 uni-app / uni-app-x 项目的 App 端（原生 Android、iOS、HarmonyOS）获取当前系统的设备唯一标识符。

模块会根据运行平台自动选用对应的标识符：

重要说明： 这些标识符遵循各操作系统的隐私规则，并非永久不变的硬件标识。详见 隐私与安全说明。

2. 支持的平台

Web 端和小程序端不支持本插件，仅可用于原生 App 打包环境。

3. 模块结构

uni_modules/apex-gu-cheng/
├── package.json              # 模块配置文件
├── readme.md                 # 简要说明（英文）
├── changelog.md              # 更新日志
├── 操作文档.md               # 本文档
└── utssdk/                   # UTS SDK 核心代码
    ├── index.uts             # 统一导出入口
    ├── interface.uts         # 类型定义
    ├── unierror.uts          # 错误主题常量
    ├── app-android/
    │   ├── config.json       # Android 编译配置
    │   └── index.uts         # Android 平台实现
    ├── app-ios/
    │   ├── config.json       # iOS 编译配置（最低部署目标 iOS 12）
    │   └── index.uts         # iOS 平台实现
    └── app-harmony/
        ├── config.json       # HarmonyOS 编译配置
        └── index.uts         # HarmonyOS 平台实现

文件职责说明

4. 安装与集成

4.1 导入模块

本模块已位于项目的 uni_modules 目录下，无需额外安装。在需要使用的地方直接 import：

import {
  getDeviceUniqueId,
  getDeviceUniqueIdInfo
} from '@/uni_modules/apex-gu-cheng'

4.2 注册回调接口（可选）

本模块已实现 Android 侧的两个回调函数，无需额外注册，直接调用即可：

• getAndroidIdSync() — 同步获取 Android ID
• getAndroidIdAsync() — 异步获取 Android ID 结果对象

4.3 编译要求

• HBuilderX 版本 ≥ 3.6.8
• uni-app 版本 ≥ 3.1.0 / uni-app-x 版本 ≥ 3.1.0
• iOS 最低部署目标：iOS 12（详见 utssdk/app-ios/config.json）

5. API 参考

5.1 导出函数

本模块共导出 4 个函数：

注意： getAndroidIdSync 和 getAndroidIdAsync 是为了兼容旧版 API 而保留的别名，在 iOS / HarmonyOS 上也能正常工作。推荐新项目使用 getDeviceUniqueId 和 getDeviceUniqueIdInfo。

5.2 数据类型

DeviceUniqueIdResult

type DeviceUniqueIdResult = {
  id: string                              // 设备标识字符串
  platform: 'android' | 'harmony' | 'ios' | 'unknown'  // 当前平台
  idType: 'ANDROID_ID' | 'ODID' | 'IDFV' | 'UNKNOWN'   // 标识类型
  success: boolean                        // 是否成功获取
  errorMsg?: string                       // 失败时的错误信息
}

GetAndroidIdResult

type GetAndroidIdResult = {
  androidId: string     // Android ID 字符串
  success: boolean      // 是否成功
  errorMsg?: string     // 失败时的错误信息
}

平台枚举

type DeviceIdPlatform = 'android' | 'harmony' | 'ios' | 'unknown'
type DeviceIdType = 'ANDROID_ID' | 'ODID' | 'IDFV' | 'UNKNOWN'

6. 使用示例

6.1 基础用法 — 获取设备标识字符串

import { getDeviceUniqueId } from '@/uni_modules/apex-gu-cheng'

const deviceId: string = getDeviceUniqueId()

if (deviceId != '') {
  // 使用 deviceId 进行后续操作，例如绑定设备、上报日志等
  console.log('设备标识:', deviceId)
} else {
  console.warn('无法获取设备标识')
}

6.2 完整用法 — 获取结构化信息

import { getDeviceUniqueIdInfo } from '@/uni_modules/apex-gu-cheng'

const info = getDeviceUniqueIdInfo()

console.log('平台:', info.platform)       // 如 'android'
console.log('标识类型:', info.idType)     // 如 'ANDROID_ID'
console.log('是否成功:', info.success)    // true / false
console.log('标识值:', info.id)           // 标识字符串

if (!info.success) {
  console.error('获取失败:', info.errorMsg)
}

6.3 实际项目中的使用（来自 pages/index/index.uvue）

import { getDeviceUniqueId, getDeviceUniqueIdInfo } from '@/uni_modules/apex-gu-cheng'

// 场景 1：将设备标识作为序列号用于表单提交
formData.value.sn = getDeviceUniqueId()

// 场景 2：查询设备绑定状态
queryStatus(getDeviceUniqueId()).then(res => {
  // 处理绑定状态查询结果
})

6.4 完整页面示例（来自 pages/id-photo/index.uvue）

import { ref } from 'vue'
import { getDeviceUniqueId, getDeviceUniqueIdInfo } from '@/uni_modules/apex-gu-cheng'

const deviceId = ref('')
const platform = ref('未检测')
const idType = ref('未检测')
const errorMsg = ref('')
const success = ref(false)
const statusText = ref('等待检测')

const detectDeviceId = () => {
  const id = getDeviceUniqueId()
  const info = getDeviceUniqueIdInfo()

  deviceId.value = id
  platform.value = info.platform
  idType.value = info.idType
  success.value = info.success
  errorMsg.value = info.errorMsg ?? ''
  statusText.value = info.success ? '检测成功' : '检测失败'

  console.log('getDeviceUniqueId:', id)
  console.log('getDeviceUniqueIdInfo:', info)
}

// 页面加载时自动检测
detectDeviceId()

完整页面代码见 pages/id-photo/index.uvue

7. 平台行为说明

7.1 Android

标识类型: ANDROID_ID
来源: Settings.Secure.ANDROID_ID

返回值说明：

• 正常情况下返回一个 64 位十六进制字符串（如 9774d56d682e549c）
• 在极少数设备或异常情况下可能返回 ""（空字符串），此时 success 为 false，errorMsg 为 "Android ID is empty"

ANDROID_ID 的稳定性：

• 在同一设备上，相同签名、相同用户的 App 获取的 ANDROID_ID 是一致的
• 以下情况可能导致 ANDROID_ID 改变：
  • 设备恢复出厂设置
  • Android 8.0+ 中，不同签名的 App 获取的值不同
  • 某些厂商 ROM 可能会返回固定值（如全为 0）

7.2 iOS

标识类型: IDFV (identifierForVendor)
来源: UIDevice.current.identifierForVendor

返回格式： UUID 字符串（如 E621E1F8-C36C-495A-93FC-0C247A3E6E5F）

IDFV 的稳定性：

• 同一厂商（Vendor）的所有 App 之间共享相同的 IDFV
• 当用户卸载该厂商的所有 App 后重新安装时，IDFV 可能会变化
• 设备重启不影响 IDFV

权限要求： 无需额外权限声明，iOS 系统内置 API。

7.3 HarmonyOS

标识类型: ODID (Open Device Identifier)
来源: @kit.BasicServicesKit.deviceInfo.ODID

ODID 的稳定性：

• 同一设备上的同一应用获取的 ODID 是固定的
• 应用卸载后重装，ODID 一般不变
• 设备恢复出厂设置后 ODID 会改变

依赖： 需要在 utssdk/app-harmony/config.json 中声明 @kit.BasicServicesKit 依赖。

8. 隐私与安全说明

8.1 标识符限制

以上标识都是操作系统提供的软件层标识符，不是硬件级别的唯一标识（如 IMEI、序列号）。请勿依赖它们作为永久不变的用户追踪标识。

8.2 合规建议

1. 本模块不会自动上传任何设备标识到服务器
2. 如果应用需要将设备标识发送给服务端，请在隐私政策中声明
3. 建议将设备标识仅用于：
   • 设备绑定 / 激活
   • 日志关联
   • 反作弊 / 风控
4. 不要将设备标识用作用户画像或行为追踪

9. 常见问题与排查

Q1：返回的 id 为空字符串怎么办？

可能原因：

• Android： 模拟器运行、设备未登录 Google 账户（部分旧版本）、系统权限限制
• iOS： 模拟器运行、系统异常
• HarmonyOS： 模拟器运行、@kit.BasicServicesKit 不可用

解决方案：

const info = getDeviceUniqueIdInfo()
if (!info.success) {
  // 降级方案：使用本地生成的 UUID 作为备选标识
  // 注意：此 UUID 在 App 卸载后会丢失
  const fallbackId = uni.getStorageSync('__device_fallback_id__') || generateUUID()
  uni.setStorageSync('__device_fallback_id__', fallbackId)
}

Q2：Web 端或小程序端能用吗？

不能。 本插件是 UTS 原生插件，仅在 App 原生环境（Android / iOS / HarmonyOS）中可用。Web 端和小程序端会因平台不匹配而无法使用。

Q3：Android 8.0+ 不同签名的 App 获取的 ANDROID_ID 相同吗？

不相同。 Android 8.0（API 26）起，ANDROID_ID 的作用域限定为应用签名 + 用户的组合。不同签名的 App 在同一设备上获取的值不同。

Q4：iOS 上 IDFV 什么时候会改变？

当用户卸载该设备上同一 Vendor 的所有 App 后，IDFV 会被系统重置。只要设备上保留有该 Vendor 的至少一个 App，IDFV 就会保持稳定。

Q5：编译报错或找不到模块路径？

确认项目运行的 HBuilderX 版本 ≥ 3.6.8，且 manifest.json 中已正确配置 App 原生打包。如果使用 uni-app-x，版本需 ≥ 3.1.0。

Q6：能否直接获取 IMEI / IDFA 等更精确的标识？

不建议。 获取 IMEI / IDFA 需要额外的运行时权限（Android）或 ATT 授权（iOS），且可能违反应用商店审核政策。本模块使用的 ANDROID_ID / IDFV / ODID 是无需额外权限的系统 API。

10. 更新日志

v1.0.0（当前版本）

• 初始发布
• 支持 Android（ANDROID_ID）、iOS（IDFV）、HarmonyOS（ODID）三端
• 提供 getDeviceUniqueId / getDeviceUniqueIdInfo 跨平台统一接口
• 提供 getAndroidIdSync / getAndroidIdAsync 兼容接口

技术支持： 如需帮助，请联系模块作者（详见 package.json 中的联系方式）。
文档生成日期： 2026-06-16