search

dpa99c / cordova-plugin-cloud-settings

A Cordova plugin for Android & iOS to persist user settings in cloud storage across devices and installs.
27 stars 17 forks source link

readme

Cordova Cloud Settings plugin Latest Stable Version

A Cordova plugin for Android & iOS to persist user settings in cloud storage across devices and installs.

Table of Contents

Summary

This plugin provides a mechanism to store key/value app settings in the form of a JSON structure which will persist in cloud storage so if the user re-installs the app or installs it on a different device, the settings will be restored and available in the new installation.

Key features:

Note:

Android

The plugin uses Android's Data Backup service to store settings in a file.

iOS

The plugin uses iCloud to store the settings, specifically the NSUbiquitousKeyValueStore class to store settings in a native K/V store

Note:

Installation

The plugin is published to npm as cordova-plugin-cloud-settings.

Install the plugin

cordova plugin add cordova-plugin-cloud-settings

Usage lifecycle

A typical lifecycle is as follows:

API

The plugin's JS API is under the global namespace cordova.plugin.cloudsettings.

exists()

cordova.plugin.cloudsettings.exists(successCallback);

Indicates if any stored cloud settings currently exist for the current user.

Parameters

cordova.plugin.cloudsettings.exists(function(exists){
    if(exists){
        console.log("Saved settings exist for the current user");
    }else{
        console.log("Saved settings do not exist for the current user");
    }
});

save()

cordova.plugin.cloudsettings.save(settings, [successCallback], [errorCallback], [overwrite]);

Saves the settings to cloud backup.

Notes:

Parameters

var settings = {
  user: {
    id: 1678,
    name: 'Fred',
    preferences: {
      mute: true,
      locale: 'en_GB'
    }
  }
}

cordova.plugin.cloudsettings.save(settings, function(savedSettings){
    console.log("Settings successfully saved at " + (new Date(savedSettings.timestamp)).toISOString());
}, function(error){
    console.error("Failed to save settings: " + error);
}, false);

load()

cordova.plugin.cloudsettings.load(successCallback, [errorCallback]);

Loads the current settings.

Note: the settings are loaded locally off disk rather than directly from cloud backup so are not guaranteed to be the latest settings in cloud backup. If you require conflict resolution of local vs cloud settings, you should save a timestamp when loading/saving your settings and use this to resolve any conflicts.

Parameters

cordova.plugin.cloudsettings.load(function(settings){
    console.log("Successfully loaded settings: " + console.log(JSON.stringify(settings)));
}, function(error){
    console.error("Failed to load settings: " + error);
});

onRestore()

cordova.plugin.cloudsettings.onRestore(successCallback);

Registers a function which will be called if/when settings on the device have been updated from the cloud.

The purpose of this is to notify your app if current settings have changed due to being updated from the cloud while your app is running. This may occur, for example, if the user has two devices with your app installed; changing settings on one device will cause them to be synched to the other device.

When you call save(), a timestamp key is added to the stored settings object which indicates when the settings were saved. If necessary, this can be used for conflict resolution.

Parameters

cordova.plugin.cloudsettings.onRestore(function(){
    console.log("Settings have been updated from the cloud");
});

enableDebug()

cordova.plugin.cloudsettings.enableDebug(successCallback);

Outputs verbose log messages from the native plugin components to the JS console.

Parameters

cordova.plugin.cloudsettings.enableDebug(function(){
    console.log("Debug mode enabled");
});

Testing

Testing Android

Test backup & restore (automatic)

To automatically test backup and restore of your app, run scripts/android/test_cloud_backup.sh in this repo with the package name of your app. This will initialise and create a backup, then uninstall/reinstall the app to trigger a restore.

    $ scripts/android/test_cloud_backup.sh <APP_PACKAGE_ID>

Test backup (manual)

To test backup of settings you need to manually invoke the backup manager (as instructed in the Android documentation) to force backing up of the updated values:

First make sure the backup manager is enabled and setup for verbose logging:

    $ adb shell bmgr enabled
    $ adb shell setprop log.tag.GmsBackupTransport VERBOSE
    $ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE

The method of testing the backup then depends on the version of Android running of the target device:

Android 7 and above

Run the following command to perform a backup:

    $ adb shell bmgr backupnow <APP_PACKAGE_ID>

Android 6

Test restore (manual)

To manually initiate a restore, run the following command:

    $ adb shell bmgr restore <TOKEN> <APP_PACKAGE_ID>

You also can test automatic restore for your app by uninstalling and reinstalling your app either with adb or through the Google Play Store app.

Wipe backup data

To wipe the backup data for your app:

    $ adb shell bmgr list transports
    # note the one with an * next to it, it is the transport protocol for your backup
    $ adb shell bmgr wipe [* transport-protocol] <APP_PACKAGE_ID>

Testing iOS

Test backup

iCloud backups happen periodically, hence saving data via the plugin will write it to disk, but it may not be synced to iCloud immediately.

To force an iCloud backup immediately (on iOS 11):

Test restore

To test restoring, uninstall then re-install the app to sync the data back from iCloud.

You can also install the app on 2 iOS devices. Saving data on one should trigger an call to the onRestore() callback on the other.

Example project

An example project illustrating/validating use of this plugin can be found here: https://github.com/dpa99c/cordova-plugin-cloud-settings-test

Use in GDPR-compliant analytics

GDPR background

Impact on user tracking in analytics

Benefits of using this plugin

Authors

Major code contributors:

Based on the plugins:

Licence

The MIT License

Copyright (c) 2018-21, Dave Alden (Working Edge Ltd.)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.