App Preferences
3.4.6The App Preferences API enables apps to store custom user-specific data and retrieve it when necessary. This allows you to enhance the UX of your apps by instrumenting them to preserve specific user settings and apply them when the app is relaunched.
The App Preferences API provides methods for updating, replacing and clearing user settings stored for the current or a specific app, as well as for all apps of the current user.
The App Preferences API is accessible through the io.prefs object.
APIobject
Description
App Preferences API.
Methods
clearmethod
Signature
() => Promise<void>
Description
Removes the user preferences for the current app.
clearAllmethod
Signature
() => Promise<void>
Description
Removes all preferences stored for the current user.
clearFormethod
Signature
(app: string) => Promise<void>
Description
Removes the user preferences for a specified app.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| app | string | Name of the app whose user preferences to remove. |
getmethod
Signature
(app?: string) => Promise<AppPreferences>
Description
Retrieves the user preferences for the current app.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| app | string | Name of the app for which to retrieve the user preferences. |
getAllmethod
Signature
() => Promise<{ all: AppPreferences[]; }>
Description
Retrieves all preferences stored for the current user.
setmethod
Signature
(data: any, options?: { app: string; }) => Promise<void>
Description
Replaces the user preferences for the current app. All existing properties will be removed and replaced with the ones supplied in the data object.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| data | any | Data to replace the existing user preferences. |
|
| options | { app: string; } | Object with an |
setFormethod
Signature
(app: string, data: any) => Promise<void>
Description
Replaces the user preferences of a specified app. All existing properties will be removed and replaced with the ones supplied in the data object.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| app | string | Name of the app whose user preferences to replace. |
|
| data | any | Data to replace the existing user preferences. |
subscribemethod
Signature
(callback: (prefs: AppPreferences) => void) => UnsubscribeFunction
Description
Subscribes for changes to the user preferences of the current app.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (prefs: AppPreferences) => void | Callback function that will be invoked once with the initial user preferences and after that on every change of the user preferences. |
subscribeFormethod
Signature
(app: string, callback: (prefs: AppPreferences) => void) => UnsubscribeFunction
Description
Subscribes for changes to the user preferences of a specified app.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| app | string | Name of the app to which to subscribe. |
|
| callback | (prefs: AppPreferences) => void | Callback function that will be invoked once with the initial user preferences and after that on every change of the user preferences. |
updatemethod
Signature
(data: any, options?: { app: string; }) => Promise<void>
Description
Updates the preferences for the current app. The properties specified in the data object will be merged with the existing user preferences. Other existing properties will remain intact, and non-existent ones will be added.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| data | any | Data to be merged with the existing user preferences. |
|
| options | { app: string; } | Object with an |
updateFormethod
Signature
(app: string, data: any) => Promise<void>
Description
Updates the preferences for a specified app. The properties specified in the data object will be merged with the existing user preferences. Other existing properties will remain intact, and non-existent ones will be added.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| app | string | Name of the app whose user preferences to update. |
|
| data | any | Data to be merged with the existing user preferences. |
AppPreferencesobject
Description
App preferences object.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| app | string | Name of the app. |
||
| data | any | Object holding the user preferences as key/value pairs. |
||
| lastUpdate | string | Timestamp of the last update of the user preferences. |