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:

  • App Storage settings are cleared when the app is updated or uninstalled/re-installed, or the device is upgraded.
  • Cloud Storage settings are designed to continue to be available through app updates and re-installation, and through device upgrades when possible through the device.

Device Implementation Methods

Storage Type

Android

iOS

App Storage

SharedPreferences

UserDefaults

Cloud Storage

SharedPreferences +
Android Backup Service

Apple Keychain Services

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.

App 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 App Storage (SharedPreferences) database file is DATA/data/APP_PACKAGE_NAME/shared_prefs/user_preferences.xml

Set Command

To save a value, use the following JavaScript Bridge command. To get status of this write operation, define a callback function in JavaScript and pass as statuscallback (Optional).

↔️GoNative JavaScript Bridge

gonative.storage.app.set({
  key: KEY, 
  value: VALUE, 
  statuscallback: statcb
});

// Optional callback for status
function statcb(result) {
    if (result.status) {
       console.log(result.status);
   }
}

Get Command

To retrieve the saved settings define a callback function and call the JavaScript Bridge command below, providing the KEY of the saved setting and the callback that was defined. The status of the read operation is included as a parameter in the result variable as shown below.

↔️GoNative JavaScript Bridge

gonative.storage.app.get({
  key: KEY, 
  callback: cbRead 
});

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

// Promise method
gonative.storage.app.get({
  key: KEY
}).then(function (result) {
  if (result.data) {
       console.log(result.data);
   }
   if (result.status) {
       console.log(result.status);
   }
});

Learn more about using promises and the GoNative JavaScript Bridge.

Delete Commands

To delete a setting provide the KEY of the previously saved setting. The status of the delete operation can be accessed through the function passed as statuscallback (Optional).

↔️GoNative JavaScript Bridge

gonative.storage.app.delete({ 
  key: KEY, 
  statuscallback: statcb 
});

// Optional callback for status
function statcb(result) {
   if (result.status) {
       console.log(result.status);
   }
}

To delete all saved settings from the device:

↔️GoNative JavaScript Bridge

gonative.storage.app.deleteAll({statuscallback: statcb});
function statcb(result) {
   if (result.status) {
       console.log(result.status);
   }
}

Cloud 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 Cloud Storage (SharedPreferences) database file is DATA/data/APP_PACKAGE_NAME/shared_prefs/user_preferences_backup.xml

Set Command

To save a value, use the following JavaScript Bridge command. To get status of this write operation, define a callback function in JavaScript (Optional).

↔️GoNative JavaScript Bridge

gonative.storage.cloud.set({
  key: KEY, 
  value: VALUE, 
  statuscallback: statcb
});

// Optional callback for status
function statcb(result) {
   if (result.status) {
       console.log(result.status);
   }
}

Get Command

To retrieve the saved settings define a callback function and call the JavaScript Bridge command below, providing the KEY of the saved setting and the callback that was defined. The status of the read operation is included as a parameter in the result variable as shown below.

↔️GoNative JavaScript Bridge

gonative.storage.cloud.get({
  key: KEY, 
  callback: cbRead 
});

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

// Promise method
gonative.storage.cloud.get({
  key: KEY
}).then(function (result) {
  if (result.data) {
       console.log(result.data);
   }
   if (result.status) {
       console.log(result.status);
   }
});

Learn more about using promises and the GoNative JavaScript Bridge.

Delete Command

To delete a setting provide the KEY of the previously saved setting. The status of the delete operation can be accessed through the function passed as statuscallback (Optional).

↔️GoNative JavaScript Bridge

gonative.storage.cloud.delete({ 
  key: KEY, 
  statuscallback: statcb 
});

// Optional callback for status
function statcb(result) {
   if (result.status) {
       console.log(result.status);
   }
}

To delete all saved settings from the device:

↔️GoNative JavaScript Bridge

gonative.storage.cloud.deleteAll({statuscallback: statcb});

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.

preference-not-found

The requested preference does not exist.