capacitor-secure-preferences

A capacitor plugin to securely store key/value pairs such as passwords, tokens, and other sensitive information.

Install

npm install capacitor-secure-preferences
npx cap sync

Android

Backup rules

To prevent the preferences file from being backed up to the cloud, you need to add backup rules to your Android project. You can read more about this in the Android documentation.

Android 11 and lower

Add the android:fullBackupContent attribute to the <application> tag in your AndroidManifest.xml file:

<application
  android:fullBackupContent="@xml/full_backup_content">
</application>

Create a new file res/xml/full_backup_content.xml with the following content:

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
  <include domain="sharedpref" path="."/>
  <exclude domain="sharedpref" path="capacitor_secure_prefs.xml"/>
</full-backup-content>

Android 12 and higher

Add the android:dataExtractionRules attribute to the <application> tag in your AndroidManifest.xml file:

<application
  android:dataExtractionRules="@xml/data_extraction_rules">
</application>

Create a new file res/xml/data_extraction_rules.xml with the following content:

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
 <cloud-backup disableIfNoEncryptionCapabilities="true">
   <include domain="sharedpref" path="."/>
   <exclude domain="sharedpref" path="capacitor_secure_prefs.xml"/>
 </cloud-backup>
</data-extraction-rules>

Proguard

If you are using Proguard (code obfuscation), you need to add the following rules to your proguard-rules.pro file:

-keep class com.carlrosales.capacitor.storage.** { *; }

Note: These Proguard rules are only needed if your app has minifyEnabled true in your build configuration. If you're not using Proguard, you can safely ignore this step.

Compatibility

• iOS: 15.0+ (uses Keychain with iCloud Keychain sync)
• Android: API level 24+ (uses EncryptedSharedPreferences)
• Web: Uses localStorage (unencrypted - for development only)

⚠️ Web Platform Warning: On Web, the value is stored unencrypted in localStorage. This is for development purposes only and should not be used in production.

Usage

import { SecurePreferences } from 'capacitor-secure-preferences';

// Set a value
await SecurePreferences.set({ key: 'password', value: 'secret123' });

// Get a value
const { value } = await SecurePreferences.get({ key: 'password' });
console.log(value); // 'secret123'

// Remove a value
await SecurePreferences.remove({ key: 'password' });

// Get all keys
const { keys } = await SecurePreferences.keys();
console.log(keys); // ['password', 'token', ...]

// Clear all values
await SecurePreferences.clear();

API

• set(...)
• get(...)
• remove(...)
• keys()
• clear()

set(...)

set(options: { key: string; value: string; }) => Promise<void>

Persist a string value for the given key.

| Param | Type | | ------------- | -------------------------------------------- | | options | { key: string; value: string; } |

get(...)

get(options: { key: string; }) => Promise<{ value: string | null; }>

Retrieve the string value for the given key. Returns null if the key is not set.

| Param | Type | | ------------- | ----------------------------- | | options | { key: string; } |

Returns: Promise<{ value: string | null; }>

remove(...)

remove(options: { key: string; }) => Promise<void>

Remove the value for the given key if it exists.

| Param | Type | | ------------- | ----------------------------- | | options | { key: string; } |

keys()

keys() => Promise<{ keys: string[]; }>

Get all stored keys.

Returns: Promise<{ keys: string[]; }>

clear()

clear() => Promise<void>

Remove all stored entries for this plugin.