Android Development Patterns: Best Practices for Professional Developers (2016)

---

When you retrieve a file from Drive, a resource called DriveContents will be available as a temporary copy of the file you are working with. This resource does require that you verify that it was able to get the file you want to work with. The following snippet shows a request made for a file as well as the process of verifying the contents of the DriveContents resource:

// either create a file object, or use Drive.DriveApi.getFile()
// MODE_READ_ONLY signifies working with an InputStream
file.open(myGoogleApiClient, DriveFile.MODE_READ_ONLY, null)
.setResultCallback(contentsOpenedCallback);

ResultCallback<DriveContentsResult> contentsOpenedCallback =
new ResultCallback<DriveContentsResult>() {
@Override
public void onResult(DriveContentsResult result) {
if (!result.getStatus().isSuccess()) {
// File cannot be opened, display appropriate message
return;
}
// set contents to the binary return
DriveContents contents = result.getDriveContents();
}
};

To read the binary contents that were just opened, you need to create a BufferedReader, a StringBuilder, and a String. When you are finished working with the file, remember to close the file with either DriveContents.commit or DriveContents.discard. The following snippet shows how to convert the binary data into a String as well as how to close the file:

// add this snippet where you are working with the binary read
DriveContents contents = result.getDriveContents();
BufferedReader reader =
new BufferedReader(new InputStreamReader(contents.getInputStream()));
StringBuilder builder = new StringBuilder();
String line;
while ((line = reader.readLine()) != null) {
builder.append(line);
}
// Create a String to house the contents
String contentsAsString = builder.toString();
// Perform logic with the string

// The following will close the file
contents.commit(mGoogleApiClient, null)
.setResultCallback(new ResultCallback<Status>() {
@Override
public void onResult(Status result) {
// handle based on result status
}
});

Writing to files is similar to reading from them in that you need to retrieve and open the file you want to write to, perform the write, and then close the file. Remember that you will need to use a ParcelFileDescriptor when you are appending to a file rather than using anOutputStream. The following snippet demonstrates opening a file to work with, appending a String message to the file and then closing the file:

// create a file object, use Drive.DriveApi.getFile(), or use DriveContents
file.open(mGoogleApiClient, DriveFile.MODE_WRITE_ONLY, null)
.setResultCallback(new ResultCallback<DriveContentsResult>() {
@Override
public void onResult(DriveContentsResult result) {
if (!result.getStatus().isSuccess()) {
// File cannot be opened, display appropriate message
return;
}
DriveContents contents = result.getDriveContents();
}
});

// append a string to the file that was opened
try {
ParcelFileDescriptor parcelFileDescriptor =
contents.getParcelFileDescriptor();
FileInputStream fileInputStream =
new FileInputStream(parcelFileDescriptor.getFileDescriptor());
// read to the end of the file
fileInputStream.read(new byte[fileInputStream.available()]);

// append to the file
FileOutputStream fileOutputStream = new FileOutputStream(parcelFileDescriptor
.getFileDescriptor());
Writer writer = new OutputStreamWriter(fileOutputStream);
writer.write("Howdy World!");
writer.flush();
} catch (IOException e) {
e.printStackTrace();
}

// close the file
contents.commit(mGoogleApiClient, null)
.setResultCallback(new ResultCallback<Status>() {
@Override
public void onResult(Status result) {
// handle based on response status
}
});

Once a file has been closed, it will be flagged to synchronize with the Drive service. The synchronization service is run automatically and will perform connectivity checks to ensure that any files that need to be updated will complete when the network is available and that this operation performs successfully.

Using Google Play Games Services

Google Play Games is a service that allows game developers to create achievements, track login information, grant user permissions, and add a social aspect to gaming that allows you to provide smoother and more addictive gameplay to your users. There is a lot to learn and cover to implement all of the available services, and in this section we are going to focus on what has been the most troublesome aspect of handling user data.

There has long been an issue of figuring out how to provide a quality “save” experience for users who get a new device or have multiple devices. When users only have one device, saving game data is a manageable affair. As a developer, you could save to the local file system or database and you were done.

