public final class

GamesClient

extends Object
implements GooglePlayServicesClient
java.lang.Object
   ↳ com.google.android.gms.games.GamesClient

Class Overview

Main public entry point for Games APIs.

Summary

Nested Classes
class GamesClient.Builder Builder class for GamesClient. 
Constants
String EXTRA_EXCLUSIVE_BIT_MASK Used to bundle the exclusive bit mask of the player for auto-match criteria.
String EXTRA_INVITATION Used to return an Invitation.
String EXTRA_MAX_AUTOMATCH_PLAYERS Used to return the maximum number of players that should be added to a room by auto-matching.
String EXTRA_MIN_AUTOMATCH_PLAYERS Used to return the minimum number of players that should be added to a room by auto-matching.
String EXTRA_PLAYERS Used to return a list of player IDs.
String EXTRA_PLAYER_SEARCH_RESULTS Used by the Player Search UI to return a list of parceled Player objects.
String EXTRA_ROOM Used to return a Room.
String EXTRA_TURN_BASED_MATCH Used to return a TurnBasedMatch.
int MAX_RELIABLE_MESSAGE_LEN This gives the maximum message size supported via the sendReliableRealTimeMessage(RealTimeReliableMessageSentListener, byte[], String, String) methods (excluding protocol headers).
int MAX_UNRELIABLE_MESSAGE_LEN This gives the maximum (unfragmented) message size supported via the sendUnreliableRealTimeMessage(byte[], String, String) methods (excluding protocol headers).
int NOTIFICATION_TYPES_ALL Notification types for any notification.
int NOTIFICATION_TYPES_MULTIPLAYER Notification types for multiplayer notifications.
int NOTIFICATION_TYPE_INVITATION Notification type for invites to multiplayer games.
int NOTIFICATION_TYPE_MATCH_UPDATE Notification type for updates to match information.
int STATUS_ACHIEVEMENT_NOT_INCREMENTAL Indicates that the call to increment achievement failed since the achievement is not an incremental achievement.
int STATUS_ACHIEVEMENT_UNKNOWN Could not find the achievement, so the operation to update the achievement failed.
int STATUS_ACHIEVEMENT_UNLOCKED Indicates that the incremental achievement was also unlocked when the call was made to increment the achievement.
int STATUS_ACHIEVEMENT_UNLOCK_FAILURE An incremental achievement cannot be unlocked directly, so the call to unlock achievement failed.
int STATUS_APP_MISCONFIGURED The developer has misconfigured their application in some way.
int STATUS_CLIENT_RECONNECT_REQUIRED The GamesClient is in an inconsistent state and must reconnect to the service to resolve the issue.
int STATUS_GAME_NOT_FOUND The specified game ID was not recognized by the server.
int STATUS_INTERNAL_ERROR An unspecified error occurred; no more specific information is available.
int STATUS_INVALID_REAL_TIME_ROOM_ID Constant indicating that the real-time room ID provided to the operation was not valid, or does not correspond to the currently active real-time room.
int STATUS_LICENSE_CHECK_FAILED The game is not licensed to the user.
int STATUS_MATCH_ERROR_ALREADY_REMATCHED The specified match has already had a rematch created.
int STATUS_MATCH_ERROR_INACTIVE_MATCH The match is not currently active.
int STATUS_MATCH_ERROR_INVALID_MATCH_RESULTS The match results provided in this API call are invalid.
int STATUS_MATCH_ERROR_INVALID_MATCH_STATE The match is not in the correct state to perform the specified action.
int STATUS_MATCH_ERROR_INVALID_PARTICIPANT_STATE One or more participants in this match are not in valid states.
int STATUS_MATCH_ERROR_LOCALLY_MODIFIED The specified match has already been modified locally.
int STATUS_MATCH_ERROR_OUT_OF_DATE_VERSION The match data is out of date.
int STATUS_MATCH_NOT_FOUND The specified match cannot be found.
int STATUS_MULTIPLAYER_DISABLED This game does not support multiplayer.
int STATUS_MULTIPLAYER_ERROR_CREATION_NOT_ALLOWED The user is not allowed to create a new multiplayer game at this time.
int STATUS_MULTIPLAYER_ERROR_INVALID_MULTIPLAYER_TYPE The match is not the right type to perform this action on.
int STATUS_MULTIPLAYER_ERROR_INVALID_OPERATION This multiplayer operation is not valid, and the server rejected it.
int STATUS_MULTIPLAYER_ERROR_NOT_TRUSTED_TESTER The user attempted to invite another user who was not authorized to see the game.
int STATUS_NETWORK_ERROR_NO_DATA A network error occurred while attempting to retrieve fresh data, and no data was available locally.
int STATUS_NETWORK_ERROR_OPERATION_DEFERRED A network error occurred while attempting to modify data, but the data was successfully modified locally and will be updated on the network the next time the device is able to sync.
int STATUS_NETWORK_ERROR_OPERATION_FAILED A network error occurred while attempting to perform an operation that requires network access.
int STATUS_NETWORK_ERROR_STALE_DATA A network error occurred while attempting to retrieve fresh data, but some locally cached data was available.
int STATUS_OK The operation was successful.
int STATUS_OPERATION_IN_FLIGHT Trying to start a join/create operation while another is already in flight.
int STATUS_PARTICIPANT_NOT_CONNECTED Constant indicating that the ID of the participant provided by the user is not currently connected to the client in the real-time room.
int STATUS_REAL_TIME_CONNECTION_FAILED Failed to initialize the network connection for a real-time room.
int STATUS_REAL_TIME_INACTIVE_ROOM The room is not currently active.
int STATUS_REAL_TIME_MESSAGE_FAILED Status code returned from the sendUnreliableRealTimeMessage(byte[], String, String) and sendReliableRealTimeMessage(RealTimeReliableMessageSentListener, byte[], String, String) methods when the message send operation failed due to an immediate error.
int STATUS_REAL_TIME_MESSAGE_SEND_FAILED Failed to send message to the peer participant for a real-time room.
int STATUS_REAL_TIME_ROOM_NOT_JOINED Failed to send message to the peer participant for a real-time room, since the user has not joined the room.
Public Methods
void acceptTurnBasedInvitation(OnTurnBasedMatchInitiatedListener listener, String invitationId)
Accept an invitation for a turn-based match.
void cancelTurnBasedMatch(String matchId)
Cancels a turn-based match.
void cancelTurnBasedMatch(OnTurnBasedMatchCanceledListener listener, String matchId)
Cancels a turn-based match.
void clearAllNotifications()
Clear all notifications for the current game and signed-in player.
void clearNotifications(int notificationTypes)
Clear the notifications of the specified type for the current game and signed-in player.
void connect()
Connect to the games service.
void createRoom(RoomConfig config)
Create a real-time room for the current game.
void createTurnBasedMatch(OnTurnBasedMatchInitiatedListener listener, TurnBasedMatchConfig config)
Create a turn-based match for the current game.
void declineRoomInvitation(String invitationId)
Decline an invitation for a real-time room.
void declineTurnBasedInvitation(String invitationId)
Decline an invitation for a turn-based match.
void disconnect()
Closes the connection to Google Play services.
void dismissRoomInvitation(String invitationId)
Dismiss an invitation to a real-time room.
void dismissTurnBasedInvitation(String invitationId)
Dismiss an invitation to a turn-based match.
void dismissTurnBasedMatch(String matchId)
Delete a match from the server and local storage.
void finishTurnBasedMatch(OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, List<ParticipantResult> results)
Mark a match as finished.
void finishTurnBasedMatch(OnTurnBasedMatchUpdatedListener listener, String matchId)
Indicate that a participant is finished with a match.
void finishTurnBasedMatch(OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, ParticipantResult... results)
Mark a match as finished.
Intent getAchievementsIntent()
Gets an intent to show the list of achievements for a game.
Intent getAllLeaderboardsIntent()
Gets an intent to show the list of leaderboards for a game.
String getAppId()
Get the application ID linked to this GamesClient instance.
String getCurrentAccountName()
Get the name of the currently selected account.
Game getCurrentGame()
Player getCurrentPlayer()
String getCurrentPlayerId()
Intent getInvitationInboxIntent()
Returns an intent that will let the user see and manage any outstanding invitations.
Intent getLeaderboardIntent(String leaderboardId)
Gets an intent to show a leaderboard for a game.
Intent getMatchInboxIntent()
Returns an intent that will let the user see and manage any outstanding invitations and matches.
int getMaxTurnBasedMatchDataSize()
Gets the maximum data size per match in bytes.
Intent getPlayerSearchIntent()
Returns an intent that will display a screen where the user can search for people on Google+.
RealTimeSocket getRealTimeSocketForParticipant(String roomId, String participantId)
Returns a RealTimeSocket for carrying network traffic to the given peer.
Intent getRealTimeWaitingRoomIntent(Room room, int minParticipantsToStart)
Returns an intent that will display a "waiting room" screen that shows the progress of participants joining a real-time multiplayer room.
Intent getSelectPlayersIntent(int minPlayers, int maxPlayers)
Returns an intent that will let the user select players to send an invitation to.
Intent getSelectPlayersIntent(int minPlayers, int maxPlayers, boolean allowAutomatch)
Returns an intent that will let the user select players to send an invitation to.
Intent getSettingsIntent()
Gets an intent to show the Settings screen that allows the user to configure GamesClient-related features for the current game.
void getTurnBasedMatch(OnTurnBasedMatchLoadedListener listener, String matchId)
Load a specified turn-based match.
void incrementAchievement(String id, int numSteps)
Increments an achievement by the given number of steps.
void incrementAchievementImmediate(OnAchievementUpdatedListener listener, String id, int numSteps)
Increments an achievement by the given number of steps.
boolean isConnected()
Checks if the client is currently connected to the service, so that requests to other methods will succeed.
boolean isConnecting()
Checks if the client is attempting to connect to the service.
boolean isConnectionCallbacksRegistered(GooglePlayServicesClient.ConnectionCallbacks listener)
Returns true if the specified listener is currently registered to receive connection events.
boolean isConnectionFailedListenerRegistered(GooglePlayServicesClient.OnConnectionFailedListener listener)
Returns true if the specified listener is currently registered to receive connection failed events.
void joinRoom(RoomConfig config)
Join a real-time room by accepting an invitation.
void leaveRoom(RoomUpdateListener listener, String roomId)
Leave the specified room.
void leaveTurnBasedMatch(OnTurnBasedMatchLeftListener listener, String matchId)
Leave the specified match when it is not the current player's turn.
void leaveTurnBasedMatchDuringTurn(OnTurnBasedMatchLeftListener listener, String matchId, String pendingParticipantId)
Leave the specified match during the current player's turn.
void loadAchievements(OnAchievementsLoadedListener listener, boolean forceReload)
Asynchronously load achievement data for the currently signed in player.
void loadCurrentPlayerLeaderboardScore(OnPlayerLeaderboardScoreLoadedListener listener, String leaderboardId, int span, int leaderboardCollection)
Asynchronously load the currently signed in player's score for a given leaderboard.
void loadGame(OnGamesLoadedListener listener)
Load the details for the current game.
void loadInvitablePlayers(OnPlayersLoadedListener listener, int pageSize, boolean forceReload)
Load the initial page of players the currently signed-in player can invite to a multiplayer game, sorted alphabetically by name.
void loadInvitations(OnInvitationsLoadedListener listener)
Asynchronously load the list of invitations for the current game.
void loadLeaderboardMetadata(OnLeaderboardMetadataLoadedListener listener, boolean forceReload)
Asynchronously load the list of leaderboard metadata for this game.
void loadLeaderboardMetadata(OnLeaderboardMetadataLoadedListener listener, String leaderboardId, boolean forceReload)
Asynchronously load a specific leaderboard's metadata for this game.
void loadMoreInvitablePlayers(OnPlayersLoadedListener listener, int pageSize)
Asynchronously loads an additional page of invitable players.
void loadMoreScores(OnLeaderboardScoresLoadedListener listener, LeaderboardScoreBuffer buffer, int maxResults, int pageDirection)
Asynchronously loads an additional page of score data for the given score buffer.
void loadPlayer(OnPlayersLoadedListener listener, String playerId)
Asynchronously loads the profile for the requested player ID.
void loadPlayerCenteredScores(OnLeaderboardScoresLoadedListener listener, String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)
Asynchronously load the player-centered page of scores for a given leaderboard.
void loadPlayerCenteredScores(OnLeaderboardScoresLoadedListener listener, String leaderboardId, int span, int leaderboardCollection, int maxResults)
Asynchronously load the player-centered page of scores for a given leaderboard.
void loadTopScores(OnLeaderboardScoresLoadedListener listener, String leaderboardId, int span, int leaderboardCollection, int maxResults)
Asynchronously load the top page of scores for a given leaderboard.
void loadTopScores(OnLeaderboardScoresLoadedListener listener, String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)
Asynchronously load the top page of scores for a given leaderboard.
void loadTurnBasedMatches(OnTurnBasedMatchesLoadedListener listener, int... matchTurnStatuses)
Asynchronously load turn-based matches for the current game.
void reconnect()
Closes the current connection to Google Play services and creates a new connection.
void registerConnectionCallbacks(GooglePlayServicesClient.ConnectionCallbacks listener)
Registers a listener to receive connection events from this GooglePlayServicesClient.
void registerConnectionFailedListener(GooglePlayServicesClient.OnConnectionFailedListener listener)
Registers a listener to receive connection failed events from this GooglePlayServicesClient.
void registerInvitationListener(OnInvitationReceivedListener listener)
Register a listener to intercept incoming invitations for the currently signed-in user.
void registerMatchUpdateListener(OnTurnBasedMatchUpdateReceivedListener listener)
Register a listener to intercept incoming match updates for the currently signed-in user.
void rematchTurnBasedMatch(OnTurnBasedMatchInitiatedListener listener, String matchId)
Create a rematch of a previously completed turn-based match.
void revealAchievement(String id)
Reveal a hidden achievement to the currently signed in player.
void revealAchievementImmediate(OnAchievementUpdatedListener listener, String id)
Reveal a hidden achievement to the currently signed in player.
int sendReliableRealTimeMessage(RealTimeReliableMessageSentListener listener, byte[] messageData, String roomId, String recipientParticipantId)
Send a message to a participant in a real-time room reliably.
int sendUnreliableRealTimeMessage(byte[] messageData, String roomId, List<String> recipientParticipantIds)
Send a message to one or more participants in a real-time room.
int sendUnreliableRealTimeMessage(byte[] messageData, String roomId, String recipientParticipantId)
Send a message to a participant in a real-time room.
int sendUnreliableRealTimeMessageToAll(byte[] messageData, String roomId)
Send a message to all participants in a real-time room.
void setAchievementSteps(String id, int numSteps)
Set an achievement to have at least the given number of steps completed.
void setAchievementStepsImmediate(OnAchievementUpdatedListener listener, String id, int numSteps)
Set an achievement to have at least the given number of steps completed.
void setGravityForPopups(int gravity)
Specifies the part of the screen at which games service popups (for example, "welcome back" or "achievement unlocked" popups) will be displayed using gravity.
void setViewForPopups(View gamesContentView)
Sets the View to use as a content view for popups.
void signOut(OnSignOutCompleteListener listener)
Asynchronously signs the current user out.
void signOut()
Asynchronously signs the current user out.
void submitScore(String leaderboardId, long score, String scoreTag)
Submit a score to a leaderboard for the currently signed in player.
void submitScore(String leaderboardId, long score)
Submit a score to a leaderboard for the currently signed in player.
void submitScoreImmediate(OnScoreSubmittedListener listener, String leaderboardId, long score, String scoreTag)
Submit a score to a leaderboard for the currently signed in player.
void submitScoreImmediate(OnScoreSubmittedListener listener, String leaderboardId, long score)
Submit a score to a leaderboard for the currently signed in player.
void takeTurn(OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, String pendingParticipantId)
Update a match with new turn data.
void takeTurn(OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, String pendingParticipantId, ParticipantResult... results)
Update a match with new turn data.
void takeTurn(OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, String pendingParticipantId, List<ParticipantResult> results)
Update a match with new turn data.
void unlockAchievement(String id)
Unlock an achievement for the currently signed in player.
void unlockAchievementImmediate(OnAchievementUpdatedListener listener, String id)
Unlock an achievement for the currently signed in player.
void unregisterConnectionCallbacks(GooglePlayServicesClient.ConnectionCallbacks listener)
Removes a connection listener from this GooglePlayServicesClient.
void unregisterConnectionFailedListener(GooglePlayServicesClient.OnConnectionFailedListener listener)
Removes a connection failed listener from the GooglePlayServicesClient.
void unregisterInvitationListener()
Unregisters this client's invitation listener, if any.
void unregisterMatchUpdateListener()
Unregisters this client's match update listener, if any.
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.google.android.gms.common.GooglePlayServicesClient

