更新记录

1.0.6（2026-09-15）

• 修复 Android 运行编译时提示设备标识能力类型不存在、导致项目无法正常编译的问题。
• 整理接入文档，按使用场景分模块展示示例，为参数、返回结果和失败处理补充注释，并将 API、错误码与常见问题集中到文档下方。
• 升级后无需修改项目配置或调用代码，已有安装 ID 不会主动重置；需要重新进行 Android 原生联编，或重新制作并安装 Android 自定义基座。

1.0.5（2026-09-14）

• 新增 getPersistentInstallId() 和 getPersistentInstallIdSync()：Android 使用 ANDROID_ID，iOS 使用 Keychain UUID，HarmonyOS API 12+ 使用 Asset Store 持久 UUID。
• 新增 stabilityLevel、maySurviveReinstall、resettableByPlugin 和 sourceCapabilities，可区分安装级、平台级、尽力跨卸载以及仅诊断来源。
• Web 和小程序会明确返回不支持，不再以 storage 安装 ID 冒充跨卸载标识；OAID、IDFA、ODID、AAID 仍只提供能力诊断。
• 现有 getDeviceId*、getAppInstallId* 和命名空间 API 无需修改调用，原有安装 ID 数据不会主动迁移或重置。
• Android/iOS/HarmonyOS 均涉及原生实现或配置变化，升级后需要重新制作并安装对应平台自定义基座或 HarmonyOS HAP。

1.0.3（2026-07-28）

• 新增 getAppInstallId() 和 getAppInstallIdSync()，可直接读取插件维护的应用安装 ID，不再依赖 ANDROID_ID / IDFV 的来源优先级。
• Android、iOS、HarmonyOS、Web、微信小程序和支付宝小程序统一返回 source=appInstallId、scope=app 的结构化结果。
• Web 与小程序存储不可用时复用进程级临时 ID，并返回 9050004 诊断；重置未持久化时明确返回失败，不伪造成功。
• uni-app 与 uni-app x 示例新增“读取安装标识”，重置后直接展示新安装 ID，形成读取、重置、再次读取的完整验收链路。
• 保持既有 privacy / stable / advertising 行为不变，不新增权限、三方 SDK、Manifest 或广告标识采集。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-device-id

设备唯一标识 UTS插件，为 uni-app / uni-app x 提供设备标识、应用安装 ID、按业务隔离的安装 ID，以及尽力跨卸载保留的标识。返回结果会同时说明 ID 来源、可用状态和可能变化的条件。

功能特色

适用场景

• 匿名使用：用户尚未登录时，关联本次安装的偏好和草稿。
• 多业务应用：一个 App 中的不同业务分别使用独立安装 ID。
• 重复安装识别：读取尽力跨卸载标识，作为业务判断的辅助信息。
• 接入排查：查看 ID 来源、存储状态和中文诊断，判断本次结果是否可用。

快速开始：读取第一个标识

在插件市场选择“使用 HBuilderX 导入插件”，导入到项目后即可从插件根目录引用，无需调用初始化方法。

下面是一个可放入 uni-app x Vue 3 页面中的完整示例。uni-app Vue 3 使用 .vue 页面时，将 lang="uts" 改成 lang="ts"；uni-app Vue 2 的完整写法见下方“完整示例”。

<template>
  <view>
    <button @click="readId">读取设备标识</button>
    <text>{{ message }}</text>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import { getDeviceIdSync } from '@/uni_modules/lizhao-device-id'

// 页面展示内容；按钮点击后更新为本次读取结果。
const message = ref('点击按钮读取')

function readId() {
  // 不传参数使用默认 privacy 策略，优先读取当前平台可用来源。
  const result = getDeviceIdSync()
  if (!result.supported || result.id == '') {
    // 不可用时展示原因，不把空字符串保存为业务标识。
    message.value = '读取失败：' + result.reason
    return
  }
  // ID 应与来源一起理解；不同平台取得的 ID 类型可能不同。
  message.value = '标识：' + result.id + '，来源：' + result.source
}
</script>

核心参数与结果判断

先选择适合的 API

按业务模块使用

