@capawesome-team/capacitor-secure-preferences¶
Capacitor plugin to securely store key/value pairs such as passwords, tokens or other sensitive information.
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: First-class support from the Capawesome Team.
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:
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:
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:
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:
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',
});
};
API¶
clear()¶
Clear all stored keys and values.
Since: 7.0.0
get(...)¶
Get the value associated with a key.
Param | Type |
---|---|
options |
GetOptions |
Returns: Promise<GetResult>
Since: 7.0.0
keys()¶
Get a list of all stored keys.
Returns: Promise<KeysResult>
Since: 7.0.0
remove(...)¶
Remove a value given its key.
Param | Type |
---|---|
options |
RemoveOptions |
Since: 7.0.0
set(...)¶
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.
License¶
See LICENSE.