@capawesome-team/capacitor-secure-preferences¶

Capacitor plugin to securely store key/value pairs such as passwords, tokens or other sensitive information.

Features¶

We are proud to offer one of the most complete and feature-rich Capacitor plugins for secure storage. Here are some of the key features:

🖥️ Cross-platform: Supports Android, iOS and Web.
🔒 Secure: Store sensitive information such as passwords securely using the Android Keystore and iOS Keychain.
🤝 Compatibility: Compatible with the Biometrics plugin.
📦 SPM: Supports Swift Package Manager for iOS.
🔁 Up-to-date: Always supports the latest Capacitor version.
⭐️ Support: Priority support from the Capawesome Team.

Missing a feature? Just open an issue and we'll add it for you!

Compatibility¶

Plugin Version	Capacitor Version	Status
7.x.x	>=7.x.x	Active support

Installation¶

This plugin is only available to Capawesome Insiders. First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Attention: Replace <YOUR_LICENSE_KEY> with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a Capawesome Insider.

Next, install the package:

npm install @capawesome-team/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="CAPAWESOME_SECURE_PREFERENCES.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|false"]>
   <include domain="sharedpref" path="."/>
   <exclude domain="sharedpref" path="device.xml"/>
 </cloud-backup>
</data-extraction-rules>

Proguard¶

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

-keep class io.capawesome.capacitorjs.plugins.** { *; }

Configuration¶

No configuration required for this plugin.

Usage¶

import { SecurePreferences } from '@capawesome-team/capacitor-secure-preferences';

const clear = async () => {
  await SecurePreferences.clear();
};

const get = async () => {
  const { value } = await SecurePreferences.get({
    key: 'password',
  });
  console.log(value);
};

const keys = async () => {
  const { keys } = await SecurePreferences.keys();
  console.log(keys);
};

const remove = async () => {
  await SecurePreferences.remove({
    key: 'password',
  });
};

const set = async () => {
  await SecurePreferences.set({
    key: 'password',
    value: '123456',
  });
};

clear()¶

clear() => Promise<void>

Clear all stored keys and values.

Since: 7.0.0

get(...)¶

get(options: GetOptions) => Promise<GetResult>

Get the value associated with a key.

Param	Type
`options`	`GetOptions`

Returns: Promise<GetResult>

Since: 7.0.0

keys()¶

keys() => Promise<KeysResult>

Get a list of all stored keys.

Returns: Promise<KeysResult>

Since: 7.0.0

remove(...)¶

remove(options: RemoveOptions) => Promise<void>

Remove a value given its key.

Param	Type
`options`	`RemoveOptions`

Since: 7.0.0

set(...)¶

set(options: SetOptions) => Promise<void>

Set a value given its key.

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

Param	Type
`options`	`SetOptions`

Since: 7.0.0

Interfaces¶

GetResult¶

Prop	Type	Description	Since
`value`	`string \| null`	The retrieved value.	7.0.0

GetOptions¶

Prop	Type	Description	Since
`key`	`string`	The key associated with the stored value.	7.0.0

KeysResult¶

Prop	Type	Description	Since
`keys`	`string[]`	The available stored keys.	7.0.0

RemoveOptions¶

Prop	Type	Description	Since
`key`	`string`	The key to remove.	7.0.0

SetOptions¶

Prop	Type	Description	Since
`key`	`string`	The key associated with the stored value.	7.0.0
`value`	`string`	The value to store.	7.0.0

Changelog¶

See CHANGELOG.md.

Breaking Changes¶

See BREAKING.md.

License¶

See LICENSE.