This guide shows you how to use the Saved Games API in an Android application.
The API can be found in the
Before you begin
If you haven't already done so, you might find it helpful to review the Saved Games game concepts.
Before you start to code using the Saved Games API:
- Install the Google Play Services SDK.
- Download and review the Saved Games code sample.
- Enable the Saved Games service in the Google Play Developer Console.
- Specify the
Drive.APIAPI when you create your
- Follow the sign-in checklist recommendations.
Once the player is signed in and the
connected, your game can start using the Saved Games API.
Displaying Saved Games
You can integrate the Saved Games API wherever your game provides players with the option to save or restore their progress. Your game might display such an option at designated save/restore points or allow players to save or restore progress at any time.
Once players select the save/restore option in your game, your game should bring up a screen that prompts the players to enter information for a new saved game or select an existing saved game to restore. To simplify your development, the Saved Games API provides a default Saved Games selection user interface (UI) that you can use out-of-the-box. The Saved Games selection UI allows players to create a new saved game, view details about existing saved games, and load previous saved games.
To bring up the default Saved Games UI:
getSelectSnapshotIntent()to get an
Intentfor launching the default Saved Games selection UI. In the method call, you can set boolean values in the
allowDeleteparameters to indicate if your game wants the UI to provide buttons to create a new saved game or delete existing saved games.
startActivityForResult()and pass in that
Intent. If the call is successful, the game displays the Saved Game selection UI, along with the options you specified.
The following snippet shows how to bring up the default Saved Games selection UI:
If the player selects to create a new saved game or load an existing saved game,
the UI sends a request to Google Play games services. If the request is successful,
Google Play games services returns a
Snapshot object representing the saved game to your game through
onActivityResult() callback. Your game can override this callback to
check if any errors occurred during request.
The following code snippet shows a sample implementation of
Writing Saved Games
To store content to a saved game, your game must obtain a reference to a
Snapshot object then call
open() to get access to modify its
contents. You can store a player's data in byte format by calling
Once all your modifications are made to the saved game's content or metadata,
commitAndClose() to send your changes to Google's servers. In the method call, your game can associate additional information to
tell Google Play games services how to present this saved game to players. This
information is represented in a
object, which your game creates using
The following snippet shows how your game might commit changes to a saved game:
If the player's device is not connected to a network when your app calls
commitAndClose(), Google Play games services stores the saved game data locally on the device. Upon device re-connection,
Google Play games services syncs the locally cached saved game changes to Google's
Loading Saved Games
To retrieve all saved games for the currently signed-in player, call
Your game can also retrieve a specific saved game through the player's UI
selection, as described in Displaying Saved Games.
The returned saved game is represented as a
your game can then open to read its content and metadata.
To improve your game's performance, you are encouraged to perform saved game
loading as a background operation rather than in the main thread. One way to do
this is by using an
and override its
doInBackground() method to open the saved game.
The following snippet shows how you might implement the
AsyncTask to load a specific saved game:
Handling saved game conflicts
When using the Saved Games service in your game, it is possible for multiple devices to perform reads and writes on the same saved game. In the event that a device temporarily loses its network connection and later reconnects, this might cause data conflicts whereby the saved game stored on a player's local device is out-of-sync with the remote version stored in Google's servers. The Saved Games services provides a conflict resolution mechanism that presents both sets of conflicting saved games at read-time and lets you implement a resolution strategy that is appropriate for your game.
When Google Play games services detects a data conflict, it notifies your game
during a saved game open operation by returning a status code of
In this event, the
provides two versions of the saved game:
- The most-up-to-date version known by Google Play games services to be accurate; and
- A modified version detected on one of the player's devices that contains conflicting content or metadata. This may not be the same as the version that you tried to save.
Your game must decide how to resolve the conflict by picking one of the provided versions or merging the data of the two saved game versions.
To detect and resolve saved game conflicts, follow these steps:
STATUS_SNAPSHOT_CONFLICTis returned, you have a conflict to resolve.
OpenSnapshotResult.getConflictId()to retrieve the conflict ID that uniquely identifies the detected conflict. Your game needs this value to send a conflict resolution request later.
getConflictingSnapshot()to get the modified version.
getSnapshot()to get the server version.
- To resolve the saved game conflict, select a version that you want to save to the server as the final version, and pass it to
The following snippet shows and example of how your game might handle a saved game conflict by selecting the newest saved game as the final version to save:
Modifying a saved game for conflict resolution
If you want to merge data from the two Saved Games or modify an existing
Snapshot to save to the server as the resolved final version, follow these steps:
- Pick a
getSnapshot()as your base.
- Next, call
Snapshots.resolveConflict()and pass in the
Snapshotthat you selected in the previous step. This stores the
Snapshotto the server.
open()to retrieve the
Snapshotthat you just stored in the previous step. Now make your modifications to the returned
Snapshot, then call
Snapshots.commitAndClose()to upload the modified save game to the server.
Migrating from the AppState API
If your game uses the Cloud Save (
AppState) API to store player
data to Google Play games services, you should migrate your code to use the Saved
Games API as soon as possible. The following table lists the code changes that
you should be aware of when migrating your game:
|Operation||Cloud Save||Saved Games|