Overview

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

You may save settings using two 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.

👍

Developer Demo

Display our demo page in your app to test during development https://median.dev/native-datastore/

Device Implementation Methods

Storage Limits

Android

SharedPreferences does not have a storage limit.

Android Backup supports up to 5MB per app.
Learn more about the Android Backup Service here.

iOS

UserDefaults supports up to 500KB of data.

Apple Keychain Services supports up to 16MB of data.

Implementation Guide

Once the Native Datastore Native Plugin has been added to your app, you may use the following Median 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).

↔️Median JavaScript Bridge

JavaScript

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

↔️Median JavaScript Bridge

JavaScript

median.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
median.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 Median 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).

↔️Median JavaScript Bridge

JavaScript

median.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:

↔️Median JavaScript Bridge

JavaScript

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

🚧

Android Cloud Storage

Android Cloud Storage uses its BackupManager service to save the data on cloud. Hence, your data may not be immediately saved to the cloud as mentioned in this Google Documentation.

So once there are changes in the data, your app will trigger a backup request, and then the Android system will schedule a backup operation to occur in the near future. The event can take place at any point during the day, and a precise time cannot be guaranteed.

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

↔️Median JavaScript Bridge

JavaScript

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

↔️Median JavaScript Bridge

JavaScript

median.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
median.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 Media 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).

↔️Median JavaScript Bridge

JavaScript

median.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:

↔️Median JavaScript Bridge

JavaScript

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

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

Callback statuses