Overview

The Native Datastore Plugin enables developers to persist key-value data such as user preferences and app settings directly on the user's device or in the cloud via the Median JavaScript Bridge.

This plugin supports both App Storage and Cloud Storage, giving you flexibility in how data is saved and accessed across sessions and devices.

Key Features

• App Storage is available offline and persists on the device until the app is updated, reinstalled, or the device is upgraded. Ideal for session-specific or device-bound preferences.
• Cloud Storage syncs data with the user's cloud account, making it accessible across multiple devices and app re-installations. Use Cloud Storage for settings that need to follow the user across devices.

👍

Developer Demo

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

Supported Storage Types and Platforms

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 Status Reference

Demo App

Try out the plugin on iOS and Android with our interactive demo apps.