指南
如何在 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 后不会保留。
完整参考
- GitHub: https://github.com/Cap-go/capacitor-persistent-uuid/
- 文档:/docs/plugins/persistent-uuid/
继续
如果你正在使用 @capgo/capacitor-persistent-uuid 如需保持应用身份稳定,请将其与以下服务关联: @capgo/capacitor-persistent-uuid 查看概览, 快速入门 安装及 API 示例,请访问 Android 行为 有关重新安装的详细信息,请参阅: iOS 行为 有关 Keychain 的详细信息,以及 @capgo/capacitor-persistent-account 当你需要持久化账户数据而不是 UUID 时。