@capacitor/preferences
The Preferences API provides a simple key/value persistent store for lightweight data.
Mobile OSs may periodically clear data set in window.localStorage
, so this
API should be used instead. This API will fall back to using localStorage
when running as a Progressive Web App.
This plugin will use
UserDefaults
on iOS and
SharedPreferences
on Android. Stored data is cleared if the app is uninstalled.
Note: This API is not meant to be used as a local database. If your app stores a lot of data, has high read/write load, or requires complex querying, we recommend taking a look at a SQLite-based solution. One such solution is Ionic Secure Storage, a SQLite-based engine with full encryption support. The Capacitor Community has also built a number of other storage engines.
Install
npm install @capacitor/preferences
npx cap sync
Apple Privacy Manifest Requirements
Apple mandates that app developers now specify approved reasons for API usage to enhance user privacy. By May 1st, 2024, it's required to include these reasons when submitting apps to the App Store Connect.
When using this specific plugin in your app, you must create a PrivacyInfo.xcprivacy
file in /ios/App
or use the VS Code Extension to generate it, specifying the usage reasons.
For detailed steps on how to do this, please see the Capacitor Docs.
For this plugin, the required dictionary key is NSPrivacyAccessedAPICategoryUserDefaults and the recommended reason is CA92.1.
Example PrivacyInfo.xcprivacy
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>NSPrivacyAccessedAPITypes</key>
<array>
<dict>
<key>NSPrivacyAccessedAPIType</key>
<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
<key>NSPrivacyAccessedAPITypeReasons</key>
<array>
<string>CA92.1</string>
</array>
</dict>
</array>
</dict>
</plist>
Example Plugin Usage
import { Preferences } from '@capacitor/preferences';
const setName = async () => {
await Preferences.set({
key: 'name',
value: 'Max',
});
};
const checkName = async () => {
const { value } = await Preferences.get({ key: 'name' });
console.log(`Hello ${value}!`);
};
const removeName = async () => {
await Preferences.remove({ key: 'name' });
};
Working with JSON
The Preferences API only supports string values. You can, however, use JSON if you JSON.stringify
the object before calling set()
, then JSON.parse
the value returned from get()
.
This method can also be used to store non-string values, such as numbers and booleans.
API
configure(...)
configure(options: ConfigureOptions) => Promise<void>
Configure the preferences plugin at runtime.
Options that are undefined
will not be used.
Param | Type |
---|---|
options | ConfigureOptions |
Since: 1.0.0
get(...)
get(options: GetOptions) => Promise<GetResult>
Get the value from preferences of a given key.
Param | Type |
---|---|
options | GetOptions |
Returns: Promise<GetResult>
Since: 1.0.0
set(...)
set(options: SetOptions) => Promise<void>
Set the value in preferences for a given key.
Param | Type |
---|---|
options | SetOptions |
Since: 1.0.0
remove(...)
remove(options: RemoveOptions) => Promise<void>
Remove the value from preferences for a given key, if any.
Param | Type |
---|---|
options | RemoveOptions |
Since: 1.0.0
clear()
clear() => Promise<void>