Native Datastore

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.

Why Use Native Datastore

• User preference persistence: Save settings like theme, language, and notification preferences that survive app restarts and webview cache clears without relying on cookies.
• Authentication state: Store session tokens and login flags locally so users stay authenticated between app launches, with cloud storage restoring state after a reinstall.
• Cross-device settings sync: Use cloud storage to carry user preferences across devices without building a sync backend. When a user reinstalls or switches devices, their settings are restored automatically.
• Offline-first apps: Cache lightweight values like a user's account ID or last-known app state so the app can render meaningful content without a network connection.
• Secure credential storage: On iOS, cloud storage uses Apple Keychain Services, providing hardware-backed encryption suitable for persisting sensitive values like API keys and tokens across reinstalls.

Storage Backends

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.

Storage Limits

Android cloud storage uses BackupManager, which schedules sync operations asynchronously. A precise sync time cannot be guaranteed as the system triggers a backup at some point after your app requests one. See Google's BackupManager documentation for details.

Implementation Guide

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

// Callback 
median.storage.app.get({
  key: KEY,
  callback: cbRead
});

function cbRead(result) {
  console.log(result.data);    // the stored value
  console.log(result.status);  // operation status
}

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

Delete

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

Delete All

Removes all stored key-value pairs from device-local storage.

↔️Median JavaScript Bridge

JavaScript

median.storage.app.deleteAll({
  statuscallback: statcb  // optional
});

function statcb(result) {
  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).

↔️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);
  }
}

Delete All

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

All write and delete operations return status via statuscallback; get returns status via callback. Check result.status in your callback to confirm success or handle errors.

Demo App

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

Frequently Asked Questions