PlayersClient

public interface PlayersClient

A client to interact with Players.

Constant Summary

String EXTRA_PLAYER_SEARCH_RESULTS Used by the Player Search UI to return a list of parceled Player objects.

Public Method Summary

abstract Task<Intent>
getCompareProfileIntent(String otherPlayerId)
Returns a Task which asynchronously loads an Intent that will display a screen where the user can see a comparison of their own profile against another player's profile.
abstract Task<Intent>
getCompareProfileIntent(Player player)
Returns a Task which asynchronously loads an Intent that will display a screen where the user can compare themselves against another player's profile.
abstract Task<Intent>
getCompareProfileIntentWithAlternativeNameHints(String otherPlayerId, String otherPlayerInGameName, String currentPlayerInGameName)
Returns a Task which asynchronously loads an Intent that will display a screen where the user can see a comparison of their own profile against another player's profile.
abstract Task<AnnotatedData<Player>>
getCurrentPlayer(boolean forceReload)
Returns a Task which asynchronously loads the current signed-in Player, if available.
abstract Task<Player>
getCurrentPlayer()
Returns a Task which asynchronously loads the current signed-in Player, if available.
abstract Task<String>
getCurrentPlayerId()
Returns a Task which asynchronously loads the current signed-in player ID, if available.
abstract Task<Intent>
getPlayerSearchIntent()
Returns a Task which asynchronously loads an Intent that will display a screen where the user can search for players.
abstract Task<AnnotatedData<PlayerBuffer>>
loadFriends(int pageSize, boolean forceReload)
Returns a Task which asynchronously loads an annotated PlayerBuffer that represents friends the user has.
abstract Task<AnnotatedData<PlayerBuffer>>
loadMoreFriends(int pageSize)
Returns a Task which asynchronously loads an annotated PlayerBuffer that represents friends the user has.
abstract Task<AnnotatedData<PlayerBuffer>>
loadMoreRecentlyPlayedWithPlayers(int pageSize)
This method is deprecated. Real-time multiplayer and Turn-based multiplayer support is being shut down on March 31, 2020. See Multiplayer deprecation
abstract Task<AnnotatedData<Player>>
loadPlayer(String playerId, boolean forceReload)
Returns a Task which asynchronously loads an annotated Player profile specified by playerId.
abstract Task<AnnotatedData<Player>>
loadPlayer(String playerId)
Returns a Task which asynchronously loads an annotated Player profile specified by playerId.
abstract Task<AnnotatedData<PlayerBuffer>>
loadRecentlyPlayedWithPlayers(int pageSize, boolean forceReload)
This method is deprecated. Real-time multiplayer and Turn-based multiplayer support is being shut down on March 31, 2020. See Multiplayer deprecation

Constants

public static final String EXTRA_PLAYER_SEARCH_RESULTS

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

See getPlayerSearchIntent()

Constant Value: "player_search_results"

Public Methods

public abstract Task<Intent> getCompareProfileIntent (String otherPlayerId)

Returns a Task which asynchronously loads an Intent that will display a screen where the user can see a comparison of their own profile against another player's profile. Note that the Intent returned from the Task must be invoked with Activity.startActivityForResult(Intent, int), so that the identity of the calling package can be established.

Parameters
otherPlayerId The player ID of the player to compare with.

public abstract Task<Intent> getCompareProfileIntent (Player player)

Returns a Task which asynchronously loads an Intent that will display a screen where the user can compare themselves against another player's profile. Note that the Intent returned from the Task must be invoked with Activity.startActivityForResult(Intent, int), so that the identity of the calling package can be established.

The returned Task can fail with a RemoteException.

public abstract Task<Intent> getCompareProfileIntentWithAlternativeNameHints (String otherPlayerId, String otherPlayerInGameName, String currentPlayerInGameName)

Returns a Task which asynchronously loads an Intent that will display a screen where the user can see a comparison of their own profile against another player's profile. Note that the Intent returned from the Task must be invoked with Activity.startActivityForResult(Intent, int), so that the identity of the calling package can be established.