Constants

public static final String EXTRA_EXCLUSIVE_BIT_MASK

Used to bundle the exclusive bit mask of the player for auto-match criteria.

Constant Value: "exclusive_bit_mask"

public static final String EXTRA_INVITATION

Used to return an Invitation. Retrieve with getParcelableExtra(String) or getParcelable(String).

Constant Value: "invitation"

public static final String EXTRA_MAX_AUTOMATCH_PLAYERS

Used to return the maximum number of players that should be added to a room by auto-matching. Retrieve with getIntExtra(String, int).

Constant Value: "max_automatch_players"

public static final String EXTRA_MIN_AUTOMATCH_PLAYERS

Used to return the minimum number of players that should be added to a room by auto-matching. Retrieve with getIntExtra(String, int).

Constant Value: "min_automatch_players"

public static final String EXTRA_PLAYERS

Used to return a list of player IDs. Retrieve with getStringArrayListExtra(String).

Constant Value: "players"

public static final String EXTRA_PLAYER_SEARCH_RESULTS

Used by the Player Search UI to return a list of parceled Player objects. Retrieve with getParcelableArrayListExtra(String).

Constant Value: "player_search_results"

public static final String EXTRA_ROOM

Used to return a Room. Retrieve with getParcelableExtra(String).

Constant Value: "room"

