GooglePlayGames.BasicApi.SavedGame.ISavedGameClient

The main entry point for interacting with saved games.

Summary

Saved games are persisted in the cloud along with several game-specific properties (ISavedGameMetadata for more information). There are several core concepts involved with saved games:

Filenames - act as unique identifiers for saved games. Two devices performing a read or write using the same filename will end up reading or modifying the same file (i.e. filenames are not device specific).

Saved Game Metadata are represented by ISavedGameMetadata. The instances allow access to metadata properties about the underlying saved game (e.g. description). In addition, metadata functions as a handle that are required to read and manipulate saved game contents. Lastly, metadata may be "Open". Open metadata instances are required to manipulate the underlying binary data of the saved game. See method comments to determine whether a specific method requires or returns an open saved game.

Conflicts occur when multiple devices attempt to write to the same file at the same time. The saved game system guarantees that no conflicting writes will be lost or silently overwritten. Instead, they must be handled the next time the file with a conflict is Opened. Conflicts can be handled automatically ( OpenWithAutomaticConflictResolution) or can be manuallyhandled by the developer (OpenWithManualConflictResolution). See the Open methods for more discussion.

Saved games will generally be used in the following workflow:

1. Determine which saved game to use (either using a hardcoded filename or ShowSelectSavedGameUI)
2. Open the file using OpenWithManualConflictResolution or OpenWithAutomaticConflictResolution
3. Read the binary data of the saved game using ReadBinaryData handle it as appropriate for your game.
4. When you have updates, persist them in the cloud using CommitUpdate. Note that writing to the cloud is relatively expensive, and shouldn't be done frequently.

See online documentation for Saved Games for more information.

Public functions
CommitUpdate(ISavedGameMetadata metadata, SavedGameMetadataUpdate updateForMetadata, byte[] updatedBinaryData, Action< SavedGameRequestStatus, ISavedGameMetadata > callback)	void Durably commits an update to the passed saved game.
Delete(ISavedGameMetadata metadata)	void Delete the specified snapshot.
FetchAllSavedGames(DataSource source, Action< SavedGameRequestStatus, List< ISavedGameMetadata >> callback)	void Returns the metadata for all known saved games for this game.
OpenWithAutomaticConflictResolution(string filename, DataSource source, ConflictResolutionStrategy resolutionStrategy, Action< SavedGameRequestStatus, ISavedGameMetadata > callback)	void Opens the file with the indicated name and data source.
OpenWithManualConflictResolution(string filename, DataSource source, bool prefetchDataOnConflict, ConflictCallback conflictCallback, Action< SavedGameRequestStatus, ISavedGameMetadata > completedCallback)	void Opens the file with the indicated name and data source.
ReadBinaryData(ISavedGameMetadata metadata, Action< SavedGameRequestStatus, byte[]> completedCallback)	void Reads the binary data of the passed saved game.
ShowSelectSavedGameUI(string uiTitle, uint maxDisplayedSavedGames, bool showCreateSaveUI, bool showDeleteSaveUI, Action< SelectUIStatus, ISavedGameMetadata > callback)	void Shows the select saved game UI with the indicated configuration.

Public functions

CommitUpdate

void CommitUpdate(
  ISavedGameMetadata metadata,
  SavedGameMetadataUpdate updateForMetadata,
  byte[] updatedBinaryData,
  Action< SavedGameRequestStatus, ISavedGameMetadata > callback
)

Durably commits an update to the passed saved game.

When this method returns successfully, the data is durably persisted to disk and will eventually be uploaded to the cloud (in practice, this will happen very quickly unless the device does not have a network connection). If an update to the saved game has occurred after the metadata was retrieved from the cloud, this update will produce a conflict (this commonly occurs if two different devices are writing to the cloud at the same time). All conflicts must be handled the next time this saved game is opened. See OpenWithManualConflictResolution and OpenWithAutomaticConflictResolution for more information.

Details

Parameters

metadata The metadata for the saved game to update. This metadata must be Open (i.e. ISavedGameMetadata.IsOpen returns true)."/> If it is not open, the method will immediately fail with status All updates that should be applied to the saved game metadata. updatedBinaryData The new binary content of the saved game callback The callback that is invoked when this operation finishes. The returned metadata will only be non-null if the commit succeeded. If an error is encountered during conflict resolution, that error will be reflected here. This callback will always execute on the game thread and the returned metadata (if any) will NOT be "Open" (i.e. commiting an update closes the metadata).

Delete

void Delete(
  ISavedGameMetadata metadata
)

Delete the specified snapshot.

This will delete the data of the snapshot locally and on the server.

Details
Parameters	metadata the saved game metadata identifying the data to delete.

FetchAllSavedGames

void FetchAllSavedGames(
  DataSource source,
  Action< SavedGameRequestStatus, List< ISavedGameMetadata >> callback
)

Returns the metadata for all known saved games for this game.

