跳转至正文
@capgo/capacitor-persistent-uuid 身份验证与安全 开源

持久化 UUID Capacitor 插件

生成并持久化一个应用级 UUID,在重装、应用更新和系统更新后保持不变

安装

bun add @capgo/capacitor-persistent-uuid bunx cap sync
npm、pnpm 或 yarn
  • npm install @capgo/capacitor-persistent-uuid
  • pnpm add @capgo/capacitor-persistent-uuid
  • yarn add @capgo/capacitor-persistent-uuid

指南

如何在 Capacitor 中使用 Persistent UUID

使用 @capgo/capacitor-persistent-uuid

为 Capacitor 生成一个应用级持久 UUID,并在常规应用存储会被清除的重装和更新流程中保持稳定。

安装

npm install @capgo/capacitor-persistent-uuid
npx cap sync

插件暴露的内容

  • getId - 读取已存储的 UUID,如果所选 scope 下不存在则创建一个。
  • resetId - 轮换已存储的 UUID,用于登出、隐私重置或测试清理流程。
  • scope - 可选的命名空间,适用于调试版和生产版包标识符不同的应用。

用法示例

import { PersistentUuid } from '@capgo/capacitor-persistent-uuid';

const { id, created, scope } = await PersistentUuid.getId();

console.log(id);
console.log(created);
console.log(scope);

在不同 Build 变体间共享同一个 UUID

const result = await PersistentUuid.getId({
  scope: 'com.example.app',
});

console.log(result.id);

重置标识符

const replacement = await PersistentUuid.resetId();
console.log(replacement.id);

平台注意事项

Android 将 UUID 存储在 AccountManager 中,以便在包名或自定义 scope 稳定的情况下,能够经受 Android Studio 重装循环以及调试签名与 Play 签名之间的差异。iOS 将 UUID 存储在 Keychain 中,并在 Keychain 访问保持兼容的情况下,使其在应用和 iOS 更新中保留。Web 使用 localStorage 作为开发回退方案。

此插件不暴露硬件 ID,且在恢复出厂设置、手动删除账户、清除 Keychain、清除浏览器存储或调用 resetId 后不会保留。

完整参考

继续

如果你正在使用 @capgo/capacitor-persistent-uuid 如需保持应用身份稳定,请将其与以下服务关联: @capgo/capacitor-persistent-uuid 查看概览, 快速入门 安装及 API 示例,请访问 Android 行为 有关重新安装的详细信息,请参阅: iOS 行为 有关 Keychain 的详细信息,以及 @capgo/capacitor-persistent-account 当你需要持久化账户数据而不是 UUID 时。

常见问题

Persistent UUID 插件常见问题

如何在 Capacitor 应用中安装 Persistent UUID 插件?

运行 "bun add @capgo/capacitor-persistent-uuid"(或 "npm install @capgo/capacitor-persistent-uuid"),然后运行 "bunx cap sync",以便 iOS 和 Android 项目获取原生 code。在应用 code 中从 "@capgo/capacitor-persistent-uuid" 导入它。

@capgo/capacitor-persistent-uuid 支持 React、Vue 和 Angular 吗?

是的。Persistent UUID 是一个 Capacitor 包,因此它适用于任何在 Capacitor 中运行的 Web 框架,包括 Ionic、React、Vue、Angular、Svelte 和纯 JavaScript。

@capgo/capacitor-persistent-uuid 支持哪个版本的 Capacitor?

Capgo 插件遵循 Capacitor 的主版本号:请使用与 Capacitor 主版本号一致的插件主版本(例如插件 v8 对应 Capacitor 8)。GitHub README 中的兼容性表列出了仍在维护的版本。

@capgo/capacitor-persistent-uuid 是免费且开源的吗?

是的。code 的源代码在 GitHub 上公开,地址为 https://github.com/Cap-go/capacitor-persistent-uuid/,并且可以从 npm 免费安装。欢迎提交 Bug 报告和 Pull Request。

我能否在不经过 App Store 审核的情况下更新使用 Persistent UUID 的 code?

安装或升级插件会改动原生 code,因此需要重新做一次商店构建。之后,调用该插件的 JavaScript、HTML 和 CSS 改动就能通过 Capgo live updates 立即发布。

无需等待应用审核,即可发布 Persistent UUID 变更

只要插件已包含在你的商店版本中,Capgo live updates 就能在几分钟内把 JavaScript、HTML 和 CSS 的改动推送给用户。

开始使用 Capgo