The problem with this strategy is that many users have more than one device. They may not actually “own” multiple devices, but within the life of your app they may upgrade or change devices. When this happens, a user does not want to spend more of their time doing what they had already done previously to get back to where they were in your game.

Developers have ended up using a variety of strategies to save, restore, and synchronize game data between devices. Any implementation is better than none, but to ease this particular burden, Google has provided a free service that can help you handle this process with Google Play Games Services.

To use Google Play Games Services, you will need to log in to the Google Play Developer Console and add your name to it. This includes a description of your game as well as the name of it. You also need to make sure you have credentials set up for your game. This usually includes creating an OAuth client and linking it to the console.

Google has written up a guide that you can follow, with detailed steps on how this initial setup is done. It is also the best place to go to for reference because it is updated to reflect what the Google Play Developer Console looks like and how it is used. Visit this guide athttps://developers.google.com/games/services/console/enabling.

With your app registered in the console, you can now access all of the features of Google Play Games Services. For examples on all of the features you can use, you should visit the samples code repository that is hosted on GitHub at https://github.com/playgameservices/android-basic-samples.

Working with Saved Games

To add game saving through Google Play Games Services, you need to provide only two things:

A binary blob of game data

Metadata containing Google-provided data as well as data you provide, which includes an ID, name, description, last modified timestamp, time played, and a cover image

Note that you are given 3MB of data for the binary data blob, and 800KB for your cover image. The cover image is used to help the player visually understand what and where they were in your game. The cover image should be something to not only show your game but should be something to help entice the player to continue playing in case they haven’t played the game in a while.

The data and cover image are stored in the Drive account for the user playing the game. This folder is hidden from them and contains the game blob and cover image. Due to the Drive service being used, when you create your Google Services API client, you will need to include Games and Drive as part of the client. The following shows an example of creating the API using the builder method that allows access to Google Plus, Google Games, and Google Drive:

@Override
public void onCreate(Bundle savedInstanceState) {
// create Services API with Play, Games, and Drive access
myGoogleApiClient = new GoogleApiClient.Builder(this)
.addConnectionCallbacks(this)
.addOnConnectionFailedListener(this)
.addApi(Plus.API).addScope(Plus.SCOPE_PLUS_LOGIN)
.addApi(Games.API).addScope(Games.SCOPE_GAMES)
.addApi(Drive.API).addScope(Drive.SCOPE_APPFOLDER)
.build();
}

In code, a game is referred to as a Snapshot. This is the combination of the required blob and metadata for the saved game. To save the Snapshot, you need to obtain a reference to it, use the open() and writeBytes() methods to write current game data, and then use thecommitAndClose() method to save the Snapshot. The following snippet shows you how these methods are used to save a game:

private PendingResult<Snapshots.CommitSnapshotResult>
writeSnapshot(Snapshot snapshot,
byte[] data, Bitmap coverImage, String desc) {

// get the contents of the snapshot and write it
snapshot.getSnapshotContents().writeBytes(data);

// set the metadata change
SnapshotMetadataChange metadataChange = new SnapshotMetadataChange.Builder()
.setCoverImage(coverImage)
.setDescription(desc)
.build();

// commit the snapshot
return Games.Snapshots.commitAndClose(myGoogleApiClient, snapshot, metadataChange);
}

To load a saved game, you should use an asynchronous method to move the process from the main thread. This can be done using AsyncTask with an override to the doInBackground() method. You can then call the load() method:

private byte[] mySaveGameData;