public static final String EXTRA_TURN_BASED_MATCH

Constant Value: "turn_based_match"

public static final int MAX_RELIABLE_MESSAGE_LEN

This gives the maximum message size supported via the sendReliableRealTimeMessage(RealTimeReliableMessageSentListener, byte[], String, String) methods (excluding protocol headers).

Constant Value: 1400 (0x00000578)

public static final int MAX_UNRELIABLE_MESSAGE_LEN

This gives the maximum (unfragmented) message size supported via the sendUnreliableRealTimeMessage(byte[], String, String) methods (excluding protocol headers).

Constant Value: 1168 (0x00000490)

public static final int NOTIFICATION_TYPES_ALL

Notification types for any notification.

Constant Value: -1 (0xffffffff)

public static final int NOTIFICATION_TYPES_MULTIPLAYER

Notification types for multiplayer notifications.

Constant Value: 3 (0x00000003)

public static final int NOTIFICATION_TYPE_INVITATION

Notification type for invites to multiplayer games.

Constant Value: 1 (0x00000001)

public static final int NOTIFICATION_TYPE_MATCH_UPDATE

Notification type for updates to match information.

Constant Value: 2 (0x00000002)

public static final int STATUS_ACHIEVEMENT_NOT_INCREMENTAL

Indicates that the call to increment achievement failed since the achievement is not an incremental achievement.

Constant Value: 3002 (0x00000bba)

public static final int STATUS_ACHIEVEMENT_UNKNOWN

Could not find the achievement, so the operation to update the achievement failed.

Constant Value: 3001 (0x00000bb9)

public static final int STATUS_ACHIEVEMENT_UNLOCKED

Indicates that the incremental achievement was also unlocked when the call was made to increment the achievement.

Constant Value: 3003 (0x00000bbb)

public static final int STATUS_ACHIEVEMENT_UNLOCK_FAILURE

An incremental achievement cannot be unlocked directly, so the call to unlock achievement failed.

Constant Value: 3000 (0x00000bb8)

public static final int STATUS_APP_MISCONFIGURED

The developer has misconfigured their application in some way. The logs will contain more data about the error and the appropriate resolution.

Constant Value: 8 (0x00000008)

public static final int STATUS_CLIENT_RECONNECT_REQUIRED

The GamesClient is in an inconsistent state and must reconnect to the service to resolve the issue. Further calls to the service using the current connection are unlikely to succeed.

Constant Value: 2 (0x00000002)

public static final int STATUS_GAME_NOT_FOUND

The specified game ID was not recognized by the server.

Constant Value: 9 (0x00000009)

public static final int STATUS_INTERNAL_ERROR

An unspecified error occurred; no more specific information is available. The device logs may provide additional data.

Constant Value: 1 (0x00000001)

public static final int STATUS_INVALID_REAL_TIME_ROOM_ID

Constant indicating that the real-time room ID provided to the operation was not valid, or does not correspond to the currently active real-time room.

Constant Value: 7002 (0x00001b5a)

public static final int STATUS_LICENSE_CHECK_FAILED

The game is not licensed to the user. Further calls will return the same code.

Constant Value: 7 (0x00000007)

public static final int STATUS_MATCH_ERROR_ALREADY_REMATCHED

The specified match has already had a rematch created. Only one rematch may be created for any initial match.

Constant Value: 6505 (0x00001969)

public static final int STATUS_MATCH_ERROR_INACTIVE_MATCH

The match is not currently active. This action cannot be performed on an inactive match.

Constant Value: 6501 (0x00001965)

public static final int STATUS_MATCH_ERROR_INVALID_MATCH_RESULTS

The match results provided in this API call are invalid. This covers cases of duplicate results, results for players who are not in the match, etc.

Constant Value: 6504 (0x00001968)

public static final int STATUS_MATCH_ERROR_INVALID_MATCH_STATE

The match is not in the correct state to perform the specified action.

Constant Value: 6502 (0x00001966)

public static final int STATUS_MATCH_ERROR_INVALID_PARTICIPANT_STATE

One or more participants in this match are not in valid states. This could occur if a specified participant is not actually a participant of the match, or is invalid, or is in an incorrect state to make the API call. Check the logs for more detailed information.

Constant Value: 6500 (0x00001964)

public static final int STATUS_MATCH_ERROR_LOCALLY_MODIFIED

The specified match has already been modified locally. This operation cannot be performed until the match has been sent to the server.

Constant Value: 6507 (0x0000196b)

public static final int STATUS_MATCH_ERROR_OUT_OF_DATE_VERSION

The match data is out of date. Someone else has modified the data on the server, so the request could not be completed safely.

Constant Value: 6503 (0x00001967)

public static final int STATUS_MATCH_NOT_FOUND

The specified match cannot be found. The provided match ID does not correspond to any known match.

Constant Value: 6506 (0x0000196a)

public static final int STATUS_MULTIPLAYER_DISABLED

This game does not support multiplayer. This could occur if the linked app is not configured appropriately in the developer console.

Constant Value: 6003 (0x00001773)

public static final int STATUS_MULTIPLAYER_ERROR_CREATION_NOT_ALLOWED

The user is not allowed to create a new multiplayer game at this time. This could occur if the user has too many outstanding invitations already.

Constant Value: 6000 (0x00001770)

public static final int STATUS_MULTIPLAYER_ERROR_INVALID_MULTIPLAYER_TYPE

The match is not the right type to perform this action on. For example, this error will be returned when trying to take a turn in a real-time match.

Constant Value: 6002 (0x00001772)

public static final int STATUS_MULTIPLAYER_ERROR_INVALID_OPERATION

This multiplayer operation is not valid, and the server rejected it. Check the logs for more information.

Constant Value: 6004 (0x00001774)

public static final int STATUS_MULTIPLAYER_ERROR_NOT_TRUSTED_TESTER

The user attempted to invite another user who was not authorized to see the game. This can occur if a trusted tester invites a user who is not a trusted tester while the game is unpublished. In this case, the invitations will not be sent.

Constant Value: 6001 (0x00001771)

public static final int STATUS_NETWORK_ERROR_NO_DATA

A network error occurred while attempting to retrieve fresh data, and no data was available locally.

Constant Value: 4 (0x00000004)

public static final int STATUS_NETWORK_ERROR_OPERATION_DEFERRED

A network error occurred while attempting to modify data, but the data was successfully modified locally and will be updated on the network the next time the device is able to sync.

Constant Value: 5 (0x00000005)

public static final int STATUS_NETWORK_ERROR_OPERATION_FAILED

A network error occurred while attempting to perform an operation that requires network access. The operation may be retried later.

Constant Value: 6 (0x00000006)

public static final int STATUS_NETWORK_ERROR_STALE_DATA

A network error occurred while attempting to retrieve fresh data, but some locally cached data was available. The data returned may be stale and/or incomplete.

Constant Value: 3 (0x00000003)

public static final int STATUS_OK

The operation was successful.

Constant Value: 0 (0x00000000)

public static final int STATUS_OPERATION_IN_FLIGHT

Trying to start a join/create operation while another is already in flight.

Constant Value: 7007 (0x00001b5f)

public static final int STATUS_PARTICIPANT_NOT_CONNECTED

Constant indicating that the ID of the participant provided by the user is not currently connected to the client in the real-time room.

Constant Value: 7003 (0x00001b5b)

public static final int STATUS_REAL_TIME_CONNECTION_FAILED

Failed to initialize the network connection for a real-time room.

Constant Value: 7000 (0x00001b58)

public static final int STATUS_REAL_TIME_INACTIVE_ROOM

The room is not currently active. This action cannot be performed on an inactive room.

Constant Value: 7005 (0x00001b5d)

public static final int STATUS_REAL_TIME_MESSAGE_FAILED

Status code returned from the sendUnreliableRealTimeMessage(byte[], String, String) and sendReliableRealTimeMessage(RealTimeReliableMessageSentListener, byte[], String, String) methods when the message send operation failed due to an immediate error.

Constant Value: -1 (0xffffffff)

public static final int STATUS_REAL_TIME_MESSAGE_SEND_FAILED

Failed to send message to the peer participant for a real-time room.

Constant Value: 7001 (0x00001b59)

public static final int STATUS_REAL_TIME_ROOM_NOT_JOINED