每个模块的代码均可独立选用。将 import 放到页面脚本顶部，将读取逻辑放到按钮方法、业务函数或合适的页面生命周期中；不要在高频渲染过程中反复读取。

模块一：读取设备标识并处理回调

适合希望在回调中更新页面或接入业务逻辑的场景。同步调用使用快速开始中的 getDeviceIdSync()。

import { getDeviceId } from '@/uni_modules/lizhao-device-id'

getDeviceId({
  strategy: 'privacy', // 默认策略，具体来源由当前平台决定。
  includeRawId: false, // 不额外返回 rawId；id 仍然是本次标识值。
  success(res) {
    // success 可能收到结构化诊断，不代表一定取得了可用 ID。
    if (!res.supported || res.id == '') {
      console.log('本次标识不可用', res.errCode, res.reason)
      return
    }
    console.log('设备标识', res.id, '来源', res.source)
    // 如需保存，应同时记录 source、scope，便于解释来源和范围。
    console.log('作用域', res.scope, '稳定级别', res.stabilityLevel)
  },
  fail(err) {
    // 原生上下文不可用等硬失败进入此回调。
    console.log('读取失败', err.errCode, err.errMsg)
  },
  complete() {
    // 成功或失败后都会执行，可在这里结束页面加载状态。
    console.log('设备标识读取结束')
  }
})

模块二：读取本次安装的 ID

适合匿名偏好、草稿归属等安装级用途。此 API 直接读取插件维护的安装 ID，不会优先选择 ANDROID_ID 或 IDFV。

import { getAppInstallIdSync } from '@/uni_modules/lizhao-device-id'

// 多次读取同一安装 ID；主动重置或安装数据丢失后可能变化。
const result = getAppInstallIdSync()
if (!result.supported || result.id == '') {
  console.log('安装 ID 不可用', result.reason)
} else if (result.errCode == 9050004) {
  // 存储不可用时可能返回临时 ID，不能据此认定下次启动仍相同。
  console.log('当前仅使用临时安装 ID', result.id, result.reason)
} else {
  console.log('安装 ID', result.id, '来源', result.source)
}

如需回调形式，使用 getAppInstallId(options)，提供 success / fail / complete 即可；结果仍应检查 supported、id 和 errCode。

模块三：为不同业务分配独立 ID

“命名空间”就是用于隔离 ID 的业务名称。同一个名称重复读取同一个 ID，不同名称各自保存。

import { getNamespacedInstallIdSync } from '@/uni_modules/lizhao-device-id'

// 使用固定业务名称，不要每次用时间戳或随机数创建新的命名空间。
const namespace = 'tenant-demo'
const result = getNamespacedInstallIdSync(namespace)
if (!result.supported || result.id == '') {
  console.log('业务安装 ID 不可用', result.errCode, result.reason)
} else if (!result.persistent) {
  // 有 ID 但未确认持久化，仅适合当前进程内临时使用。
  console.log('业务安装 ID 尚未持久化', result.id, result.reason)
} else {
  console.log('业务名称', result.namespace, '安装 ID', result.id)
}

需要回调时，使用下面的形式：

import { getNamespacedInstallId } from '@/uni_modules/lizhao-device-id'

getNamespacedInstallId({
  namespace: 'tenant-demo', // 必填，决定读取哪个业务的安装 ID。
  success(res) {
    // 存储降级也会进入 success，持久使用前需检查 persistent。
    if (!res.supported || res.id == '' || !res.persistent) {
      console.log('业务安装 ID 暂不可持久使用', res.errCode, res.reason)
      return
    }
    console.log('业务安装 ID', res.namespace, res.id)
  },
  fail(err) {
    // 名称非法或原生上下文不可用时进入这里。
    console.log('读取业务安装 ID 失败', err.errCode, err.errMsg)
  },
  complete() {
    // 可在这里结束加载状态。
    console.log('业务安装 ID 读取结束')
  }
})

命名空间长度为 1 至 64 位，只允许 ASCII 字母、数字、.、_、-。插件不自动去除空格或转换大小写，tenant-demo 与 Tenant-demo 是两个名称；非法名称返回 9050005。

