@capgo/capacitor-persistent-uuid

Persistent app UUID for Capacitor. The plugin generates one random UUID per app scope and stores it with native persistence designed to survive app reinstalls, Android Studio reinstalls, Play/App Store updates, and OS updates.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/persistent-uuid/

Compatibility

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

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

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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

Usage

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

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

// Use a custom scope when debug and production builds use different package IDs
// but should share one persistent UUID.
const scoped = await PersistentUuid.getId({ scope: 'com.example.app' });
console.log(scoped.id);

// Rotate the UUID when the user logs out or requests data reset.
const replacement = await PersistentUuid.resetId();
console.log(replacement.id);

Persistence model

• Android stores the UUID in an AccountManager account owned by the plugin authenticator. The default scope is the app package name, so the UUID can survive uninstall/reinstall and debug vs Play installs with different signing keys when the package name stays the same.
• iOS stores the UUID in Keychain using a device-only item. The default scope is the bundle identifier, and the value survives app updates and iOS updates. Keychain access still follows Apple team/bundle access rules.
• Web stores the UUID in localStorage. It is a development fallback, not a reinstall-resistant identifier.
• This is not a hardware identifier and does not survive factory reset, user account removal, Keychain clearing, or an explicit resetId() call.

API

getId(options?: PersistentUuidOptions | undefined) => Promise<PersistentUuidResult>

resetId(options?: PersistentUuidOptions | undefined) => Promise<PersistentUuidResult>

getPluginVersion() => Promise<PluginVersionResult>