Failed to send message to the peer participant for a real-time room, since the user has not joined the room.

Constant Value: 7004 (0x00001b5c)

Public Methods

public void acceptTurnBasedInvitation (OnTurnBasedMatchInitiatedListener listener, String invitationId)

Accept an invitation for a turn-based match.

Parameters
listener The listener that is called when the match has been accepted. The listener is called on the main thread.
invitationId The ID of the invitation to be accepted.

public void cancelTurnBasedMatch (String matchId)

Cancels a turn-based match. Once this call succeeds, the match will be removed from local storage. Note that this will cancel the match completely, forcing it to end for all players involved. See leaveTurnBasedMatch(OnTurnBasedMatchLeftListener, String) for a different alternative.

Parameters
matchId The ID of the match to cancel.

public void cancelTurnBasedMatch (OnTurnBasedMatchCanceledListener listener, String matchId)

Cancels a turn-based match. Once this call succeeds, the match will be removed from local storage. Note that this will cancel the match completely, forcing it to end for all players involved. See leaveTurnBasedMatch(OnTurnBasedMatchLeftListener, String) for a different alternative.

Parameters
listener The listener that is called after the match has been canceled. The listener is called on the main thread.
matchId The ID of the match to cancel.

public void clearAllNotifications ()

Clear all notifications for the current game and signed-in player.

public void clearNotifications (int notificationTypes)

Clear the notifications of the specified type for the current game and signed-in player. This should be a mask comprised of values from the constants NOTIFICATION_TYPE_INVITATION, NOTIFICATION_TYPES_MULTIPLAYER, and NOTIFICATION_TYPES_ALL.

Parameters
notificationTypes Mask of notification types to clear.

public void connect ()

Connect to the games service.

This method should be called from onStart() or onStart().

This method will return immediately, and onConnected(Bundle) will be called if the connection is successful.

The Bundle provided to onConnected may be null. If not null, it can contain the following keys:

See Also

public void createRoom (RoomConfig config)

Create a real-time room for the current game. The lifetime of the current game's connection to the room is bound to this GamesClient's lifecycle. When the client disconnects, the player will leave the room and any peer-to-peer connections for this player will be torn down. The result is delivered by the callback onRoomCreated(int, Room) to the given RoomUpdateListener in the RoomConfig. The listener is called on the main thread.

Parameters
config The real-time room configuration.

public void createTurnBasedMatch (OnTurnBasedMatchInitiatedListener listener, TurnBasedMatchConfig config)

Create a turn-based match for the current game.

Parameters
listener The listener that is called when the match has been created. The listener is called on the main thread.
config The configuration parameters for the match to create.

public void declineRoomInvitation (String invitationId)

Decline an invitation for a real-time room.

Parameters
invitationId The ID of the invitation to decline.

public void declineTurnBasedInvitation (String invitationId)

Decline an invitation for a turn-based match.

Parameters
invitationId The ID of the invitation to decline.

public void disconnect ()

Closes the connection to Google Play services. No calls can be made on this object after calling this method.

public void dismissRoomInvitation (String invitationId)

Dismiss an invitation to a real-time room. Dismissing an invitation will not change the state of the room for the other participants.

Parameters
invitationId The ID of the invitation to dismiss.

public void dismissTurnBasedInvitation (String invitationId)

Dismiss an invitation to a turn-based match. Dismissing an invitation will not change the state of the match for the other participants.

Parameters
invitationId The ID of the invitation to dismiss.

public void dismissTurnBasedMatch (String matchId)

Delete a match from the server and local storage. Dismissing a match will not change the state of the match for the other participants, but dismissed matches will never be shown to the dismissing player again.

Parameters
matchId The ID of the match to dismiss.

public void finishTurnBasedMatch (OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, List<ParticipantResult> results)

Mark a match as finished. This should be called when the match is over and all participants have results to be reported (if appropriate). Note that the last client to update a match is responsible for calling finish on that match.

Parameters
listener The listener that is called when the match has been updated. The listener is called on the main thread.
matchId ID of the match to finish.
matchData Data representing the new state of the match after this update. Limited to a maximum of getMaxTurnBasedMatchDataSize() bytes.
results List of ParticipantResult objects for this match. The client which calls finishMatch is responsible for reporting the results for all appropriate participants in the match. Not every participant is required to have a result, but providing results for participants who are not in the match is an error.

public void finishTurnBasedMatch (OnTurnBasedMatchUpdatedListener listener, String matchId)

Indicate that a participant is finished with a match. This will not change the data of the match, but it will transition the match into state MATCH_STATUS_COMPLETE if the match is not already in that state. This method is most commonly used to report that a participant has finished any post-processing steps the game might have and has seen their results in the match.

Parameters
listener The listener that is called when the match has been updated. The listener is called on the main thread.
matchId ID of the match to finish.

public void finishTurnBasedMatch (OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, ParticipantResult... results)

Mark a match as finished. This should be called when the match is over and all participants have results to be reported (if appropriate). Note that the last client to update a match is responsible for calling finish on that match.

On the last turn of the match, the client should call this method instead of takeTurn(OnTurnBasedMatchUpdatedListener, String, byte[], String).

Parameters
listener The listener that is called when the match has been updated. The listener is called on the main thread.
matchId ID of the match to finish.
matchData Data representing the new state of the match after this update. Limited to a maximum of getMaxTurnBasedMatchDataSize() bytes.
results List of ParticipantResult objects for this match. The client which calls finishMatch is responsible for reporting the results for all appropriate participants in the match. Not every participant is required to have a result, but providing results for participants who are not in the match is an error.

public Intent getAchievementsIntent ()

Gets an intent to show the list of achievements for a game. Note that this must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

A RESULT_RECONNECT_REQUIRED may be returned as the resultCode in onActivityResult(int, int, Intent) if the GamesClient ends up in an inconsistent state.

Returns
  • An Intent that can be started to view the currently signed in player's achievements.

public Intent getAllLeaderboardsIntent ()

Gets an intent to show the list of leaderboards for a game. Note that this must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

A RESULT_RECONNECT_REQUIRED may be returned as the resultCode in onActivityResult(int, int, Intent) if the GamesClient ends up in an inconsistent state.

Returns
  • An Intent that can be started to view the list of leaderboards for a game.

public String getAppId ()

Get the application ID linked to this GamesClient instance.

Returns
  • The application ID linked to this GamesClient instance.

public String getCurrentAccountName ()

Get the name of the currently selected account. This is the account the user has chosen to use for Google Play Games.

Note that the GamesClient must be connected to call this API, and your app must have <uses-permission android:name="android.permission.GET_ACCOUNTS" /> declared in your manifest in order to use this method.

Returns
  • Account name for the currently selected account. May be null if an error occurred while communicating with the games service.
Throws
SecurityException If your app doesn't have the GET_ACCOUNTS permission.

public Game getCurrentGame ()

Returns
  • Game metadata for the current game. May be null if the metadata is not available locally.

public Player getCurrentPlayer ()

Returns
  • Player representing the currently signed in player. May be null if an error occurred while communicating with the games service.

public String getCurrentPlayerId ()

Returns
  • The player ID for the currently signed in player. May be null if an error occurred while communicating with the games service.

public Intent getInvitationInboxIntent ()

Returns an intent that will let the user see and manage any outstanding invitations. 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, the result will be RESULT_CANCELED. If the user selected an invitation to accept, the result will be RESULT_OK and the data intent will contain the selected invitation as a parcelable extra in EXTRA_INVITATION.

Returns
  • An Intent that can be started to view the invitation inbox UI.

public Intent getLeaderboardIntent (String leaderboardId)

Gets an intent to show a leaderboard for a game. Note that this must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

A RESULT_RECONNECT_REQUIRED may be returned as the resultCode in onActivityResult(int, int, Intent) if the GamesClient ends up in an inconsistent state.

Parameters
leaderboardId The ID of the leaderboard to view.
Returns
  • An Intent that can be started to view the specified leaderboard.

public Intent getMatchInboxIntent ()

Returns an intent that will let the user see and manage any outstanding invitations and matches. 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 the result will be RESULT_CANCELED. If the user selected an invitation or a match to accept, the result will be RESULT_OK and the data intent will contain the selected invitation/match as a parcelable extra in the extras. Based on the type of the match, the result will include either EXTRA_TURN_BASED_MATCH or EXTRA_INVITATION.

Returns
  • An Intent that can be started to view the match inbox.

public int getMaxTurnBasedMatchDataSize ()

Gets the maximum data size per match in bytes. Guaranteed to be at least 128 KB. May increase in the future.

If the service cannot be reached for some reason, this will return STATUS_CLIENT_RECONNECT_REQUIRED. In this case, no further operations should be attempted until after the client has reconnected.

Returns
  • The maximum data size per match in bytes.

public Intent getPlayerSearchIntent ()

