Syncing to the Cloud

GET STARTED

DEPENDENCIES AND PREREQUISITES

• Android 2.2 (API level 8) and higher

By providing powerful APIs for internet connectivity, the Android framework helps you build rich cloud-enabled apps that sync their data to a remote web service, making sure all your devices always stay in sync, and your valuable data is always backed up to the cloud.

This class covers different strategies for cloud enabled applications. It covers syncing data with the cloud using your own back-end web application, and backing up data using the cloud so that users can restore their data when installing your application on a new device.

Lessons

Using the Backup API

Learn how to integrate the Backup API into your Android Application, so that user data such as preferences, notes, and high scores update seamlessly across all of a user‘s devices

Making the Most of Google Cloud Messaging

Learn how to efficiently send multicast messages, react intelligently to incoming Google Cloud Messaging (GCM) messages, and use GCM messages to efficiently sync with the server.

Using the Backup API

PREVIOUSNEXT

THIS LESSON TEACHES YOU TO

1. Register for the Android Backup Service
2. Configure Your Manifest
3. Write Your Backup Agent
4. Request a Backup
5. Restore from a Backup

YOU SHOULD ALSO READ

• Data Backup

When a user purchases a new device or resets their existing one, they might expect that when Google Play restores your app back to their device during the initial setup, the previous data associated with the app restores as well. By default, that doesn‘t happen and all the user‘s accomplishments or settings in your app are lost.

For situations where the volume of data is relatively light (less than a megabyte), like the user‘s preferences, notes, game high scores or other stats, the Backup API provides a lightweight solution. This lesson walks you through integrating the Backup API into your application, and restoring data to new devices using the Backup API.

Register for the Android Backup Service

<meta-data android:name="com.google.android.backup.api_key"android:value="ABcDe1FGHij2KlmN3oPQRs4TUvW5xYZ" />

Note that each backup key works with a specific package name. If you have different applications, register separate keys for each one.

Configure Your Manifest

<application android:label="MyApp"             android:backupAgent="TheBackupAgent">    ...    <meta-data android:name="com.google.android.backup.api_key"    android:value="ABcDe1FGHij2KlmN3oPQRs4TUvW5xYZ" />    ...</application>

Write Your Backup Agent

Inside the onCreate() method, create a BackupHelper. These helpers are specialized classes for backing up certain kinds of data. The Android framework currently includes two such helpers: FileBackupHelper andSharedPreferencesBackupHelper. After you create the helper and point it at the data you want to back up, just add it to the BackupAgentHelper using the addHelper() method, adding a key which is used to retrieve the data later. In most cases the entire implementation is perhaps 10 lines of code.