void loadFromSnapshot() {
// Consider using a loading message or widget here

AsyncTask<Void, Void, Integer> task =
new AsyncTask<Void, Void, Integer>() {
@Override
protected Integer doInBackground(Void... params) {
/*
* Open the saved game using myCurrentSaveName
* using "true" as the third argument of open()
* will create a save game if one has not already been created
*/
Snapshots.OpenSnapshotResult result = Games.Snapshots
.open(myGoogleApiClient, myCurrentSaveName, true).await();

// did the open method work?
if (result.getStatus().isSuccess()) {
Snapshot snapshot = result.getSnapshot();
try {
// read the byte content of the saved game.
mySaveGameData = snapshot.getSnapshotContents().readFully();
} catch (IOException e) {
// Logging the IO error
Log.e(TAG, "Error while reading Snapshot.", e);
}
} else {
// Logging the status code error
Log.e(TAG, "Error while loading: " +
result.getStatus().getStatusCode());
}
return result.getStatus().getStatusCode();
}

@Override
protected void onPostExecute(Integer status) {
// Close the loading message or progress dialog if used
// and update the UI
}
};
task.execute();
}

If you do not want to implement your own design for handling game loading, you can use an out-of-the-box solution that is provided by the Google Play Games Services. This is launched by using two methods that call an Intent that displays any saved games the user has, and may allow the user to delete or create a new saved game based on arguments passed to the methods. The following snippet demonstrates how to show the Saved Games UI as well as how to use the onActivityResult() method to handle creating a new save or loading an existing one:

// display the Saved Games UI
// RC_SAVED_GAMES is set to an int to identify it
private static final int RC_SAVED_GAMES = 1003;

private void showSavedGamesUI() {
// set number of saves to show
int maxNumberOfSavedGamesToShow = 3;
// args 3 and 4 represent allowAddButton and allowDelete
Intent savedGamesIntent =
Games.Snapshots.getSelectSnapshotIntent(myGoogleApiClient,
"See Saved Games", true, true, maxNumberOfSavedGamesToShow);
startActivityForResult(savedGamesIntent, RC_SAVED_GAMES);
}

// save a new game or load an existing one
// start by creating a temp snapshot
private String myCurrentSaveName = "snapshotTemp";


// this callback is triggered after startActivityForResult() is called
// from the showSavedGamesUI() method.

@Override
protected void onActivityResult(int requestCode, int resultCode,
Intent intent) {

if (intent != null) {
if (intent.hasExtra(Snapshots.EXTRA_SNAPSHOT_METADATA)) {
// load a snapshot
SnapshotMetadata snapshotMetadata = (SnapshotMetadata)
intent.getParcelableExtra(Snapshots.EXTRA_SNAPSHOT_METADATA);
// avoid hardcoding names, use the name from the snapshot
myCurrentSaveName = snapshotMetadata.getUniqueName();

// continue logic here to load the game data from the Snapshot

} else if (intent.hasExtra(Snapshots.EXTRA_SNAPSHOT_NEW)) {
// Create a new snapshot, name it with a unique string
String unique = new BigInteger(281, new Random()).toString(13);
myCurrentSaveName = "snapshotTemp-" + unique;

// continue the create the new snapshot logic
}
}
}

If you need further references on how to implement this logic into your game, visit the package docs at https://developers.google.com/android/reference/com/google/android/gms/games/snapshot/package-summary. You can also view the “SavedGames” code sample athttps://github.com/playgameservices/android-basic-samples/tree/master/BasicSamples/SavedGames. This sample also includes how to migrate data from the old Cloud Save service to the Saved Games service that is part of the Google Play Games Services.

Summary

In this chapter, you learned the basics of working with account details by using the AccountManager. This was done by specifying a package name that matched some Google accounts, and a name for the user account was retrieved. You also learned that there may be multiple accounts on a device and that you should get them all and either return a list or allow the user to choose which one to use.

You also learned about the Android Backup Service. This service allows you to make small backups that will restore user settings when they have to wipe, hard-reset, or set up a new device. You learned that this is not a suitable service for data synchronization, but is a helpful and free solution for minor data restoration needs.

You learned about the Google Drive Android API that can be used to load files to and from a device using Google Drive. You learned about the benefits of using this service because it allows for a seamless integration for mobile users who are constantly moving in and out of data or network range. You also learned how to read and write files using this API.

Finally, you were shown a portion of the Google Play Games Services. These services offer a lot of methods and libraries to help make game development easier. You learned how to save games using a snapshot, how to load a game, and how to use the built-in UI solution for performing both saves and loading games to a device.