Most apps will need some sort of backup for the various customizations that the app permits, especially if the app does not have a dedicated server to store those settings. The Android Backup Service provides a simple means of preserving data.
Adding backup support for shared preferences and files is very easy and very simple. Let's take a look at the following steps:
- Before we start, we have to register our app with the Android Backup Service: http://developer.android.com/google/backup/signup.html
On the form, enter the application package name and click on Register.
- Make a note of the key that is provided and create a
[MetaData]attribute in our app with the value being the key:[assembly: MetaData( "com.google.android.backup.api_key", Value = "AndroidBackupServiceKey")]
- To create our backup agent, we need to inherit from
BackupAgentHelper:public class BackupHelper : BackupAgentHelper { public override void OnCreate() { } } - Then, we need to register our agent with the Android application:
[assembly: Application( BackupAgent = typeof(XamarinCookbook.BackupHelper))]
- The last thing that our agent needs is to know what to backup. In the
OnCreate()method, we add helpers:AddHelper( "PrefsHelper", new SharedPreferencesBackupHelper(this, "GamePrefs")); AddHelper( "FileHelpers", new FileBackupHelper(this, "scores.xml"));
- All we have to do now is tell Android that a backup is needed whenever the preferences or files change:
using (BackupManager bm = new BackupManager(this)) { bm.DataChanged(); }
Most apps and games have some sort of data that should be preserved across devices or app installs. It can be scores, progress, or app configurations. There are two types of backup agents that we can create: a helper-based agent and a more comprehensive agent. This recipe looks at the former and the next recipe looks at the latter.
There are two simple data types that can be backed up using helpers, almost without any code: shared preferences and files. This backup API is only designed for small pieces of data, less than one megabyte, and should not be used to store large data.
Each app requires a special Android Backup Service Key, which can be obtained from the http://developer.android.com/google/backup/signup.html service. This key is then added to the Android manifest by adding an assembly [MetaData] attribute.
We also have to register the backup agent with the app by passing the type of the agent to the BackupAgent property of the [Application] attribute.
Creating an agent is as simple as inheriting from the BackupAgentHelper type and implementing the OnCreate() method. In this method, we can add all the helpers that we require.
Each helper is constructed with a list of files or a list of shared preferences that we need to backup. After construction, we add each helper to the agent along with a unique key.
Once we have created and registered our backup agent, we need to let Android know every time the data changes, so it can back it up. To do this, we instantiate a BackupManager and call DataChanged. This does not run the backup immediately, but instead queues it up for the most opportune time determined by the Android OS.
It is also very simple to test the backup process while developing our app. We can request a backup to happen immediately by executing the following commands:
adb shell bmgr backup <android-package-name> adb shell bmgr run
Once we have run the backup, we can either clear all data associated with the app or uninstall and reinstall the app. Both actions can be done from the Settings app on the device. Once we have done either of these, we can start the restore task:
adb shell bmgr restore <android-package-name>
We can then launch the app and check whether the app has the data that was backed up. We can also override the OnBackup() and OnRestore() methods of the agent and insert breakpoints. When we run the command lines, they will be hit accordingly.
Sometimes, Android does not think it should run the backup or restore process. This can be for any number of reasons, but we can force the backup to occur by disabling and then re-enabling it:
adb shell bmgr enable false adb shell bmgr enable true
Once the agent has started, we can then request a backup as normal. The reason this works is that when the backup agent is disabled, it wipes all the data from the service. As there is no data anymore, it will always perform the backup.