LeaderboardsClient

public class LeaderboardsClient extends GoogleApi<Games.GamesOptions>

A client to interact with leaderboards functionality.

Nested Class Summary

class LeaderboardsClient.LeaderboardScores Result delivered when leaderboard scores have been loaded. 

Public Method Summary

Task<Intent>
getAllLeaderboardsIntent()
Returns a Task which asynchronously loads an Intent to show the list of leaderboards for a game.
Task<Intent>
getLeaderboardIntent(String leaderboardId, int timeSpan)
Returns a Task which asynchronously loads an Intent to show a leaderboard for a game specified by a leaderboardId.
Task<Intent>
getLeaderboardIntent(String leaderboardId)
Returns a Task which asynchronously loads an Intent to show a leaderboard for a game specified by a leaderboardId.
Task<Intent>
getLeaderboardIntent(String leaderboardId, int timeSpan, int collection)
Returns a Task which asynchronously loads an Intent to show a leaderboard for a game specified by a leaderboardId.
Task<AnnotatedData<LeaderboardScore>>
loadCurrentPlayerLeaderboardScore(String leaderboardId, int span, int leaderboardCollection)
Returns a Task which asynchronously loads an annotated LeaderboardScore that represents the signed-in player's score for the leaderboard specified by leaderboardId.
Task<AnnotatedData<LeaderboardBuffer>>
loadLeaderboardMetadata(boolean forceReload)
Returns a Task which asynchronously loads an annotated LeaderboardBuffer that represents a list of leaderboards metadata for this game.
Task<AnnotatedData<Leaderboard>>
loadLeaderboardMetadata(String leaderboardId, boolean forceReload)
Returns a Task which asynchronously loads an annotated Leaderboard specified by leaderboardId.
Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>>
loadMoreScores(LeaderboardScoreBuffer buffer, int maxResults, int pageDirection)
Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents an additional page of score data for the given score buffer.
Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>>
loadPlayerCenteredScores(String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)
Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents the player-centered page of scores for the leaderboard specified by leaderboardId.
Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>>
loadPlayerCenteredScores(String leaderboardId, int span, int leaderboardCollection, int maxResults)
Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents the player-centered page of scores for the leaderboard specified by leaderboardId.
Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>>
loadTopScores(String leaderboardId, int span, int leaderboardCollection, int maxResults)
Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents the top page of scores for a given leaderboard specified by leaderboardId.
Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>>
loadTopScores(String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)
Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents the top page of scores for the leaderboard specified by leaderboardId.
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.
Task<ScoreSubmissionData>
submitScoreImmediate(String leaderboardId, long score, String scoreTag)
Returns a Task which asynchronously submits the score to the leaderboard for the currently signed-in player.
Task<ScoreSubmissionData>
submitScoreImmediate(String leaderboardId, long score)
Returns a Task which asynchronously submits the score to the leaderboard for the currently signed-in player.

Inherited Method Summary

Public Methods

public Task<Intent> getAllLeaderboardsIntent ()

Returns a Task which asynchronously loads 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.

The returned Task can fail with a RemoteException.

Required Scopes: SCOPE_GAMES_LITE

public Task<Intent> getLeaderboardIntent (String leaderboardId, int timeSpan)

Returns a Task which asynchronously loads an Intent to show a leaderboard for a game specified by a leaderboardId. Note that the Intent returned from the Task must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

The returned Task can fail with a RemoteException.

Required Scopes: SCOPE_GAMES_LITE

Parameters
leaderboardId The ID of the leaderboard to view.
timeSpan Time span to retrieve data for. Valid values are TIME_SPAN_DAILY, TIME_SPAN_WEEKLY, or TIME_SPAN_ALL_TIME.

public Task<Intent> getLeaderboardIntent (String leaderboardId)

Returns a Task which asynchronously loads an Intent to show a leaderboard for a game specified by a leaderboardId. Note that the Intent returned from the Task must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

The returned Task can fail with a RemoteException.

Required Scopes: SCOPE_GAMES_LITE

Parameters
leaderboardId The ID of the leaderboard to view.

public Task<Intent> getLeaderboardIntent (String leaderboardId, int timeSpan, int collection)