Here‘s an example that backs up a high scores file.

 import android.app.backup.BackupAgentHelper; import android.app.backup.FileBackupHelper;

 public class TheBackupAgent extends BackupAgentHelper {    // The name of the SharedPreferences file    static final String HIGH_SCORES_FILENAME = "scores";

    // A key to uniquely identify the set of backup data    static final String FILES_BACKUP_KEY = "myfiles";

    // Allocate a helper and add it to the backup agent    @Override    void onCreate() {        FileBackupHelper helper = new FileBackupHelper(this, HIGH_SCORES_FILENAME);        addHelper(FILES_BACKUP_KEY, helper);    }}

For added flexibility, FileBackupHelper‘s constructor can take a variable number of filenames. You could just as easily have backed up both a high scores file and a game progress file just by adding an extra parameter, like this:

    @Override    void onCreate() {        FileBackupHelper helper = new FileBackupHelper(this, HIGH_SCORES_FILENAME, PROGRESS_FILENAME);        addHelper(FILES_BACKUP_KEY, helper);    }

Backing up preferences is similarly easy. Create a SharedPreferencesBackupHelper the same way you did aFileBackupHelper. In this case, instead of adding filenames to the constructor, add the names of the shared preference groups being used by your application. Here‘s an example of how your backup agent helper might look if high scores are implemented as preferences instead of a flat file:

 import android.app.backup.BackupAgentHelper; import android.app.backup.SharedPreferencesBackupHelper;

 public class TheBackupAgent extends BackupAgentHelper {     // The names of the SharedPreferences groups that the application maintains.  These     // are the same strings that are passed to getSharedPreferences(String, int).     static final String PREFS_DISPLAY = "displayprefs";     static final String PREFS_SCORES = "highscores";

     // An arbitrary string used within the BackupAgentHelper implementation to     // identify the SharedPreferencesBackupHelper‘s data.     static final String MY_PREFS_BACKUP_KEY = "myprefs";

     // Simply allocate a helper and install it     void onCreate() {         SharedPreferencesBackupHelper helper =                 new SharedPreferencesBackupHelper(this, PREFS_DISPLAY, PREFS_SCORES);         addHelper(MY_PREFS_BACKUP_KEY, helper);     } }

You can add as many backup helper instances to your backup agent helper as you like, but remember that you only need one of each type. One FileBackupHelper handles all the files that you need to back up, and oneSharedPreferencesBackupHelper handles all the shared preferencegroups you need backed up.

Request a Backup

 import android.app.backup.BackupManager; ...

 public void requestBackup() {   BackupManager bm = new BackupManager(this);   bm.dataChanged(); }

This call notifies the backup manager that there is data ready to be backed up to the cloud. At some point in the future, the backup manager then calls your backup agent‘s onBackup() method. You can make the call whenever your data has changed, without having to worry about causing excessive network activity. If you request a backup twice before a backup occurs, the backup only occurs once.

Restore from a Backup

Making the Most of Google Cloud Messaging

PREVIOUSNEXT

THIS LESSON TEACHES YOU TO

1. Send Multicast Messages Efficiently
2. Collapse Messages that can Be Replaced
3. Embed Data Directly in the GCM Message
4. React Intelligently to GCM Messages

YOU SHOULD ALSO READ

• Google Cloud Messaging for Android

Google Cloud Messaging (GCM) is a free service for sending messages to Android devices. GCM messaging can greatly enhance the user experience. Your application can stay up to date without wasting battery power on waking up the radio and polling the server when there are no updates. Also, GCM allows you to attach up to 1,000 recipients to a single message, letting you easily contact large user bases quickly when appropriate, while minimizing the work load on your server.

This lesson covers some of the best practices for integrating GCM into your application, and assumes you are already familiar with basic implementation of this service. If this is not the case, you can read the GCM demo app tutorial.

Send Multicast Messages Efficiently

Taking advantage of this functionality is easy. If you‘re using the GCM helper library for Java, simply provide aList collection of registration IDs to the send or sendNoRetry method, instead of a single registration ID.

// This method name is completely fabricated, but you get the idea.List regIds = whoShouldISendThisTo(message);

// If you want the SDK to automatically retry a certain number of times, use the// standard send method.MulticastResult result = sender.send(message, regIds, 5);

// Otherwise, use sendNoRetry.MulticastResult result = sender.sendNoRetry(message, regIds);

For those implementing GCM support in a language other than Java, construct an HTTP POST request with the following headers:

• Authorization: key=YOUR_API_KEY
• Content-type: application/json

Then encode the parameters you want into a JSON object, listing all the registration IDs under the keyregistration_ids. The snippet below serves as an example. All parameters except registration_ids are optional, and the items nested in data represent the user-defined payload, not GCM-defined parameters. The endpoint for this HTTP POST message will be https://android.googleapis.com/gcm/send.

{ "collapse_key": "score_update",   "time_to_live": 108,   "delay_while_idle": true,   "data": {       "score": "4 x 8",       "time": "15:16.2342"   },   "registration_ids":["4", "8", "15", "16", "23", "42"]}

For a more thorough overview of the format of multicast GCM messages, see the Sending Messages section of the GCM guide.

Collapse Messages that Can Be Replaced

When you define a collapse key, when multiple messages are queued up in the GCM servers for the same user, only the last one with any given collapse key is delivered. For a situation like with sports scores, this saves the device from doing needless work and potentially over-notifying the user. For situations that involve a server sync (like checking email), this can cut down on the number of syncs the device has to do. For instance, if there are 10 emails waiting on the server, and ten "new email" GCM tickles have been sent to the device, it only needs one, since it should only sync once.

In order to use this feature, just add a collapse key to your outgoing message. If you‘re using the GCM helper library, use the Message class‘s collapseKey(String key) method.

Message message = new Message.Builder(regId)    .collapseKey("game4_scores") // The key for game 4.    .ttl(600) // Time in seconds to keep message queued if device offline.    .delayWhileIdle(true) // Wait for device to become active before sending.    .addPayload("key1", "value1")    .addPayload("key2", "value2")    .build();

If not using the helper library, simply add a variable to the POST header you‘re constructing, with collapse_key as the field name, and the string you‘re using for that set of updates as the value.

Embed Data Directly in the GCM Message

• The total data fits inside the 4kb limit.
• Each message is important, and should be preserved.
• It doesn‘t make sense to collapse multiple GCM messages into a single "new data on the server" tickle.

For instance, short messages or encoded player moves in a turn-based network game are examples of good use-cases for data to embed directly into a GCM message. Email is an example of a bad use-case, since messages are often larger than 4kb, and users don‘t need a GCM message for each email waiting for them on the server.

Also consider this approach when sending multicast messages, so you don‘t tell every device across your user base to hit your server for updates simultaneously.

This strategy isn‘t appropriate for sending large amounts of data, for a few reasons:

• Rate limits are in place to prevent malicious or poorly coded apps from spamming an individual device with messages.
• Messages aren‘t guaranteed to arrive in-order.
• Messages aren‘t guaranteed to arrive as fast as you send them out. Even if the device receives one GCM message a second, at a max of 1K, that‘s 8kbps, or about the speed of home dial-up internet in the early 1990‘s. Your app rating on Google Play will reflect having done that to your users.

When used appropriately, directly embedding data in the GCM message can speed up the perceived speediness of your application, by letting it skip a round trip to the server.

React Intelligently to GCM Messages

Don‘t be irritating

When it comes to alerting your user of fresh data, it‘s easy to cross the line from "useful" to "annoying". If your application uses status bar notifications, update your existing notification instead of creating a second one. If you beep or vibrate to alert the user, consider setting up a timer. Don‘t let the application alert more than once a minute, lest users be tempted to uninstall your application, turn the device off, or toss it in a nearby river.

Sync smarter, not harder

When using GCM as an indicator to the device that data needs to be downloaded from the server, remember you have 4kb of metadata you can send along to help your application be smart about it. For instance, if you have a feed reading app, and your user has 100 feeds that they follow, help the device be smart about what it downloads from the server! Look at the following examples of what metadata is sent to your application in the GCM payload, and how the application can react:

• refresh — Your app basically got told to request a dump of every feed it follows. Your app would either need to send feed requests to 100 different servers, or if you have an aggregator on your server, send a request to retrieve, bundle and transmit recent data from 100 different feeds, every time one updates.
• refresh, feedID — Better: Your app knows to check a specific feed for updates.
• refresh, feedID, timestamp — Best: If the user happened to manually refresh before the GCM message arrived, the application can compare timestamps of the most recent post, and determine that it doesn‘t need to do anything.