Returns an intent that will display a screen where the user can search for people on Google+. Note that this must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

If the user canceled, the result will be RESULT_CANCELED. If the user selected any players from the search results list, the result will be RESULT_OK, and the data intent will contain a list of parceled Player objects in EXTRA_PLAYER_SEARCH_RESULTS.

Note that the current Player Search UI only allows a single selection, so the returned list of parceled Player objects will currently contain at most one Player. The Player Search UI may allow multiple selections in a future release, though.

Returns
  • An Intent that can be started to display the player selector.

public RealTimeSocket getRealTimeSocketForParticipant (String roomId, String participantId)

Returns a RealTimeSocket for carrying network traffic to the given peer. Creates a new socket if one does not exist (or if an existing socket gets disconnected). Requires an active real-time room and players being available. Throws an IllegalArgumentException if participantId is not a valid participant or belongs to the current player.

Parameters
roomId ID of the room for which the socket is being bound.
participantId The ID of the participant to whom this socket is bound
Returns
  • An instance of a LocalSocket, or null on error.

public Intent getRealTimeWaitingRoomIntent (Room room, int minParticipantsToStart)

Returns an intent that will display a "waiting room" screen that shows the progress of participants joining a real-time multiplayer room. Note that this must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

If the necessary number of peers have connected and it's now OK to start the game, or if the user explicitly asked to start the game now, the activity result will be RESULT_OK. If the user bailed out of the waiting room screen without taking any action, the result will be RESULT_CANCELED. If the user explicitly chose to leave the room, the result will be RESULT_LEFT_ROOM.

Regardless of what the result code was, the waiting room activity will return a data intent containing a Room object in EXTRA_ROOM that represents the current state of the Room that you originally passed as a parameter here.

If desired, the waiting room can allow the user to start playing the game even before the room is fully connected. This is controlled by the minParticipantsToStart parameter: if at least that many participants (including the current player) are connected to the room, a "Start playing" menu item will become enabled in the waiting room UI. Setting minParticipantsToStart to 0 means that "Start playing" will always be available, and a value of MAX_VALUE will disable the item completely. Note: if you do allow the user to start early, you'll need to handle that situation by explicitly telling the other connected peers that the game is now starting; see the developer documentation for more details.

Finally, note that the waiting room itself will never explicitly take any action to change the state of the room or its participants. So if the activity result is RESULT_LEFT_ROOM, it's the caller's responsibility to actually leave the room. Or if the result is RESULT_CANCELED, it's the responsibility of the caller to double-check the current state of the Room and decide whether to start the game, keep waiting, or do something else. But note that while the waiting room is active, the state of the Room will change as participants accept or decline invitations, and the number of participants may even change as auto-match players get added.

Parameters
room The Room object to be displayed.
minParticipantsToStart the minimum number of participants that must be connected to the room (including the current player) for the "Start playing" menu item to become enabled.
Returns
  • An Intent that can be started to display the waiting room screen.

public Intent getSelectPlayersIntent (int minPlayers, int maxPlayers)

Returns an intent that will let the user select players to send an invitation to. Note that this must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

The number of players passed in should be the desired number of additional players to select, not including the current player. So, for a game that can handle between 2 and 4 players, minPlayers would be 1 and maxPlayers would be 3.

If the user canceled, the result will be RESULT_CANCELED. If the user selected players, the result will be RESULT_OK, and the data intent will contain the selected player IDs in EXTRA_PLAYERS and the minimum and maximum numbers of additional auto-match players in EXTRA_MIN_AUTOMATCH_PLAYERS and EXTRA_MAX_AUTOMATCH_PLAYERS respectively. The player IDs in EXTRA_PLAYERS will include only the other players selected, not the current player.

This method is the equivalent of calling getSelectPlayersIntent(int, int, boolean) with the allowAutomatch parameter set to true.

Parameters
minPlayers The minimum number of players to select (not including the current player).
maxPlayers The maximum number of players to select (not including the current player).
Returns
  • An Intent that can be started to display the player selector.

public Intent getSelectPlayersIntent (int minPlayers, int maxPlayers, boolean allowAutomatch)

Returns an intent that will let the user select players to send an invitation to. Note that this must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

The number of players passed in should be the desired number of additional players to select, not including the current player. So, for a game that can handle between 2 and 4 players, minPlayers would be 1 and maxPlayers would be 3.

If the user canceled, the result will be RESULT_CANCELED. If the user selected players, the result will be RESULT_OK, and the data intent will contain the selected player IDs in EXTRA_PLAYERS and the minimum and maximum numbers of additional auto-match players in EXTRA_MIN_AUTOMATCH_PLAYERS and EXTRA_MAX_AUTOMATCH_PLAYERS respectively. The player IDs in EXTRA_PLAYERS will include only the other players selected, not the current player.

If the allowAutomatch parameter is set to false, the UI will not display an option for selecting automatch players. Set this to false if your game does not support automatching.

Parameters
minPlayers The minimum number of players to select (not including the current player).
maxPlayers The maximum number of players to select (not including the current player).
allowAutomatch Whether or not to display an option for selecting automatch players.
Returns
  • An Intent that can be started to display the player selector.

public Intent getSettingsIntent ()

Gets an intent to show the Settings screen that allows the user to configure GamesClient-related features for the current game. Note that this must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

A RESULT_RECONNECT_REQUIRED may be returned as the resultCode in onActivityResult(int, int, Intent) if the GamesClient ends up in an inconsistent state.

Most applications will not need to call this directly, since the Settings UI is already reachable from most other GamesClient UI screens (achievements, leaderboards, etc.) via a menu item.

Returns
  • An Intent that can be started to view the GamesClient Settings UI.

public void getTurnBasedMatch (OnTurnBasedMatchLoadedListener listener, String matchId)

Load a specified turn-based match.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
matchId The ID of the match to retreive.

public void incrementAchievement (String id, int numSteps)

Increments an achievement by the given number of steps. The achievement must be an incremental achievement. Once an achievement reaches at least the maximum number of steps, it will be unlocked automatically. Any further increments will be ignored.

This is the fire-and-forget form of the API. Use this form if you don't need to know the status of the operation immediately. For most applications, this will be the preferred API to use, though note that the update may not be sent to the server until the next sync. See incrementAchievementImmediate(OnAchievementUpdatedListener, String, int) if you need the operation to attempt to communicate to the server immediately or need to have the status code delivered to your application.

Parameters
id The achievement ID to increment.
numSteps The number of steps to increment by. Must be greater than 0.

public void incrementAchievementImmediate (OnAchievementUpdatedListener listener, String id, int numSteps)

Increments an achievement by the given number of steps. The achievement must be an incremental achievement. Once an achievement reaches at least the maximum number of steps, it will be unlocked automatically. Any further increments will be ignored.

This form of the API will attempt to update the user's achievement on the server immediately, and will use the provided listener to inform the caller of the result of the operation.

The status code to indicate the success or failure of the operation is delivered to the given listener on the main thread. If disconnect() is called before the operation is completed, the status code will not be delivered.

Parameters
listener The listener that is called when the increment achievement is complete. The listener is called on the main thread.
id The ID of the achievement to increment.
numSteps The number of steps to increment by. Must be greater than 0.

public boolean isConnected ()

Checks if the client is currently connected to the service, so that requests to other methods will succeed. Applications should guard client actions caused by the user with a call to this method.

Returns
  • true if the client is connected to the service.

public boolean isConnecting ()

Checks if the client is attempting to connect to the service.

Returns
  • true if the client is attempting to connect to the service.

public boolean isConnectionCallbacksRegistered (GooglePlayServicesClient.ConnectionCallbacks listener)

Returns true if the specified listener is currently registered to receive connection events.

Parameters
listener The listener to check for.
Returns
  • true if the specified listener is currently registered to receive connection events.

public boolean isConnectionFailedListenerRegistered (GooglePlayServicesClient.OnConnectionFailedListener listener)

Returns true if the specified listener is currently registered to receive connection failed events.

Parameters
listener The listener to check for.
Returns
  • true if the specified listener is currently registered to receive connection failed events.

public void joinRoom (RoomConfig config)

Join a real-time room by accepting an invitation. The lifetime of the current game's connection to the room is bound to this GamesClient's lifecycle. When the client disconnects, the player will leave the room and any peer-to-peer connections for this player will be torn down. The result is delivered by the callback onJoinedRoom(int, Room) to the given RoomUpdateListener in the RoomConfig. The listener is called on the main thread.

Parameters
config The real-time room configuration.

public void leaveRoom (RoomUpdateListener listener, String roomId)

Leave the specified room. This will disconnect the player from the room, but allow other players to continue playing the game. The result is delivered by the callback onLeftRoom(int, String) to the given listener on the main thread.

After this method is called, you cannot perform any further actions on the room. You can create or join another room only after onLeftRoom(int, String) is received.

