快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-persistent-uuid` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-persistent-uuid
bunx cap sync

快速入门

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

const result = await PersistentUuid.getId();
console.log(result);

示例：resetId

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

const result = await PersistentUuid.resetId();
console.log(result);

常见坑点

• 原生同步：运行 bunx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

导入

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

读取或创建 UUID

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

const result = await PersistentUuid.getId();

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

首次调用会创建并存储一个 UUID。后续针对相同 scope 的调用将返回同一个 UUID。

使用稳定的自定义 scope

原生默认 Scope 是 Android 上的包名和 iOS 上的 Bundle Identifier。如果 Debug 和 Production 构建使用不同的包标识符但需要共享同一个 UUID，请传入一个共享的 Scope。

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

重置 UUID

当用户退出登录、请求隐私重置或自动化测试需要新标识符时，请调用 resetId。

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

持久化预期

• 只要包名或自定义 Scope 保持稳定，Android 即可在卸载并重新安装后保持数据，包括使用不同签名密钥的 Android Studio 或 Play Store 安装。
• 只要 Keychain 访问规则保持不变，iOS 即可在 App 更新和 iOS 系统更新后保持数据。
• Web 端使用 localStorage，仅作为开发环境的备选方案。

从入门指南继续

如果你正在使用 快速入门 若要添加持久化应用身份，请将其连接至 @capgo/capacitor-persistent-uuid 查看概览， Android 行为 查看重新安装行为， iOS 行为 查看 Keychain 行为， 使用 @capgo/capacitor-persistent-uuid 在本教程中， Capgo 插件目录 用于其他原生插件。