Native Datastore
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 Type | Android | iOS |
---|---|---|
App Storage | SharedPreferences | UserDefaults |
Cloud Storage | SharedPreferences + Android Backup Service | Apple Keychain Services |
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
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
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
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
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
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
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
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
median.storage.cloud.deleteAll({statuscallback: statcb}); function statcb(result) { if (result.status) { console.log(result.status); } }
Callback Status Reference
result.status | Description |
---|---|
success | The operation was successful. |
read-error | Error Reading native datastore. |
write-error | Error Writing native datastore. |
delete-error | Error Deleting native datastore. |
preference-not-found | The requested preference does not exist. |
Demo App
Try out the plugin on iOS and Android with our interactive demo apps.
iOS | Android |
Updated 26 days ago