Parameters
listener The listener that is notified after the room has been left. The listener is called on the main thread.
roomId ID of the room to leave.

public void leaveTurnBasedMatch (OnTurnBasedMatchLeftListener listener, String matchId)

Leave the specified match when it is not the current player's turn. If this takes the match to fewer than two participants, the match will be canceled.

See leaveTurnBasedMatchDuringTurn(OnTurnBasedMatchLeftListener, String, String) for the form of the API to call during the current player's turn.

Parameters
listener The listener that is called after the match has been left. The listener is called on the main thread.
matchId ID of the match to leave.

public void leaveTurnBasedMatchDuringTurn (OnTurnBasedMatchLeftListener listener, String matchId, String pendingParticipantId)

Leave the specified match during the current player's turn. If this takes the match to fewer than two participants, the match will be canceled. The provided pendingParticipantId will be used to determine which participant should act next. If no pending participant is provided and the match has available auto-match slots, the match will wait for additional players to be found. If there are no auto-match slots available for this match, a pending participant ID is required.

See leaveTurnBasedMatch(OnTurnBasedMatchLeftListener, String) for the form of the API to call when it is not the current player's turn.

Parameters
listener The listener that is called after the match has been left. The listener is called on the main thread.
matchId ID of the match to leave.
pendingParticipantId ID of the participant who will be set to pending after this update succeeds, or null to wait for additional automatched players (if possible).

public void loadAchievements (OnAchievementsLoadedListener listener, boolean forceReload)

Asynchronously load achievement data for the currently signed in player.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
forceReload 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.

public void loadCurrentPlayerLeaderboardScore (OnPlayerLeaderboardScoreLoadedListener listener, String leaderboardId, int span, int leaderboardCollection)

Asynchronously load the currently signed in player's score for a given leaderboard.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
leaderboardId ID of the leaderboard to load the score from.
span Time span to retrieve data for. Valid values are TIME_SPAN_DAILY, TIME_SPAN_WEEKLY, or TIME_SPAN_ALL_TIME.
leaderboardCollection The leaderboard collection to retrieve scores for. Valid values are either COLLECTION_PUBLIC or COLLECTION_SOCIAL.

public void loadGame (OnGamesLoadedListener listener)

Load the details for the current game.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.

public void loadInvitablePlayers (OnPlayersLoadedListener listener, int pageSize, boolean forceReload)

Load the initial page of players the currently signed-in player can invite to a multiplayer game, sorted alphabetically by name.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
pageSize The number of entries to request for this initial page. Note that if cached data already exists, the returned buffer may contain more than this size, but it is guaranteed to contain at least this many if the collection contains enough records. This must be a value between 1 and 25.
forceReload 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.

public void loadInvitations (OnInvitationsLoadedListener listener)

Asynchronously load the list of invitations for the current game.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.

public void loadLeaderboardMetadata (OnLeaderboardMetadataLoadedListener listener, boolean forceReload)

Asynchronously load the list of leaderboard metadata for this game.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
forceReload 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.

public void loadLeaderboardMetadata (OnLeaderboardMetadataLoadedListener listener, String leaderboardId, boolean forceReload)

Asynchronously load a specific leaderboard's metadata for this game.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
leaderboardId ID of the leaderboard to load metadata for.
forceReload 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.

public void loadMoreInvitablePlayers (OnPlayersLoadedListener listener, int pageSize)

Asynchronously loads an additional page of invitable players. A new player buffer will be delivered that includes an extra page of results.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
pageSize The number of additional entries to request. This must be a value between 1 and 25.

public void loadMoreScores (OnLeaderboardScoresLoadedListener listener, LeaderboardScoreBuffer buffer, int maxResults, int pageDirection)

Asynchronously loads an additional page of score data for the given score buffer. A new score buffer will be delivered that replaces the given buffer.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
buffer The existing buffer that will be expanded. The buffer is allowed to be closed prior to being passed in to this method.
maxResults The maximum number of scores to fetch per page. Must be between 1 and 25.
pageDirection The direction to expand the buffer. Values are defined in PageDirection.

public void loadPlayer (OnPlayersLoadedListener listener, String playerId)

Asynchronously loads the profile for the requested player ID.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
playerId The player ID to get full profile data for.

public void loadPlayerCenteredScores (OnLeaderboardScoresLoadedListener listener, String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)

Asynchronously load the player-centered page of scores for a given leaderboard. If the player does not have a score on this leaderboard, this call will return the top page instead.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
leaderboardId ID of the leaderboard.
span Time span to retrieve data for. Valid values are TIME_SPAN_DAILY, TIME_SPAN_WEEKLY, or TIME_SPAN_ALL_TIME.
leaderboardCollection The leaderboard collection to retrieve scores for. Valid values are either COLLECTION_PUBLIC or COLLECTION_SOCIAL.
maxResults The maximum number of scores to fetch per page. Must be between 1 and 25.
forceReload 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.

public void loadPlayerCenteredScores (OnLeaderboardScoresLoadedListener listener, String leaderboardId, int span, int leaderboardCollection, int maxResults)

Asynchronously load the player-centered page of scores for a given leaderboard. If the player does not have a score on this leaderboard, this call will return the top page instead.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
leaderboardId ID of the leaderboard.
span Time span to retrieve data for. Valid values are TIME_SPAN_DAILY, TIME_SPAN_WEEKLY, or TIME_SPAN_ALL_TIME.
leaderboardCollection The leaderboard collection to retrieve scores for. Valid values are either COLLECTION_PUBLIC or COLLECTION_SOCIAL.
maxResults The maximum number of scores to fetch per page. Must be between 1 and 25.

public void loadTopScores (OnLeaderboardScoresLoadedListener listener, String leaderboardId, int span, int leaderboardCollection, int maxResults)

Asynchronously load the top page of scores for a given leaderboard.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
leaderboardId ID of the leaderboard.
span Time span to retrieve data for. Valid values are TIME_SPAN_DAILY, TIME_SPAN_WEEKLY, or TIME_SPAN_ALL_TIME.
leaderboardCollection The leaderboard collection to retrieve scores for. Valid values are either COLLECTION_PUBLIC or COLLECTION_SOCIAL.
maxResults The maximum number of scores to fetch per page. Must be between 1 and 25.

public void loadTopScores (OnLeaderboardScoresLoadedListener listener, String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)

Asynchronously load the top page of scores for a given leaderboard.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener the listener that is called when the load is complete. The listener is called on the main thread.
leaderboardId ID of the leaderboard.
span Time span to retrieve data for. Valid values are TIME_SPAN_DAILY, TIME_SPAN_WEEKLY, or TIME_SPAN_ALL_TIME.
leaderboardCollection The leaderboard collection to retrieve scores for. Valid values are either COLLECTION_PUBLIC or COLLECTION_SOCIAL.
maxResults The maximum number of scores to fetch per page. Must be between 1 and 25.
forceReload 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.

public void loadTurnBasedMatches (OnTurnBasedMatchesLoadedListener listener, int... matchTurnStatuses)

Asynchronously load turn-based matches for the current game. Matches with any specified turn status codes will be returned to the provided listener.

Valid turn status values are MATCH_TURN_STATUS_INVITED, MATCH_TURN_STATUS_MY_TURN, MATCH_TURN_STATUS_THEIR_TURN, or MATCH_TURN_STATUS_COMPLETE. Note that if your game implements both turn-based and real-time multiplayer, requesting MATCH_TURN_STATUS_INVITED will return invitations for both turn-based matches and real-time matches.

The result is delivered to the given listener on the main thread. If disconnect() is called before the result is ready it will not be delivered.

Parameters
listener The listener that is called when the load is complete. The listener is called on the main thread.
matchTurnStatuses List of turn statuses to request.

public void reconnect ()

Closes the current connection to Google Play services and creates a new connection.

This method closes the current connection then returns immediately and reconnects to the service in the background.

As with a regular connect() call, a call to this method will be followed by either onConnected(Bundle) if the connection is successful or onConnectionFailed(ConnectionResult) on a failure.

public void registerConnectionCallbacks (GooglePlayServicesClient.ConnectionCallbacks listener)

Registers a listener to receive connection events from this GooglePlayServicesClient. If the service is already connected, the listener's onConnected(Bundle) method will be called immediately. Applications should balance calls to this method with calls to unregisterConnectionCallbacks(ConnectionCallbacks) to avoid leaking resources.

If the specified listener is already registered to receive connection events, this method will not add a duplicate entry for the same listener, but will still call the listener's onConnected(Bundle) method if currently connected.

Note that the order of messages received here may not be stable, so clients should not rely on the order that multiple listeners receive events in.

Parameters
listener the listener where the results of the asynchronous connect() call are delivered.

public void registerConnectionFailedListener (GooglePlayServicesClient.OnConnectionFailedListener listener)

