Local Settings

Overview

The Local Settings Native Plugin allows you to save settings and other string data directly to the user's device, via the GoNative JavaScript Bridge.

You may save Local Settings using three different storage type options:

  • Non-Persistent settings are cleared when the app is updated or uninstalled/re-installed, or the device is upgraded.
  • Persistent settings are designed to continue to be available through app updates and re-installation, and through device upgrades when possible through the device.
  • Local File is an Android-only option in which a file is saved locally on the device file system. The availability of this file after app uninstallation is dependent on the Android API version and device settings.

Device Implementation Methods

Storage Type

Android

iOS

Non-Persistent Storage

SharedPreferences

UserDefaults

Persistent Storage

SharedPreferences +
Android Backup Service

Apple Keychain Services

Local File

Android File System

Implementation Guide

Once the Local Settings Native Plugin has been added to your app, you may use the following GoNative JavaScript Bridge commands to access functionality.

Non-Persistent Storage

This option utilizes Android's SharedPreferences and iOS's UserDefaults to store the local app settings on the user's device. You will provide a key-value pair to save the app settings. You will then use the key to retrieve or delete the corresponding value.

Note: On Android the location of the Non-Persistent Storage SharedPreferences database file is DATA/data/APP_PACKAGE_NAME/shared_prefs/user_preferences.xml

Set Command

️GoNative JavaScript Bridge

To save a value, use the following JavaScript Bridge command:

<button onclick="gonative.localpreferences.nonpersistent
.set({key: KEY, value: VALUE, statuscallback: statcb});">Save non persistent settings</button>

(Optional) To get status of this write operation, define a callback function in JavaScript and pass as statuscallback, for example:

function statcb(result) {
    if (result.status) {
        console.log(result.status);
    }
}

Get Command

To retrieve the saved settings define a callback function as follows:

function cbRead(result) {
    if (result.data) {
        console.log(result.data);
    }
    if (result.status) {
        console.log(result.status);
    }
}

Note: The status of the read operation is included as a parameter in the result variable as shown above.

️GoNative JavaScript Bridge

To retrieve the saved settings call the JavaScript Bridge command, providing the KEY of the saved setting and the callback that was defined:

<button onclick="gonative.localpreferences.nonpersistent
.get({ key: KEY, callback: cbRead })"> Get settings </button>

Delete Commands

️GoNative JavaScript Bridge

To delete a setting provide the KEY of the previously saved setting:

<button onclick="gonative.localpreferences.nonpersistent
.delete({ key: KEY, statuscallback: statcb })"> Delete settings with key </button>

To delete all saved settings from the device:

<button onclick="gonative.localpreferences.nonpersistent
.deleteAll({ statuscallback: statcb })"> Delete all settings </button>

The status of the delete operation can be accessed through the function passed as statuscallback:

function statcb(result) {
    if (result.status) {
        console.log(result.status);
    }
}

Persistent Storage

This option utilizes Android SharedPreferences combined with the native Android Backup Service and Apple Keychain Services to store the local app settings on a device. You will provide a key-value pair to save the app settings. You will use the key to retrieve or delete the settings.

Note: On Android the location of the Persistent Storage SharedPreferences database file is DATA/data/APP_PACKAGE_NAME/shared_prefs/user_preferences_backup.xml

Set Command

️GoNative JavaScript Bridge

To save a value, use the following JavaScript Bridge command:

<button onclick="gonative.localpreferences.persistent
.set({key: KEY, value: VALUE, statuscallback: statcb});">Save Persistent Settings</button>

(Optional) To get status of this write operation, define a callback function in javascript, for example:

function statcb(result) {
    if (result.status) {
        console.log(result.status);
    }
}

Get Command

To retrieve the saved settings, you will need to define the following callback function:

function cb(result) {
    if (result.data) {
        console.log(result.data);
    }
    if (result.status) {
        console.log(result.status);
    }
}

Note: The status of the read operation is included in the result variable as shown above.

️GoNative JavaScript Bridge

To retrieve the saved settings, open the url, providing the KEY of the saved settings:

<button onclick="gonative.localpreferences.persistent
.get({ key: KEY, callback: cb })"> Get persistent settings </button>

Delete Command

️GoNative JavaScript Bridge

To delete a setting provide the KEY of the previously saved setting:

<button onclick="gonative.localpreferences.persistent
.delete({ key: KEY, statuscallback: statcb })"> Delete persistent settings with key </button>

To delete all saved settings from the device:

<button onclick="gonative.localpreferences.persistent
.deleteAll({ statuscallback: statcb })"> Delete all persistent settings </button>

The status of the delete operation can be accessed by adding:

function statcb(result) {
    if (result.status) {
        console.log(result.status);
    }
}

Android File System

This option uses Android's native File System to Write/Read/Delete files in the following directories based on device's API version:
API <= 28 (Android Pie) - /INTERNAL_STORAGE/Documents/APP_PACKAGE_NAME/ (Public)
API >= 29 (Android Q) - /data/APP_PACKAGE_NAME/files/ (Private to your app)

Note: For Android, files created using File System are persistent for devices with API <= 28. For API >= 29, the app will lose ownership of its files once it is upgraded/uninstalled/reinstalled.

Save Command

To save settings, define callback functions in javascript, for example:

function statcb(result) {
    if (result.status) {
        console.log(result.status)
    }
}

️GoNative JavaScript Bridge

To save a value:

<button onclick="gonative.localpreferences.filesystem
.save( { filename: FILENAME, data: DATA, statuscallback: statcb} )"> Save data with filename </button>

Read Command

To retrieve the saved settings define the following callback function:

function cb(result) {
    if (result.data) {
        console.log(result.data);
    }
    if (result.status) {
        console.log(result.status);
    }
}

Note: The status of the read operation is included already in the result variable as shown above.

️GoNative JavaScript Bridge

To retrieve the saved settings provide the filename of the saved settings:

<button onclick="gonative.localpreferences.filesystem
.read( { filename: FILENAME, callback: cb } )"> Read data with filename </button>

Delete Command

️GoNative JavaScript Bridge

To delete the saved settings, provide the filename of the saved settings:

<button onclick="gonative.localpreferences.filesystem
.delete( { filename: FILENAME, statuscallback: statcb } )"> Delete file with filename </button>

The status of the delete operation can be accessed by adding:

function statcb(result) {
    if (result.status) {
        console.log(result.status);
    }
}

Callback statuses

result.status

Description

success

The operation was successful.

read-error

Error Reading local settings.

write-error

Error Writing local settings.

delete-error

Error Deleting local settings.

file-not-found

The requested file does not exist.

permission-denied

User denied file Read/Write permission.

preference-not-found

The requested preference does not exist.