Returns a Task which asynchronously loads an Intent to show a leaderboard for a game specified by a leaderboardId. Note that the Intent returned from the Task must be invoked with startActivityForResult(Intent, int), so that the identity of the calling package can be established.

The returned Task can fail with a RemoteException.

Required Scopes: SCOPE_GAMES_LITE

Parameters
leaderboardId The ID of the leaderboard to view.
timeSpan Time span to retrieve data for. Valid values are TIME_SPAN_DAILY, TIME_SPAN_WEEKLY, or TIME_SPAN_ALL_TIME.
collection The collection to show by default. Valid values are COLLECTION_PUBLIC or COLLECTION_SOCIAL.

public Task<AnnotatedData<LeaderboardScore>> loadCurrentPlayerLeaderboardScore (String leaderboardId, int span, int leaderboardCollection)

Returns a Task which asynchronously loads an annotated LeaderboardScore that represents the signed-in player's score for the leaderboard specified by leaderboardId. See Leaderboards.LoadPlayerScoreResult for possible error codes.

Required Scopes: SCOPE_GAMES_LITE

Parameters
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 Task<AnnotatedData<LeaderboardBuffer>> loadLeaderboardMetadata (boolean forceReload)

Returns a Task which asynchronously loads an annotated LeaderboardBuffer that represents a list of leaderboards metadata for this game. See Leaderboards.LeaderboardMetadataResult for possible error codes.

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

Required Scopes: SCOPE_GAMES_LITE

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 Task<AnnotatedData<Leaderboard>> loadLeaderboardMetadata (String leaderboardId, boolean forceReload)

Returns a Task which asynchronously loads an annotated Leaderboard specified by leaderboardId. See Leaderboards.LeaderboardMetadataResult for possible error codes.

Required Scopes: SCOPE_GAMES_LITE

Parameters
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 Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadMoreScores (LeaderboardScoreBuffer buffer, int maxResults, int pageDirection)

Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents an additional page of score data for the given score buffer. A new score buffer will be delivered that replaces the given buffer.

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

Required Scopes: SCOPE_GAMES_LITE

Parameters
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. Note that the number of scores returned here may be greater than this value, depending on how much data is cached on the device.
pageDirection The direction to expand the buffer. Values are defined in PageDirection.

public Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadPlayerCenteredScores (String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)

Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents the player-centered page of scores for the leaderboard specified by leaderboardId. If the player does not have a score on this leaderboard, this call will return the top page instead.

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

Required Scopes: SCOPE_GAMES_LITE

Parameters
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 Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadPlayerCenteredScores (String leaderboardId, int span, int leaderboardCollection, int maxResults)

Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents the player-centered page of scores for the leaderboard specified by leaderboardId. If the player does not have a score on this leaderboard, this call will return the top page instead.

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

Required Scopes: SCOPE_GAMES_LITE

Parameters
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 Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadTopScores (String leaderboardId, int span, int leaderboardCollection, int maxResults)

Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents the top page of scores for a given leaderboard specified by leaderboardId.

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

Required Scopes: SCOPE_GAMES_LITE

Parameters
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 Task<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadTopScores (String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)

Returns a Task which asynchronously loads an annotated LeaderboardsClient.LeaderboardScores that represents the top page of scores for the leaderboard specified by leaderboardId.

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

Required Scopes: SCOPE_GAMES_LITE

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

Required Scopes: SCOPE_GAMES_LITE

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.

Required Scopes: SCOPE_GAMES_LITE

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

public Task<ScoreSubmissionData> submitScoreImmediate (String leaderboardId, long score, String scoreTag)

Returns a Task which asynchronously submits the score to the 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 or the same player.

This form of the API will attempt to submit the score to the server immediately within the task, returning a ScoreSubmissionData on success with information about the submission.

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.

The returned Task will fail with an IllegalArgumentException if scoreTag is malformed.

Required Scopes: SCOPE_GAMES_LITE

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 Task<ScoreSubmissionData> submitScoreImmediate (String leaderboardId, long score)

Returns a Task which asynchronously submits the score to the 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 or the same player.

This form of the API will attempt to submit the score to the server immediately within the task, returning a ScoreSubmissionData on success with information about the submission.

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.

Required Scopes: SCOPE_GAMES_LITE

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