Registers a listener to receive connection failed events from this GooglePlayServicesClient. Unlike registerConnectionCallbacks(GooglePlayServicesClient.ConnectionCallbacks), if the service is not already connected, the listener's onConnectionFailed(ConnectionResult) method will not be called immediately. Applications should balance calls to this method with calls to unregisterConnectionFailedListener(OnConnectionFailedListener) to avoid leaking resources.

If the specified listener is already registered to receive connection failed events, this method will not add a duplicate entry for the same listener.

Note that the order of messages received here may not be stable, so clients should not rely on the order that multiple listeners receive events in.

Parameters
listener the listener where the results of the asynchronous connect() call are delivered.

public void registerInvitationListener (OnInvitationReceivedListener listener)

Register a listener to intercept incoming invitations for the currently signed-in user. If a listener is registered by this method, the incoming invitation will not generate a status bar notification as long as this client remains connected.

Note that only one invitation listener may be active at a time. Calling this method while another invitation listener was previously registered will replace the original listener with the new one.

Parameters
listener The listener that is called when a new invitation is received. The listener is called on the main thread.

public void registerMatchUpdateListener (OnTurnBasedMatchUpdateReceivedListener listener)

Register a listener to intercept incoming match updates for the currently signed-in user. If a listener is registered by this method, the incoming match update will not generate a status bar notification as long as this client remains connected.

Note that only one match update listener may be active at a time. Calling this method while another match update listener was previously registered will replace the original listener with the new one.

Parameters
listener The listener that is called when a match update is received. The listener is called on the main thread.

public void rematchTurnBasedMatch (OnTurnBasedMatchInitiatedListener listener, String matchId)

Create a rematch of a previously completed turn-based match. The new match will have the same participants as the previous match. Note that only one rematch may be created from any single completed match.

Parameters
listener The listener that is called when the match has been created. The listener is called on the main thread.
matchId The ID of the previous match to re-create.

public void revealAchievement (String id)

Reveal a hidden achievement to the currently signed in player. If the achievement has already been unlocked, this will have no effect.

This is the fire-and-forget form of the API. Use this form if you don't need to know the status of the operation immediately. For most applications, this will be the preferred API to use, though note that the update may not be sent to the server until the next sync. See revealAchievementImmediate(OnAchievementUpdatedListener, String) if you need the operation to attempt to communicate to the server immediately or need to have the status code delivered to your application.

Parameters
id The achievement ID to reveal

public void revealAchievementImmediate (OnAchievementUpdatedListener listener, String id)

Reveal a hidden achievement to the currently signed in player. If the achievement is already visible, this will have no effect.

This form of the API will attempt to update the user's achievement on the server immediately, and will use the provided listener to inform the caller of the result of the operation.

The status code to indicate the success or failure of the operation is delivered to the given listener on the main thread. If disconnect() is called before the operation is completed, the status code will not be delivered.

Parameters
listener The listener that is called when the reveal achievement is complete. The listener is called on the main thread.
id The ID of the achievement to reveal

public int sendReliableRealTimeMessage (RealTimeReliableMessageSentListener listener, byte[] messageData, String roomId, String recipientParticipantId)

Send a message to a participant in a real-time room reliably. The caller will receive a callback to report the status of the send message operation. Throws an IllegalArgumentException if recipientParticipantId is not a valid participant or belongs to the current player. The maximum message size supported is MAX_RELIABLE_MESSAGE_LEN bytes.

Parameters
listener The listener that is notified when the message has been sent.
messageData The message to be sent. Should be at most MAX_RELIABLE_MESSAGE_LEN bytes.
roomId ID of the room for which the message is being sent.
recipientParticipantId The participant ID to send the message to.
Returns

public int sendUnreliableRealTimeMessage (byte[] messageData, String roomId, List<String> recipientParticipantIds)

Send a message to one or more participants in a real-time room. The message delivery is not reliable and will not report status after completion. Throws an IllegalArgumentException if any participants in recipientParticipantIds are not valid or belong to the current player. The maximum message size supported is MAX_UNRELIABLE_MESSAGE_LEN bytes.

Parameters
messageData The message to be sent. Should be at most MAX_UNRELIABLE_MESSAGE_LEN bytes.
roomId ID of the room for which the message is being sent.
recipientParticipantIds One or more participant IDs to send the message to.
Returns

public int sendUnreliableRealTimeMessage (byte[] messageData, String roomId, String recipientParticipantId)

Send a message to a participant in a real-time room. The message delivery is not reliable and will not report status after completion. Throws an IllegalArgumentException if recipientParticipantId is not a valid participant or belongs to the current player. The maximum message size supported is MAX_UNRELIABLE_MESSAGE_LEN bytes.

Parameters
messageData The message to be sent. Should be at most MAX_UNRELIABLE_MESSAGE_LEN bytes.
roomId ID of the room for which the message is being sent.
recipientParticipantId The participant ID to send the message to.
Returns

public int sendUnreliableRealTimeMessageToAll (byte[] messageData, String roomId)

Send a message to all participants in a real-time room. The message delivery is not reliable and will not report status after completion. The maximum message size supported is MAX_UNRELIABLE_MESSAGE_LEN bytes.

Parameters
messageData The message to be sent. Should be at most MAX_UNRELIABLE_MESSAGE_LEN bytes.
roomId ID of the room for which the message is being sent.
Returns

public void setAchievementSteps (String id, int numSteps)

Set an achievement to have at least the given number of steps completed. Calling this method while the achievement already has more steps than the provided value is a no-op. Once the achievement reaches the maximum number of steps, the achievement will automatically be unlocked, and any further mutation operations will be ignored.

This is the fire-and-forget form of the API. Use this form if you don't need to know the status of the operation immediately. For most applications, this will be the preferred API to use, though note that the update may not be sent to the server until the next sync. See setAchievementStepsImmediate(OnAchievementUpdatedListener, String, int) if you need the operation to attempt to communicate to the server immediately or need to have the status code delivered to your application.

Parameters
id The ID of the achievement to modify.
numSteps The number of steps to set the achievement to. Must be greater than 0.

public void setAchievementStepsImmediate (OnAchievementUpdatedListener listener, String id, int numSteps)

Set an achievement to have at least the given number of steps completed. Calling this method while the achievement already has more steps than the provided value is a no-op. Once the achievement reaches the maximum number of steps, the achievement will automatically be unlocked, and any further mutation operations will be ignored.

This form of the API will attempt to update the user's achievement on the server immediately, and will use the provided listener to inform the caller of the result of the operation.

The status code to indicate the success or failure of the operation is delivered to the given listener on the main thread. If disconnect() is called before the operation is completed, the status code will not be delivered.

Parameters
listener The listener that is called when the set operation is complete. The listener is called on the main thread.
id The ID of the achievement to modify.
numSteps The number of steps to set the achievement to. Must be greater than 0.

public void setGravityForPopups (int gravity)

Specifies the part of the screen at which games service popups (for example, "welcome back" or "achievement unlocked" popups) will be displayed using gravity.

Default value is TOP|CENTER_HORIZONTAL.

Parameters
gravity The gravity which controls the placement of games service popups.

public void setViewForPopups (View gamesContentView)

Sets the View to use as a content view for popups.

Parameters
gamesContentView The view to use as a content view for popups. View cannot be null.

public void signOut (OnSignOutCompleteListener listener)

Asynchronously signs the current user out.

This call doesn't disconnect the GamesClient. As no user is signed in after this call is completed, subsequent calls to this client will very likely fail. You should either call disconnect() or finish your Activity after this call.

The listener is called when sign-out is complete. If disconnect() is called before sign-out is complete, the listener will not be called.

Parameters
listener The listener that is called when sign-out is complete. The listener is called on the main thread.

public void signOut ()

Asynchronously signs the current user out.

This call doesn't disconnect the GamesClient. As no user is signed in after this call is completed, subsequent calls to this client will very likely fail. You should either call disconnect() or finish your Activity after this call.

public void submitScore (String leaderboardId, long score, String scoreTag)

Submit a score to a leaderboard for the currently signed in player. The score is ignored if it is worse (as defined by the leaderboard configuration) than a previously submitted score for the same player.

This form of the API is a fire-and-forget form. Use this if you do not need to be notified of the results of submitting the score, though note that the update may not be sent to the server until the next sync.

The meaning of the score value depends on the formatting of the leaderboard established in the developer console. Leaderboards support the following score formats:

  • Fixed-point: score represents a raw value, and will be formatted based on the number of decimal places configured. A score of 1000 would be formatted as 1000, 100.0, or 10.00 for 0, 1, or 2 decimal places.
  • Time: score represents an elapsed time in milliseconds. The value will be formatted as an appropriate time value.
  • Currency: score represents a value in micro units. For example, in USD, a score of 100 would display as $0.0001, while a score of 1000000 would display as $1.00

For more details, please see Leaderboard Concepts.

