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.

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

App preferences can be stored locally or remotely by using a REST service or io.Manager.

To provide settings for app preferences stores, use the store property of the applicationPreferences top-level key in the configuration object for initializing the @interopio/browser-platform library.

The store object has the following properties:

Local

By default, app preferences are stored locally using the IndexedDB API of the browser.

To instruct io.Connect Browser to manage app preferences using a local app preferences store, set the type property of the store object to "local".

The following example demonstrates how to configure the platform to use the browser IndexedDB API to store app preferences locally:

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

const config = {
    licenseKey: "my-license-key",
    applicationPreferences: {
        store: {
            type: "local"
        }
    }
};

const { io } = await IOBrowserPlatform(config);

Rest

App preferences can also be obtained from remote Layout stores via a REST service.

ℹ️ For a reference implementation of a remote app preferences store, see the Node.js REST Config example.

To instruct io.Connect Browser to manage app preferences using a remote REST service, set the type property of the store object to "rest" and provide settings for the REST store by using the rest object.

The rest object has the following properties:

The following example demonstrates how to configure the platform to use a remote REST service as an app preferences store:

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

const config = {
    licenseKey: "my-license-key",
    applicationPreferences: {
        store: {
            type: "rest",
            // Settings for the REST store.
            rest: {
                url: "https://my-remote-store/app-preferences"
            }
        }
    }
};

const { io } = await IOBrowserPlatform(config);

The remote store must return an AppPreferences object as a response.

io.Manager

You can also use io.Manager for hosting and retrieving app preferences.

The following example demonstrates how to configure the platform to use io.Manager as an app preferences store:

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

const config = {
    licenseKey: "my-license-key",
    applicationPreferences: {
        store: {
            type: "manager"
        }
    }
};

const { io } = await IOBrowserPlatform(config);

ℹ️ For more details on how to configure io.Connect Browser to connect to io.Manager, see the io.Manager section.

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.