react-native-device-uuid-cordova

React Native Turbo Module that returns a device UUID using the same native logic as cordova-plugin-device (device.uuid).

Requires React Native 0.76+ with the New Architecture (Turbo Modules) enabled.

Why this module exists

This module is primarily intended for Ionic / Cordova apps migrating to React Native.

During migration, you often need the device identifier stored on your backend to stay the same so existing users are not treated as new devices. Generic React Native libraries (for example react-native-device-info, custom Keychain-based IDs, or freshly generated UUIDs) may produce a different identifier than Ionic's device.uuid, even on the same physical device.

react-native-device-uuid-cordova avoids that break by reusing the exact native UUID sources that cordova-plugin-device uses:

| Platform | Source (same as Ionic/Cordova) | |---|---| | Android | Settings.Secure.ANDROID_ID | | iOS | NSUserDefaults["CDVUUID"] → identifierForVendor → CFUUIDCreate |

On the same device with the same bundle ID (iOS) and signing key (Android), await getUuid() returns the exact same string as device.uuid after deviceready in your Ionic app.

If you are building a new React Native app with no Ionic/Cordova history, another device-ID library may be sufficient. Use this module when UUID continuity across the Ionic → React Native migration is required.

Installation

npm install react-native-device-uuid-cordova
# or
yarn add react-native-device-uuid-cordova

iOS

cd ios && pod install

Usage

import { getUuid } from 'react-native-device-uuid-cordova';

const uuid = await getUuid();
console.log(uuid);

Before (Ionic / Cordova)

document.addEventListener('deviceready', () => {
  console.log(device.uuid);
}, false);

After (React Native)

import { getUuid } from 'react-native-device-uuid-cordova';

const uuid = await getUuid(); // same value as device.uuid

The native value is returned as-is — no transformation in JavaScript.

API

getUuid(): Promise<string | null>

Returns the device UUID.

| Platform | Native source | Storage | |---|---|---| | Android | Settings.Secure.ANDROID_ID | None (OS-provided) | | iOS | NSUserDefaults["CDVUUID"] → identifierForVendor → CFUUIDCreate | NSUserDefaults key "CDVUUID" |

TypeScript

import { getUuid, type DeviceUuid } from 'react-native-device-uuid-cordova';

Migration from Ionic / Cordova

When replacing an Ionic or Cordova app with React Native:

1. Keep the same bundle ID (iOS) and same app signing key (Android) so stored identifiers are preserved.
2. Replace device.uuid (sync, after deviceready) with await getUuid() (async).
3. The UUID string is identical — only the JavaScript API shape changes.

Example mapping in your codebase:

| Ionic / Cordova | React Native | |---|---| | device.uuid | await getUuid() | | Available after deviceready | Available after app launch (async) |

See docs/PARITY_VERIFICATION.md for how to verify UUID parity on a physical device.

Cordova parity guarantee

This module implements the same UUID algorithm as cordova-plugin-device v3.x:

• Android: Device.java — Settings.Secure.ANDROID_ID only, no fallback.
• iOS: CDVDevice.m — uniqueAppInstanceIdentifier: with CDVUUID in NSUserDefaults.

Only the bridge layer differs (Turbo Module vs Cordova plugin). The native UUID logic is unchanged.

Platform quirks

Android

• UUID is a 64-bit hex string (no dashes), e.g. "9774d56d682e549c".
• On Android 8.0+ (API 26), ANDROID_ID is scoped per app-signing key, user, and device.
• May return null if the OS returns no value — same as Cordova.

iOS

• UUID uses standard format with dashes, e.g. "A1B2C3D4-E5F6-7890-ABCD-EF1234567890".
• If CDVUUID exists in UserDefaults (from Ionic/Cordova or a prior install), that value is returned — even if identifierForVendor would differ.
• Resets when all apps from the same vendor are deleted and reinstalled.

Requirements

• React Native >= 0.76.0
• New Architecture (Turbo Modules) enabled

iOS privacy manifest

This module bundles a privacy manifest declaring NSUserDefaults access (reason CA92.1), matching cordova-plugin-device. App developers must still declare their own data collection in their app privacy manifest if the UUID is sent off-device.

Development

yarn
yarn example android
yarn example ios
yarn test
yarn lint

License

Apache-2.0 — UUID logic derived from cordova-plugin-device (Apache-2.0).