Skip to content

@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:

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',
  });
};

API

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.

License

See LICENSE.