Note that PGS gamer tags should not be provided as the "alternative" name. This form of #getCompareProfileIntent should be used when the game has its own player names separate from the Play Games Services gamer tag. These names will be used in the profile display and only sent to the server if the player initiates a friend invitation to the profile being viewed, so that the sender and recipient have context relevant to their game experience.

Parameters
otherPlayerId The player ID of the player to compare with.
otherPlayerInGameName The game's own display name of the player referred to by otherPlayerId.
currentPlayerInGameName The game's own display name of the current player.

public abstract Task<AnnotatedData<Player>> getCurrentPlayer (boolean forceReload)

Returns a Task which asynchronously loads the current signed-in Player, if available.

The returned Task can fail with a RemoteException.

Parameters
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 abstract Task<Player> getCurrentPlayer ()

Returns a Task which asynchronously loads the current signed-in Player, if available.

The returned Task can fail with a RemoteException.

public abstract Task<String> getCurrentPlayerId ()

Returns a Task which asynchronously loads the current signed-in player ID, if available.

The returned Task can fail with a RemoteException.

public abstract Task<Intent> getPlayerSearchIntent ()

Returns a Task which asynchronously loads an Intent that will display a screen where the user can search for players.

Note that this must be invoked with Activity.startActivityForResult(Intent, int), so that the identity of the calling package can be established.

If the user canceled, the result will be Activity.RESULT_CANCELED. If the user selected any players from the search results list, the result will be Activity.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 returned Task can fail with a RemoteException.

public abstract Task<AnnotatedData<PlayerBuffer>> loadFriends (int pageSize, boolean forceReload)

Returns a Task which asynchronously loads an annotated PlayerBuffer that represents friends the user has.

This call will fail with FriendsResolutionRequiredException if the user has not granted the game access to their friends list. The exception result can be used to ask for consent.

AbstractDataBuffer.release() should be called to release resources after usage.

Parameters
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.
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 abstract Task<AnnotatedData<PlayerBuffer>> loadMoreFriends (int pageSize)

Returns a Task which asynchronously loads an annotated PlayerBuffer that represents friends the user has. The PlayerBuffer will contain an extra page of results.

This call will fail with FriendsResolutionRequiredException if the user has not granted the game access to their friends list. The exception result can be used to ask for consent.

AbstractDataBuffer.release() should be called to release resources after usage.

Parameters
pageSize The number of additional entries to request.

public abstract Task<AnnotatedData<PlayerBuffer>> loadMoreRecentlyPlayedWithPlayers (int pageSize)

This method is deprecated.
Real-time multiplayer and Turn-based multiplayer support is being shut down on March 31, 2020. See Multiplayer deprecation

Returns a Task which asynchronously loads an annotated PlayerBuffer that represents players the user has interacted with recently, starting with the most recent.

AbstractDataBuffer.release() should be called to release resources after usage.

Parameters
pageSize The number of additional entries to request. This must be a value between 1 and 25.

public abstract Task<AnnotatedData<Player>> loadPlayer (String playerId, boolean forceReload)

Returns a Task which asynchronously loads an annotated Player profile specified by playerId.

The returned Task can fail with a RemoteException.

Parameters
playerId The player ID to get full profile data 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 abstract Task<AnnotatedData<Player>> loadPlayer (String playerId)

Returns a Task which asynchronously loads an annotated Player profile specified by playerId.

Returns the locally-cached player if available.

The returned Task can fail with a RemoteException.

Parameters
playerId The player ID to get full profile data for.

public abstract Task<AnnotatedData<PlayerBuffer>> loadRecentlyPlayedWithPlayers (int pageSize, boolean forceReload)

This method is deprecated.
Real-time multiplayer and Turn-based multiplayer support is being shut down on March 31, 2020. See Multiplayer deprecation

Returns a Task which asynchronously loads an annotated PlayerBuffer that represents players the user has interacted with recently, starting with the most recent.

AbstractDataBuffer.release() should be called to release resources after usage.

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