public interface

Leaderboards

com.google.android.gms.games.leaderboard.Leaderboards

Class Overview

Entry point for leaderboard functionality.

Summary

Nested Classes
interface Leaderboards.LeaderboardMetadataResult Result delivered when leaderboard metadata has been loaded. 
interface Leaderboards.LoadPlayerScoreResult Result delivered when a player's leaderboard score has been loaded. 
interface Leaderboards.LoadScoresResult Result delivered when leaderboard scores have been loaded. 
interface Leaderboards.SubmitScoreResult Result delivered when a leaderboard score has been submitted. 
Public Methods
abstract Intent getAllLeaderboardsIntent(GoogleApiClient apiClient)
Gets an intent to show the list of leaderboards for a game.
abstract Intent getLeaderboardIntent(GoogleApiClient apiClient, String leaderboardId)
Gets an intent to show a leaderboard for a game.
abstract PendingResult<Leaderboards.LoadPlayerScoreResult> loadCurrentPlayerLeaderboardScore(GoogleApiClient apiClient, String leaderboardId, int span, int leaderboardCollection)
Asynchronously load the currently signed in player's score for a given leaderboard.
abstract PendingResult<Leaderboards.LeaderboardMetadataResult> loadLeaderboardMetadata(GoogleApiClient apiClient, String leaderboardId, boolean forceReload)
Asynchronously load a specific leaderboard's metadata for this game.
abstract PendingResult<Leaderboards.LeaderboardMetadataResult> loadLeaderboardMetadata(GoogleApiClient apiClient, boolean forceReload)
Asynchronously load the list of leaderboard metadata for this game.
abstract PendingResult<Leaderboards.LoadScoresResult> loadMoreScores(GoogleApiClient apiClient, LeaderboardScoreBuffer buffer, int maxResults, int pageDirection)
Asynchronously loads an additional page of score data for the given score buffer.
abstract PendingResult<Leaderboards.LoadScoresResult> loadPlayerCenteredScores(GoogleApiClient apiClient, String leaderboardId, int span, int leaderboardCollection, int maxResults)
Asynchronously load the player-centered page of scores for a given leaderboard.
abstract PendingResult<Leaderboards.LoadScoresResult> loadPlayerCenteredScores(GoogleApiClient apiClient, String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)
Asynchronously load the player-centered page of scores for a given leaderboard.
abstract PendingResult<Leaderboards.LoadScoresResult> loadTopScores(GoogleApiClient apiClient, String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)
Asynchronously load the top page of scores for a given leaderboard.
abstract PendingResult<Leaderboards.LoadScoresResult> loadTopScores(GoogleApiClient apiClient, String leaderboardId, int span, int leaderboardCollection, int maxResults)
Asynchronously load the top page of scores for a given leaderboard.
abstract void submitScore(GoogleApiClient apiClient, String leaderboardId, long score, String scoreTag)
Submit a score to a leaderboard for the currently signed in player.
abstract void submitScore(GoogleApiClient apiClient, String leaderboardId, long score)
Submit a score to a leaderboard for the currently signed in player.
abstract PendingResult<Leaderboards.SubmitScoreResult> submitScoreImmediate(GoogleApiClient apiClient, String leaderboardId, long score)
Submit a score to a leaderboard for the currently signed in player.
abstract PendingResult<Leaderboards.SubmitScoreResult> submitScoreImmediate(GoogleApiClient apiClient, String leaderboardId, long score, String scoreTag)
Submit a score to a leaderboard for the currently signed in player.

Public Methods

public abstract Intent getAllLeaderboardsIntent (GoogleApiClient apiClient)

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 GoogleApiClient ends up in an inconsistent state.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
Returns
  • An Intent that can be started to view the list of leaderboards for a game.

public abstract Intent getLeaderboardIntent (GoogleApiClient apiClient, 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 GoogleApiClient ends up in an inconsistent state.

Required API: API
Required Scopes: SCOPE_GAMES

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

public abstract PendingResult<Leaderboards.LoadPlayerScoreResult> loadCurrentPlayerLeaderboardScore (GoogleApiClient apiClient, String leaderboardId, int span, int leaderboardCollection)

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

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns

public abstract PendingResult<Leaderboards.LeaderboardMetadataResult> loadLeaderboardMetadata (GoogleApiClient apiClient, String leaderboardId, boolean forceReload)

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

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns

public abstract PendingResult<Leaderboards.LeaderboardMetadataResult> loadLeaderboardMetadata (GoogleApiClient apiClient, boolean forceReload)

Asynchronously load the list of leaderboard metadata for this game.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns

public abstract PendingResult<Leaderboards.LoadScoresResult> loadMoreScores (GoogleApiClient apiClient, 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.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns

public abstract PendingResult<Leaderboards.LoadScoresResult> loadPlayerCenteredScores (GoogleApiClient apiClient, 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.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns

public abstract PendingResult<Leaderboards.LoadScoresResult> loadPlayerCenteredScores (GoogleApiClient apiClient, 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.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns

public abstract PendingResult<Leaderboards.LoadScoresResult> loadTopScores (GoogleApiClient apiClient, String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)

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

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns

public abstract PendingResult<Leaderboards.LoadScoresResult> loadTopScores (GoogleApiClient apiClient, String leaderboardId, int span, int leaderboardCollection, int maxResults)

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

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns

public abstract void submitScore (GoogleApiClient apiClient, 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 API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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 abstract void submitScore (GoogleApiClient apiClient, 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 API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
leaderboardId The leaderboard to submit the score to.
score The raw score value.

public abstract PendingResult<Leaderboards.SubmitScoreResult> submitScoreImmediate (GoogleApiClient apiClient, 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 return a GamesPendingResult 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 API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
leaderboardId The leaderboard to submit the score to.
score The raw score value.
Returns

public abstract PendingResult<Leaderboards.SubmitScoreResult> submitScoreImmediate (GoogleApiClient apiClient, 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 return a GamesPendingResult 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 API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
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.
Returns