Leaderboards | Android Developers

Quicknav Quicknav
Links

- Google Play Developer Console
- Android Developers Blog
- About Android

Android Sites

- Android.com
- Android Developers
- Android Open Source Project

Language
close

- - About
  - Wear
  - TV
  - Auto
- - Get Started
  - Devices
  - Style
  - Patterns
  - Building Blocks
  - Downloads
  - Videos
- - Training
  - API Guides
  - Reference
  - Tools
  - Google Services
  - Samples
- - Google Play
  - Essentials
  - Get Users
  - Engage & Retain
  - Monetize
  - Tools & Reference
  - Developer Stories

## Results

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.

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

- `PendingResult` to access the data when available.