Getting Started

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-persistent-uuid`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/persistent-uuid/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

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/capgo-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-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

Import

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

Read Or Create The 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);

The first call creates and stores a UUID. Later calls return the same UUID for the same scope.

Use A Stable Custom Scope

The native default scope is the package name on Android and the bundle identifier on iOS. If debug and production builds use different package identifiers but should share one UUID, pass a shared scope.

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

Reset The UUID

Call resetId when the user logs out, requests a privacy reset, or when automated tests need a new identifier.

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

Persistence Expectations

Android can survive uninstall and reinstall, including Android Studio and Play installs with different signing keys, when the package name or custom scope is stable.
iOS survives app updates and iOS updates while Keychain access rules remain the same.
Web uses localStorage and is only a development fallback.

Keep going from Getting Started

If you are using Getting Started to add persistent app identity, connect it with @capgo/capacitor-persistent-uuid for the overview, Android behavior for reinstall behavior, iOS behavior for Keychain behavior, Using @capgo/capacitor-persistent-uuid for the tutorial, and Capgo Plugin Directory for other native plugins.