Parameters
leaderboardId The leaderboard to submit the score to.
score The raw score value.
scoreTag Optional metadata about this score. The value may contain no more than 64 URI-safe characters as defined by section 2.3 of RFC 3986.

public void submitScore (String leaderboardId, long score)

Submit a score to a leaderboard for the currently signed in player. The score is ignored if it is worse (as defined by the leaderboard configuration) than a previously submitted score for the same player.

This form of the API is a fire-and-forget form. Use this if you do not need to be notified of the results of submitting the score, though note that the update may not be sent to the server until the next sync.

The meaning of the score value depends on the formatting of the leaderboard established in the developer console. Leaderboards support the following score formats:

  • Fixed-point: score represents a raw value, and will be formatted based on the number of decimal places configured. A score of 1000 would be formatted as 1000, 100.0, or 10.00 for 0, 1, or 2 decimal places.
  • Time: score represents an elapsed time in milliseconds. The value will be formatted as an appropriate time value.
  • Currency: score represents a value in micro units. For example, in USD, a score of 100 would display as $0.0001, while a score of 1000000 would display as $1.00

For more details, please see Leaderboard Concepts.

Parameters
leaderboardId The leaderboard to submit the score to.
score The raw score value.

public void submitScoreImmediate (OnScoreSubmittedListener listener, String leaderboardId, long score, String scoreTag)

Submit a score to a leaderboard for the currently signed in player. The score is ignored if it is worse (as defined by the leaderboard configuration) than a previously submitted score for the same player.

This form of the API will attempt to submit the score to the server immediately, and will use the provided listener to inform the caller of the result of the operation.

The status code to indicate the success or failure of the operation is delivered to the given listener on the main thread. If disconnect() is called before the operation is completed, the status code will not be delivered.

The meaning of the score value depends on the formatting of the leaderboard established in the developer console. Leaderboards support the following score formats:

  • Fixed-point: score represents a raw value, and will be formatted based on the number of decimal places configured. A score of 1000 would be formatted as 1000, 100.0, or 10.00 for 0, 1, or 2 decimal places.
  • Time: score represents an elapsed time in milliseconds. The value will be formatted as an appropriate time value.
  • Currency: score represents a value in micro units. For example, in USD, a score of 100 would display as $0.0001, while a score of 1000000 would display as $1.00

For more details, please see this page.

Parameters
listener OnScoreSubmittedListener to call when the score has been submitted.
leaderboardId The leaderboard to submit the score to.
score The raw score value.
scoreTag Optional metadata about this score. The value may contain no more than 64 URI-safe characters as defined by section 2.3 of RFC 3986.

public void submitScoreImmediate (OnScoreSubmittedListener listener, String leaderboardId, long score)

Submit a score to a leaderboard for the currently signed in player. The score is ignored if it is worse (as defined by the leaderboard configuration) than a previously submitted score for the same player.

This form of the API will attempt to submit the score to the server immediately, and will use the provided listener to inform the caller of the result of the operation.

The status code to indicate the success or failure of the operation is delivered to the given listener on the main thread. If disconnect() is called before the operation is completed, the status code will not be delivered.

The meaning of the score value depends on the formatting of the leaderboard established in the developer console. Leaderboards support the following score formats:

  • Fixed-point: score represents a raw value, and will be formatted based on the number of decimal places configured. A score of 1000 would be formatted as 1000, 100.0, or 10.00 for 0, 1, or 2 decimal places.
  • Time: score represents an elapsed time in milliseconds. The value will be formatted as an appropriate time value.
  • Currency: score represents a value in micro units. For example, in USD, a score of 100 would display as $0.0001, while a score of 1000000 would display as $1.00

For more details, please see this page.

Parameters
listener OnScoreSubmittedListener to call when the score has been submitted.
leaderboardId The leaderboard to submit the score to.
score The raw score value.

public void takeTurn (OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, String pendingParticipantId)

Update a match with new turn data. The participant that is passed in as the pending participant will be notified that it is their turn to take action. If no pending participant is provided and the match has available auto-match slots, the match will wait for additional players to be found. If there are no auto-match slots available for this match, a pending participant ID is required.

For the final turn of the match, there is no need to call this method. Instead, call finishTurnBasedMatch(OnTurnBasedMatchUpdatedListener, String) directly.

Parameters
listener The listener that is called when the match has been updated. The listener is called on the main thread.
matchId ID of the match to update.
matchData Data representing the new state of the match after this update. Limited to a maximum of getMaxTurnBasedMatchDataSize() bytes.
pendingParticipantId ID of the participant who will be set to pending after this update succeeds, or null to wait for additional automatched players (if possible).

public void takeTurn (OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, String pendingParticipantId, ParticipantResult... results)

Update a match with new turn data. The participant that is passed in as the pending participant will be notified that it is their turn to take action. If no pending participant is provided and the match has available auto-match slots, the match will wait for additional players to be found. If there are no auto-match slots available for this match, a pending participant ID is required.

For the final turn of the match, there is no need to call this method. Instead, call finishTurnBasedMatch(OnTurnBasedMatchUpdatedListener, String) directly.

Parameters
listener The listener that is called when the match has been updated. The listener is called on the main thread.
matchId ID of the match to update.
matchData Data representing the new state of the match after this update. Limited to a maximum of getMaxTurnBasedMatchDataSize() bytes.
pendingParticipantId ID of the participant who will be set to pending after this update succeeds, or null to wait for additional automatched players (if possible).
results Optional list of ParticipantResult objects for this match. Note that the results reported here should be final - if results reported later conflict with these values, the returned value will indicate a conflicted result by returning MATCH_RESULT_DISAGREED. This is most useful for cases where a participant knows their results early. For example, a single elimination game where participants are eliminated as the game continues might wish to specify results for the eliminated participants here.

public void takeTurn (OnTurnBasedMatchUpdatedListener listener, String matchId, byte[] matchData, String pendingParticipantId, List<ParticipantResult> results)

Update a match with new turn data. The participant that is passed in as the pending participant will be notified that it is their turn to take action. If no pending participant is provided and the match has available auto-match slots, the match will wait for additional players to be found. If there are no auto-match slots available for this match, a pending participant ID is required.

For the final turn of the match, there is no need to call this method. Instead, call finishTurnBasedMatch(OnTurnBasedMatchUpdatedListener, String) directly.

Parameters
listener The listener that is called when the match has been updated. The listener is called on the main thread.
matchId ID of the match to update.
matchData Data representing the new state of the match after this update. Limited to a maximum of getMaxTurnBasedMatchDataSize() bytes.
pendingParticipantId ID of the participant who will be set to pending after this update succeeds, or null to wait for additional automatched players (if possible).
results Optional list of ParticipantResult objects for this match. Note that the results reported here should be final - if results reported later conflict with these values, the returned value will indicate a conflicted result by returning MATCH_RESULT_DISAGREED. This is most useful for cases where a participant knows their results early. For example, a single elimination game where participants are eliminated as the game continues might wish to specify results for the eliminated participants here.

public void unlockAchievement (String id)

Unlock an achievement for the currently signed in player. If the achievement is hidden this will reveal it to the player.

This is the fire-and-forget form of the API. Use this form if you don't need to know the status of the operation immediately. For most applications, this will be the preferred API to use, though note that the update may not be sent to the server until the next sync. See unlockAchievementImmediate(OnAchievementUpdatedListener, String) if you need the operation to attempt to communicate to the server immediately or need to have the status code delivered to your application.

Parameters
id The achievement ID to unlock

public void unlockAchievementImmediate (OnAchievementUpdatedListener listener, String id)

Unlock an achievement for the currently signed in player. If the achievement is hidden this will reveal it to the player.

This form of the API will attempt to update the user's achievement on the server immediately, and will use the provided listener to inform the caller of the result of the operation.

The status code to indicate the success or failure of the operation is delivered to the given listener on the main thread. If disconnect() is called before the operation is completed, the status code will not be delivered.

Parameters
listener The listener that is called when the unlock achievement is complete. The listener is called on the main thread.
id The ID of the achievement to unlock.

public void unregisterConnectionCallbacks (GooglePlayServicesClient.ConnectionCallbacks listener)

Removes a connection listener from this GooglePlayServicesClient. Note that removing a listener does not generate any callbacks.

If the specified listener is not currently registered to receive connection events, this method will have no effect.

Parameters
listener the listener to unregister.

public void unregisterConnectionFailedListener (GooglePlayServicesClient.OnConnectionFailedListener listener)

Removes a connection failed listener from the GooglePlayServicesClient. Note that removing a listener does not generate any callbacks.

If the specified listener is not currently registered to receive connection failed events, this method will have no effect.

Parameters
listener the listener to unregister.

public void unregisterInvitationListener ()

Unregisters this client's invitation listener, if any. Any new invitations will generate status bar notifications as normal.

public void unregisterMatchUpdateListener ()

Unregisters this client's match update listener, if any. Any new match updates will generate status bar notifications as normal.