模块四：读取尽力跨卸载保留的标识

适合辅助判断重复安装。它表示在同设备、同应用身份等条件下可能保留，不代表永久不变。

import { getPersistentInstallIdSync } from '@/uni_modules/lizhao-device-id'

// Android、iOS、HarmonyOS 使用各自的持久来源，具体边界见下方平台说明。
const result = getPersistentInstallIdSync()
if (!result.supported || result.id == '' || !result.persistent) {
  // 不支持或持久来源不可用时，不用普通安装 ID 冒充跨卸载标识。
  console.log('持久标识不可用', result.errCode, result.reason)
} else {
  console.log('持久标识', result.id, '来源', result.source)
  // 这些字段解释当前能力与变化条件，不是永久稳定承诺。
  console.log('可能跨卸载保留', result.maySurviveReinstall)
  console.log('可能变化的条件', result.resetHint)
}

回调形式如下，只有取得非空的可用持久标识才进入 success：

import { getPersistentInstallId } from '@/uni_modules/lizhao-device-id'

getPersistentInstallId({
  success(res) {
    // 业务保存时同时记录来源，方便后续区分平台和标识类型。
    console.log('持久标识', res.id, '来源', res.source)
  },
  fail(err) {
    // Web/小程序不支持，或系统持久来源不可用时进入此回调。
    console.log('持久标识读取失败', err.errCode, err.errMsg)
  },
  complete() {
    // 成功或失败后均可在这里结束加载状态。
    console.log('持久标识读取结束')
  }
})

模块五：重置默认安装 ID 或单个业务 ID

重置会改变后续读取结果，适合由用户主动触发的“重置匿名身份”等操作。下面只声明操作函数，接入时由确认后的按钮调用，不会在页面加载时自动重置。

import { resetAppInstallId, resetNamespacedInstallId } from '@/uni_modules/lizhao-device-id'

// 用户确认后调用：仅更新默认安装 ID，不修改系统设备标识。
function resetDefaultInstallId() {
  const result = resetAppInstallId()
  if (!result.success) {
    console.log('默认安装 ID 重置失败', result.reason)
    return
  }
  console.log('新的默认安装 ID', result.appInstallId)
}

// 用户确认后调用：仅更新 tenant-demo，不影响其他名称或默认安装 ID。
function resetTenantInstallId() {
  const result = resetNamespacedInstallId('tenant-demo')
  if (!result.success || !result.persistent) {
    console.log('业务安装 ID 重置失败', result.errCode, result.reason)
    return
  }
  console.log('新的业务安装 ID', result.namespace, result.appInstallId)
}

重置成功后，请使用对应的 getAppInstallIdSync() 或 getNamespacedInstallIdSync(namespace) 再次读取。getDeviceIdSync() 可能仍返回系统标识，因此不一定随安装 ID 重置而变化。

模块六：查询真实能力与广告标识诊断

先查询能力，再判断业务需要的来源是否可用。能力表描述插件已实现的来源，不保证本次设备读取一定成功，最终以读取结果为准。

import { getDeviceIdCapability, getDeviceIdSync } from '@/uni_modules/lizhao-device-id'

// sources 只列真实实现；sourceCapabilities 还包含仅诊断的来源。
const capability = getDeviceIdCapability()
console.log('当前平台', capability.platform, capability.message)
capability.sourceCapabilities.forEach((item) => {
  // available：已实现；diagnosticOnly：仅诊断；unsupported：不支持。
  console.log('标识来源', item.source, '实现状态', item.status)
  console.log('权限或 SDK 状态', item.permissionStatus)
})

// 当前 advertising 策略不提供可用广告 ID；用于展示诊断信息。
const result = getDeviceIdSync({ strategy: 'advertising' })
if (!result.supported) {
  console.log('广告标识不可用', result.errCode, result.reason)
}

完整示例

API 速查

方法列表

Sync 方法直接返回结果；回调形式的方法返回 void，通过回调取结果，不按 Promise 使用。同步方法不要传入回调字段，回调不会执行。

参数与回调

策略区别

读取结果字段

