📖 View this page in our documentation

Overview

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

You may save Local Settings using three different options. Non-Persistent settings may be cleared when the app is updated or un-installed/re-installed, or the device is upgraded. Persistent settings are designed to continue to be available. Local File is a special Android-only option where a file is saved locally on the device, the availability of this file after various operations is dependent on the Android API version and device settings.

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 its functionality.

Non-Persistent Storage

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

Set

View GoNative JavaScript Bridge example code in our documentation

(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);
    }
}

To save longer strings provide another callback function and have the callback function return the string to be stored. This avoids the URL length limit constraint.
For example:

function getData() {
    return sendDataVariable;
}

View GoNative JavaScript Bridge example code in our documentation

Get

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 already in the result variable as shown above.

View GoNative JavaScript Bridge example code in our documentation

Delete

View GoNative JavaScript Bridge example code in our documentation

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 need to provide key-value data to save the app settings. You may use the key later to identify the settings you would like to retrieve or delete.

Set

View GoNative JavaScript Bridge example code in our documentation

(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);
    }
}

If you want to save longer strings from a large text file, you will need to provide another callback function and have the callback function return the longer string. For example:

function getData() {
    return sendDataVariable;
}

View GoNative JavaScript Bridge example code in our documentation

Get

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 already in the result variable as shown above.

View GoNative JavaScript Bridge example code in our documentation

Delete

View GoNative JavaScript Bridge example code in our documentation

Android File System

This option uses Android's native File System to Write/Read/Delete files in the directory: INTERNAL_STORAGE/Documents/APP_PACKAGE_NAME/

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

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

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

function getData() { 
    return sendDataVariable;
}

View GoNative JavaScript Bridge example code in our documentation

Read

To retrieve the saved settings, you may 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.

View GoNative JavaScript Bridge example code in our documentation

Delete

View GoNative JavaScript Bridge example code in our documentation

Callback statuses

result.status =
Description

"success"

The operation is successful.

"read-error"

Error Reading local settings.

"write-error"

Error Writing local settings.

"delete-error"

Error Deleting local settings.

"callback-error"

Error receiving data from the callback function.

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