com.google.android.gms.games.snapshot.Snapshots |
The Snapshots API allows you to store data representing the player's game progress on Google's servers. Your app can use this data to restore saved state from a previous gaming session and provide a visual indicator of progression to the player.
For more details, see the saved games developer guide.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Snapshots.CommitSnapshotResult | Result delivered when a snapshot has been committed. | ||||||||||
Snapshots.DeleteSnapshotResult | Result delivered when a snapshot has been deleted. | ||||||||||
Snapshots.LoadSnapshotsResult | Result delivered when snapshot data has been loaded. | ||||||||||
Snapshots.OpenSnapshotResult | Result delivered when a snapshot has been opened. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | DISPLAY_LIMIT_NONE | Constant passed to getSelectSnapshotIntent(GoogleApiClient, String, boolean, boolean, int) indicating that the UI should not cap the
number of displayed snapshots. |
|||||||||
String | EXTRA_SNAPSHOT_METADATA | Intent extra used to pass a SnapshotMetadata . |
|||||||||
String | EXTRA_SNAPSHOT_NEW | Intent extra used to indicate the user wants to create a new snapshot. | |||||||||
int | RESOLUTION_POLICY_HIGHEST_PROGRESS | In the case of a conflict, the snapshot with the highest progress value will be used. | |||||||||
int | RESOLUTION_POLICY_LAST_KNOWN_GOOD | In the case of a conflict, the last known good version of this snapshot will be used. | |||||||||
int | RESOLUTION_POLICY_LONGEST_PLAYTIME | In the case of a conflict, the snapshot with the longest played time will be used. | |||||||||
int | RESOLUTION_POLICY_MANUAL | In the case of a conflict, the result will be returned to the app for resolution. | |||||||||
int | RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED | In the case of a conflict, the most recently modified version of this snapshot will be used. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Commit any modifications made to the snapshot.
| |||||||||||
Delete the specified snapshot.
| |||||||||||
Discard the contents of the snapshot and close the contents.
| |||||||||||
Gets the maximum data size per snapshot cover image in bytes.
| |||||||||||
Gets the maximum data size per snapshot in bytes.
| |||||||||||
Returns an intent that will let the user select a snapshot.
| |||||||||||
Asynchronously load the snapshot data for the currently signed-in player.
| |||||||||||
Open a snapshot with the given metadata (usually returned from
load(GoogleApiClient, boolean) . | |||||||||||
Open a snapshot with the given name.
| |||||||||||
Open a snapshot with the given name.
| |||||||||||
Open a snapshot with the given metadata (usually returned from
load(GoogleApiClient, boolean) . | |||||||||||
Resolve a conflict using the provided data.
| |||||||||||
Resolve a conflict using the data from the provided snapshot.
|
Constant passed to getSelectSnapshotIntent(GoogleApiClient, String, boolean, boolean, int)
indicating that the UI should not cap the
number of displayed snapshots.
Intent extra used to pass a SnapshotMetadata
.
See also:
Intent extra used to indicate the user wants to create a new snapshot.
See also:
In the case of a conflict, the snapshot with the highest progress value will be used. In the case of a tie, the last known good snapshot will be chosen instead.
This policy is a good choice if your game uses the progress value of the snapshot to
determine the best saved game. Note that you must use
setProgressValue(long)
when saving games for this
policy to be meaningful.
In the case of a conflict, the last known good version of this snapshot will be used. This
corresponds to the data that would be returned from getSnapshot()
in a custom merge.
This policy is a reasonable choice if your game requires stability from the snapshot data. This policy ensures that only writes which are not contested are seen by the player, which guarantees that all clients converge.
In the case of a conflict, the snapshot with the longest played time will be used. In the case of a tie, the last known good snapshot will be chosen instead.
This policy is a good choice if the length of play time is a reasonable proxy for the "best"
save game. Note that you must use
setPlayedTimeMillis(long)
when saving games for this
policy to be meaningful.
In the case of a conflict, the result will be returned to the app for resolution. No automatic resolution will be performed.
This policy ensures that no user changes to the state of the save game will ever be lost.
In the case of a conflict, the most recently modified version of this snapshot will be used.
This corresponds to the data that would be returned from
getConflictingSnapshot()
in a custom merge.
This policy is a reasonable choice if your game can tolerate players on multiple devices clobbering their own changes. Because this policy blindly chooses the most recent data, it is possible that a player's changes may get lost.
Commit any modifications made to the snapshot. This will cause the changes to be synced to the server in the background.
Calling this method with a snapshot that has already been committed or that was not opened
via open(GoogleApiClient, SnapshotMetadata)
will throw an exception.
Note that the total size of the contents of snapshot
may not exceed the size provided
by getMaxDataSize(GoogleApiClient)
.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
snapshot |
Snapshot :
The snapshot to commit the data for. |
metadataChange |
SnapshotMetadataChange :
The set of changes to apply to the metadata for the snapshot. Use
EMPTY_CHANGE to preserve the existing metadata. |
Returns | |
---|---|
PendingResult<Snapshots.CommitSnapshotResult> |
PendingResult to access the data when available.
|
Delete the specified snapshot. This will delete the data of the snapshot locally and on the server.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
metadata |
SnapshotMetadata :
The metadata of the snapshot to delete. |
Returns | |
---|---|
PendingResult<Snapshots.DeleteSnapshotResult> |
PendingResult to check the status of the operation.
|
Discard the contents of the snapshot and close the contents. This will discard all changes made to the file, and close the snapshot to future changes until it is re-opened. The file will not be modified on the server.
Calling this method with a snapshot that has already been committed or that was not opened
via open(GoogleApiClient, SnapshotMetadata)
will throw an exception.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
snapshot |
Snapshot :
The snapshot to discard the data for.
|
Gets the maximum data size per snapshot cover image in bytes. Guaranteed to be at least 800 KB. May increase in the future.
If the service cannot be reached for some reason, this will return -1.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
Returns | |
---|---|
int |
The maximum data size per snapshot cover image in bytes. |
Gets the maximum data size per snapshot in bytes. Guaranteed to be at least 3 MB. May increase in the future.
If the service cannot be reached for some reason, this will return -1.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
Returns | |
---|---|
int |
The maximum data size per snapshot in bytes. |
Returns an intent that will let the user select a snapshot. Note that this must be invoked
using startActivityForResult(Intent, int)
so that the identity of the
calling package can be established.
If the user canceled without selecting a snapshot, the result will be
RESULT_CANCELED
. If the user selected a snapshot from the list, the result
will be RESULT_OK
and the data intent will contain the selected Snapshot as
a parcelable object in EXTRA_SNAPSHOT_METADATA
. If the user pressed the add button,
the result will be RESULT_OK
and the data intent will contain a true boolean
value in EXTRA_SNAPSHOT_NEW
.
Note that if you have modified an open snapshot, the changes will not appear in this UI until
you call commitAndClose(GoogleApiClient, Snapshot, SnapshotMetadataChange)
on the snapshot.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
title |
String :
The title to display in the action bar of the returned Activity. |
allowAddButton |
boolean :
Whether or not to display a "create new snapshot" option in the
selection UI. |
allowDelete |
boolean :
Whether or not to provide a delete overflow menu option for each snapshot
in the selection UI. |
maxSnapshots |
int :
The maximum number of snapshots to display in the UI. Use
DISPLAY_LIMIT_NONE to display all snapshots. |
Returns | |
---|---|
Intent |
An Intent that can be started to view the select snapshot UI.
|
This method takes a Bundle
object and extracts the Snapshot
provided. If the
Bundle
is invalid or does not contain the correct data, this method returns null.
Parameters | |
---|---|
extras |
Bundle :
The Bundle to parse for a Snapshot object. |
Returns | |
---|---|
SnapshotMetadata |
A SnapshotMetadata object that was provided for action.
|
Asynchronously load the snapshot data for the currently signed-in player.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
forceReload |
boolean :
If true, this call will clear any locally cached data and attempt to fetch
the latest data from the server. This would commonly be used for something like a
user-initiated refresh. Normally, this should be set to false to gain advantages
of data caching. |
Returns | |
---|---|
PendingResult<Snapshots.LoadSnapshotsResult> |
PendingResult to access the data when available.
|
Open a snapshot with the given metadata (usually returned from
load(GoogleApiClient, boolean)
. To succeed, the snapshot must exist; i.e. this call
will fail if the snapshot was deleted between the load and open calls.
This will open the snapshot using RESOLUTION_POLICY_MANUAL
as a conflict policy.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
metadata |
SnapshotMetadata :
The metadata of the existing snapshot to load. |
Returns | |
---|---|
PendingResult<Snapshots.OpenSnapshotResult> |
PendingResult to access the data when available.
|
Open a snapshot with the given name. If createIfNotFound
is set to true, the
specified snapshot will be created if it does not already exist.
This will open the snapshot using RESOLUTION_POLICY_MANUAL
as a conflict policy.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
fileName |
String :
The name of the snapshot file to open. Must be between 1 and 100
non-URL-reserved characters (a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "~"). |
createIfNotFound |
boolean :
If true, the snapshot will be created if one cannot be found. |
Returns | |
---|---|
PendingResult<Snapshots.OpenSnapshotResult> |
PendingResult to access the data when available.
|
Open a snapshot with the given name. If createIfNotFound
is set to true, the
specified snapshot will be created if it does not already exist.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
fileName |
String :
The name of the snapshot file to open. Must be between 1 and 100
non-URL-reserved characters (a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "~"). |
createIfNotFound |
boolean :
If true, the snapshot will be created if one cannot be found. |
conflictPolicy |
int :
The conflict resolution policy to use for this snapshot. |
Returns | |
---|---|
PendingResult<Snapshots.OpenSnapshotResult> |
PendingResult to access the data when available.
|
Open a snapshot with the given metadata (usually returned from
load(GoogleApiClient, boolean)
. To succeed, the snapshot must exist; i.e. this call
will fail if the snapshot was deleted between the load and open calls.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
metadata |
SnapshotMetadata :
The metadata of the existing snapshot to load. |
conflictPolicy |
int :
The conflict resolution policy to use for this snapshot. |
Returns | |
---|---|
PendingResult<Snapshots.OpenSnapshotResult> |
PendingResult to access the data when available.
|
Resolve a conflict using the provided data. This will replace the data on the server with the specified metadata changes and contents. Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.
Values which are not included in the metadata change will be resolved to the version currently on the server.
Note that the total size of contents
may not exceed the size provided by
getMaxDataSize(GoogleApiClient)
.
Calling this method with a snapshot that has already been committed or that was not opened
via open(GoogleApiClient, SnapshotMetadata)
will throw an exception.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
conflictId |
String :
The ID of the conflict to resolve. Must come from
getConflictId() . |
snapshotId |
String :
The ID of the snapshot to resolve the conflict for. |
metadataChange |
SnapshotMetadataChange :
The set of changes to apply to the metadata for the snapshot. |
snapshotContents |
SnapshotContents :
The SnapshotContents to replace the snapshot data with. |
Returns | |
---|---|
PendingResult<Snapshots.OpenSnapshotResult> |
PendingResult to access the data when available.
|
Resolve a conflict using the data from the provided snapshot. This will replace the data on the server with the specified snapshot. Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.
Note that the total size of the contents of snapshot
may not exceed the size provided
by getMaxDataSize(GoogleApiClient)
.
Calling this method with a snapshot that has already been committed or that was not opened
via open(GoogleApiClient, SnapshotMetadata)
will throw an exception.
Required API: API
Required Scopes: SCOPE_GAMES
and SCOPE_APPFOLDER
.
Parameters | |
---|---|
apiClient |
GoogleApiClient :
The GoogleApiClient to service the call. |
conflictId |
String :
The ID of the conflict to resolve. Must come from
getConflictId() . |
snapshot |
Snapshot :
The snapshot to use to resolve the conflict. |
Returns | |
---|---|
PendingResult<Snapshots.OpenSnapshotResult> |
PendingResult to access the data when available.
|