GamesClient

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

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

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

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

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

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

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

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

Notification types for any notification.

Notification types for multiplayer notifications.

Notification type for invites to multiplayer games.

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

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

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

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

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

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.

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

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.

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

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.

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.

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

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.

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

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.

The operation was successful.

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

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

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

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.

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

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

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

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.

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:

• EXTRA_INVITATION if the user wanted to accept an invitation to a multiplayer game. The value contained here is an Invitation which can be accessed with getParcelable(String).

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.

Decline an invitation for a real-time room.

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

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

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.

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.

Get the application ID linked to this GamesClient instance.

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

Load the details for the current game.

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.

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.

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.

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.

This form of the API is deprecated and will be removed in a future release. Please use loadLeaderboardMetadata(OnLeaderboardMetadataLoadedListener, String, boolean) instead.

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.

This form of the API is deprecated and will be removed in a future release. Please use loadLeaderboardMetadata(OnLeaderboardMetadataLoadedListener, boolean) instead.

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.

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.

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.

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.

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.

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.

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.

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.

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.

This method will call onDisconnected() followed by either onConnected(Bundle) if the connection is successful or onConnectionFailed(ConnectionResult) on a failure.

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.

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.

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 listener may be active at a time. Calling this method while another listener was previously registered will replace the original listener with the new one.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Set whether or not to use the "new player" style notifications for the invitation inbox or destination app.

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

Asynchronously signs the current user out.

Asynchronously signs the current user out.

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.

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.

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.

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.

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.

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.

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.

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.

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