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 TypeAndroidiOS
Non-Persistent StorageSharedPreferencesUserDefaults
Persistent StorageSharedPreferences +
Android Backup Service
Apple Keychain Services
Local FileAndroid 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.

Set Command

️GoNative JavaScript Bridge

To save a value up to 1000* characters in length use the following JavaScript Bridge command:

window.location.href = 'gonative://localpreferences/nonpersistent/set?key=KEY&value=VALUE&statuscallback=statcb';

Note: The length of the string is limited by the URL limit on the user's device, hence this approach is recommended only for saving short strings.

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

To save longer strings provide a callback function and have this function return the string to be stored. This method avoids the URL length limit constraint.

️GoNative JavaScript Bridge

To save a larger value stored in a json file:

function getData() {
    return sendDataVariable;
}
var sendDataVariable;
$.ajax({url: "demo.json"}).done(function(result) {
   sendDataVariable = result;
   window.location.href = 'gonative://localpreferences/nonpersistent/set?key=KEY&callback=getData&statuscallback=statcb';
});

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:

window.location.href = 'gonative://localpreferences/nonpersistent/get?key=KEY&callback=cbRead';

Delete Commands

️GoNative JavaScript Bridge

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

window.location.href = 'gonative://localpreferences/nonpersistent/delete?key=KEY&statuscallback=statcb';

To delete all saved settings from the device:

window.location.href = 'gonative://localpreferences/nonpersistent/deleteAll?statuscallback=statcb';

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.

Set Command

️GoNative JavaScript Bridge

To save a value, which may contain up to 1000* characters as strings, open the url:

window.location.href = 'gonative://localpreferences/persistent/set?key=KEY&value=VALUE&statuscallback=statcb';

Note: The length of the string is limited by the URL limit on the user's device, hence this approach is recommended only for saving short strings.

(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 from a large text file, provide another callback function and have the callback function return the longer string. For example:

️GoNative JavaScript Bridge

To save a larger value stored in a json file:

function getData() {
    return sendDataVariable;
}
var sendDataVariable;
$.ajax({url: "demo.json"}).done(function(result) {
   sendDataVariable = result;
   window.location.href = 'gonative://localpreferences/persistent/set?key=KEY&callback=getData&statuscallback=statcb';
});

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:

window.location.href = 'gonative://localpreferences/persistent/get?key=KEY&callback=cb';

Delete Command

️GoNative JavaScript Bridge

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

window.location.href = 'gonative://localpreferences/persistent/delete?key=KEY&statuscallback=statcb';

To delete all saved settings from the device:

window.location.href = 'gonative://localpreferences/persistent/deleteAll?statuscallback=statcb';

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

function getData() { 
    return sendDataVariable;
}

️GoNative JavaScript Bridge

To save a value stored in a variable:

var sendDataVariable = "strings"
window.location.href = 'gonative://localpreferences/filesystem/save?filename=FILENAME&callback=getData&statuscallback=statcb';

To save a larger value stored in a json file:

var sendDataVariable;
$.ajax({url: "demo.json"}).done(function(result) {
   sendDataVariable = result;
   window.location.href = 'gonative://localpreferences/filesystem/save?filename=FILENAME&callback=getData&statuscallback=statcb';
});

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:

window.location.href = 'gonative://localpreferences/filesystem/read?filename=FILENAME&callback=cb';

Delete Command

️GoNative JavaScript Bridge

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

window.location.href = 'gonative://localpreferences/filesystem/delete?filename=FILENAME&statuscallback=statcb';

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

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

Callback statuses

result.statusDescription
successThe operation was successful.
read-errorError Reading local settings.
write-errorError Writing local settings.
delete-errorError Deleting local settings.
callback-errorError receiving data from the callback function.
file-not-foundThe requested file does not exist.
permission-deniedUser denied file Read/Write permission.
preference-not-foundThe requested preference does not exist.