App Preferences

Available since io.Connect Browser 3.2

The 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.

App preferences can be stored locally in a file, or remotely - using io.Manager. By default, app preferences are stored locally using the IndexedDB API of the browser. To configure io.Connect Browser where to store app preferences, use the store property of the applicationPreferences top-level key in the configuration object for initializing the @interopio/browser-platform library.

The following example demonstrates configuring the @interopio/browser-platform to store app preferences in io.Manager:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    // Settings for storing app preferences.
    applicationPreferences: {
        store: {
            type: "manager"
        }
    },
    manager: {
        // Settings for connecting to io.Manager.
    }
};

const { io } = await IOBrowserPlatform(config);

The "store" object has the following properties:

⚠️ Note that if you want to use io.Manager as an app preferences store, you must also provide the necessary settings for connecting to it by using the manager property of the Config object. For more details see the io.Manager section.

The App Preferences API is accessible through the io.prefs object.

To retrieve the stored app preferences for the current app, use the get() method:

const prefs = await io.prefs.get();

This method resolves with an AppPreferences object with the following properties:

To retrieve the stored app preferences for a specific app, pass an app name to the get() method:

const appName = "clientlist";
const prefs = await io.prefs.get(appName));

To retrieve the stored app preferences for all apps of the current user, use the getAll() method:

const prefs = await io.prefs.getAll();

// The returned object has an `all` property which contains a list of `AppPreferences` objects.
prefs.all.forEach(console.log);

To set the preferences for the current app, use the set() method:

const prefs = { fontSize: 18 };

await io.prefs.set(prefs);

The set() method replaces entirely the stored app preferences. All existing properties of the AppPreferences object associated with the app will be removed and replaced with the ones of the argument provided to the set() method.

To set the preferences for a specific app, pass an options object as a second argument to the set() method and specify the name of the app:

const prefs = { fontSize: 18 };
const options = { app: "clientlist" };

await io.prefs.set(prefs, options);

To update the preferences for the current app, use the udpate() method:

const prefs = { fontSize: 18 };

await io.prefs.update(prefs);

The update() method modifies only the properties provided in the update object. All other existing properties of the AppPreferences object associated with the app will remain intact.

To update the preferences for a specific app, pass an options object as a second argument to the update() method and specify the name of the app:

const prefs = { fontSize: 18 };
const options = { app: "clientlist" };

await io.prefs.update(prefs, options);

To remove the stored app preferences for the current app, use the clear() method:

await io.prefs.clear();

To remove the stored app preferences for a specific app, pass an app name to the clear() method:

const appName = "clientlist";

await io.prefs.clear(appName);

To remove the stored app preferences for all apps of the current user, use the clearAll() method:

await io.prefs.clearAll();

For a complete list of the available App Preferences API methods and properties, see the App Preferences API Reference Documentation.