All returned saved games are not open, and must be opened before they can be used for writes or binary data reads. The callback will always occur on the game thread.

Details

Parameters

source The data source to use. DataSource for a description of the available options here. callback The callback that is invoked when this operation finishes. The returned metadata will only be non-empty if the commit succeeded. If an error is encountered during the fetch, that error will be reflected here. This callback will always execute on the game thread and the returned metadata (if any) will NOT be "Open".

OpenWithAutomaticConflictResolution

void OpenWithAutomaticConflictResolution(
  string filename,
  DataSource source,
  ConflictResolutionStrategy resolutionStrategy,
  Action< SavedGameRequestStatus, ISavedGameMetadata > callback
)

Opens the file with the indicated name and data source.

If the file has an outstanding conflict, it will be resolved using the specified conflict resolution strategy. The metadata returned by this method will be "Open" - it can be used as a parameter for CommitUpdate and ResolveConflictByChoosingMetadata.

Details

Parameters

filename The name of the file to open. Filenames must consist of only non-URL reserved characters (i.e. a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "~") be between 1 and 100 characters in length (inclusive). source The data source to use. DataSource for a description of the available options here. resolutionStrategy The conflict resolution that should be used if any conflicts are encountered while opening the file. ConflictResolutionStrategy for a description of these strategies. callback The callback that is invoked when this operation finishes. The returned metadata will only be non-null if the open succeeded. This callback will always execute on the game thread and the returned metadata (if any) will be "Open".

OpenWithManualConflictResolution

void OpenWithManualConflictResolution(
  string filename,
  DataSource source,
  bool prefetchDataOnConflict,
  ConflictCallback conflictCallback,
  Action< SavedGameRequestStatus, ISavedGameMetadata > completedCallback
)

Opens the file with the indicated name and data source.

If there is a conflict that requires resolution, it will be resolved manually using the passed conflict callback. Once all pending conflicts are resolved, the completed callback will be invoked with the retrieved data. In the event of an error, the completed callback will be invoked with the corresponding error status. All callbacks will be executed on the game thread.

Details

Parameters

filename The name of the file to open. Filenames must consist of only non-URL reserved characters (i.e. a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "~") be between 1 and 100 characters in length (inclusive). source The data source to use. DataSource for a description of the available options here. prefetchDataOnConflict If set to true, the data for the two conflicting files will be automatically retrieved and passed as parameters in conflictCallback . If set to false, null binary data will be passed into conflictCallback and the caller will have to fetch it themselves. conflictCallback The callback that will be invoked if one or more conflict is encountered while executing this method. Note that more than one conflict may be present and that this callback might be executed more than once to resolve multiple conflicts. This callback is always executed on the game thread. completedCallback The callback that is invoked when this operation finishes. The returned metadata will only be non-null if the open succeeded. If an error is encountered during conflict resolution, that error will be reflected here. This callback will always execute on the game thread and the returned metadata (if any) will be "Open".

ReadBinaryData

void ReadBinaryData(
  ISavedGameMetadata metadata,
  Action< SavedGameRequestStatus, byte[]> completedCallback
)

Reads the binary data of the passed saved game.

The passed metadata must be opened (i.e. ISavedGameMetadata.IsOpen returns true). The callback will always be executed on the game thread.

Details

Parameters

metadata The metadata for the saved game whose binary data we want to read. This metadata must be open. If it is not open, the method will immediately fail with status SelectUIStatus.BadInputError. completedCallback The callback that is invoked when the read finishes. If the read completed without error, the passed status will be SavedGameRequestStatus.Success and the passed bytes will correspond to the binary data for the file. In the case of

ShowSelectSavedGameUI

void ShowSelectSavedGameUI(
  string uiTitle,
  uint maxDisplayedSavedGames,
  bool showCreateSaveUI,
  bool showDeleteSaveUI,
  Action< SelectUIStatus, ISavedGameMetadata > callback
)

Shows the select saved game UI with the indicated configuration.

If the user selects a saved game in that UI, it will be returned in the passed callback. This metadata will be unopened and must be passed to either OpenWithManualConflictResolution or OpenWithAutomaticConflictResolution in order to retrieve the binary data. The callback will always be executed on the game thread.

Details

Parameters

uiTitle The user-visible title of the displayed selection UI. maxDisplayedSavedGames The maximum number of saved games the UI may display. This value must be greater than 0. showCreateSaveUI If set to true, show UI that will allow the user to create a new saved game. showDeleteSaveUI If set to true show UI that will allow the user to delete a saved game. callback The callback that is invoked when an error occurs or if the user finishes interacting with the UI. If the user selected a saved game, this will be passed into the callback along with the SelectUIStatus.SavedGameSelected status. This saved game will not be Open, and must be opened before it can be written to or its binary data can be read. If the user backs out of the UI without selecting a saved game, this callback will receive UserClosedUI and a null saved game. This callback will always execute on the game thread.