getDeviceId* 的 Android scope='app' 保留既有兼容行为；getPersistentInstallId* 的 developer 表示 Android 签名身份、用户和设备共同限定，不是平台全局标识。

重置与能力查询结果

sourceCapabilities 每项为 DeviceIdSourceCapability：status 取 available / diagnosticOnly / unsupported。available 表示插件已实现；权限、设备条件和实际读取仍需检查具体调用结果。

错误码

错误回调中的 DeviceIdFail 包含 errSubject、errCode、errMsg，其中 errSubject 为 lizhao-device-id。同步读取使用结果中的 errCode / errMsg / reason 判断。

支持平台与标识边界

App 端支持 uni-app 与 uni-app x；降级能力以各框架支持的目标平台为前提，uni-app x 不因本插件而增加支付宝小程序支持。

OAID、IDFA、HarmonyOS ODID/AAID 当前仅作诊断，不能把能力名称出现理解为已经可以读取。Android/iOS 默认读取不需要新增权限。

常见问题

第一次接入应该选择哪一种 ID？

只关联本次安装的数据，使用 getAppInstallIdSync()；按业务隔离使用命名空间 API；需要平台设备信号使用 getDeviceIdSync()；需要辅助识别重新安装时再选持久标识 API。

卸载重装后一定不变吗？

不保证。安装 ID 依赖应用数据；持久标识也受系统、应用身份和权限影响。服务端账号、会员、授权和付费权益应使用服务端业务 ID 及登录或绑定关系恢复，不应仅依赖客户端 ID。

success 执行了，为什么 supported 还是 false？

普通读取接口会通过 success 返回结构化诊断，例如广告标识未接入。请继续判断 supported 和 id；命名空间结果还应检查 persistent。持久标识接口取得可用非空标识才会进入 success。

includeRawId: false 会隐藏或加密 ID 吗？

只让 rawId 为空，id 仍是本次取得的标识，可能就是平台原始值。插件不自动哈希或脱敏，请按业务需要决定保存与展示范围。

为什么重置成功后，设备标识看起来没变？

重置只作用于安装 ID；getDeviceIdSync() 可能优先读取 ANDROID_ID 或 IDFV。请用对应安装 ID API 检查重置结果，持久标识没有插件重置 API。

命名空间 ID 在退出账号时会自动变化吗？

不会。插件不会监听账号切换。相同名称继续返回已保存的 ID，业务需要变化时主动重置指定命名空间，或使用另一个固定名称。

杀进程或重启后，安装 ID 能继续使用吗？

持久化存储可用时可继续读取；HarmonyOS 安装 ID 使用应用 Preferences。若结果提示 9050004、stabilityLevel='process' 或 persistent=false，则不能认定下次启动还相同。清理数据、卸载及系统备份恢复也可能影响结果。

stable 比 privacy 更稳定吗？

当前两者使用相同来源链，stable 只表达调用意图，不增加保证。persistent=true 也只是说明持久读取或保存状态，不代表永久有效。

Web 或小程序能得到和 App 一样的设备 ID 吗？

不能。它们使用 storage 安装级标识，不代表原生系统设备身份；持久标识 API 明确返回不支持，不会用 storage 冒充跨卸载能力。

升级后还报旧错误，需要调整调用吗？

本次 Android 编译修复无需调整调用或项目配置。请重新进行 Android 原生联编，或重新制作并安装 Android 自定义基座；仅热更新页面资源不能更新已经编译进基座的插件代码。

注意事项

• 不默认读取 IMEI，不默认读取 MEID，不默认读取 MAC，不默认读取 Serial，不默认读取 UDID，也不默认集成广告标识 SDK。
• 升级不会主动迁移或重置默认安装 ID、命名空间 ID；系统备份恢复和应用数据变化仍可能影响实际生命周期。
• iOS Keychain 和 HarmonyOS Asset Store 的同步读取应低频调用，尽量在业务确有需要时读取。
• 使用 HarmonyOS 持久数据时，应在应用隐私说明中解释数据保留和删除方式。
• 本次 Android 修复需要匹配的原生基座；如果还未接入此前的 iOS/HarmonyOS 持久能力，也需使用包含对应原生实现和配置的基座或 HAP。