Native Datastore
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 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 statuses
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. |
Updated 3 months ago