A client to interact with leaderboards functionality.
Nested Class Summary
| class | LeaderboardsClient.LeaderboardScores | Result delivered when leaderboard scores have been loaded. | |
Public Method Summary
| abstractTask<Intent> | |
| abstractTask<Intent> |
getLeaderboardIntent(String
leaderboardId, int timeSpan)
|
| abstractTask<Intent> |
getLeaderboardIntent(String
leaderboardId)
|
| abstractTask<Intent> |
getLeaderboardIntent(String
leaderboardId, int timeSpan, int collection)
|
| abstractTask<AnnotatedData<LeaderboardScore>> |
loadCurrentPlayerLeaderboardScore(String
leaderboardId, int span, int leaderboardCollection)
Returns a
Task
which asynchronously loads an annotated
LeaderboardScorethat represents the signed-in player's score for
the leaderboard specified byleaderboardId.
|
| abstractTask<AnnotatedData<LeaderboardBuffer>> |
loadLeaderboardMetadata(boolean forceReload)
Returns a
Task
which asynchronously loads an annotated
LeaderboardBufferthat represents a list of leaderboards metadata
for this game.
|
| abstractTask<AnnotatedData<Leaderboard>> |
loadLeaderboardMetadata(String
leaderboardId, boolean forceReload)
|
| abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> |
loadMoreScores(LeaderboardScoreBuffer
buffer, int maxResults, int pageDirection)
Returns a
Task
which asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents an additional
page of score data for the given score buffer.
|
| abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> |
loadPlayerCenteredScores(String
leaderboardId, int span, int leaderboardCollection, int maxResults, boolean
forceReload)
Returns a
Task
which asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents the
player-centered page of scores for the leaderboard specified by
leaderboardId.
|
| abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> |
loadPlayerCenteredScores(String
leaderboardId, int span, int leaderboardCollection, int maxResults)
Returns a
Task
which asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents the
player-centered page of scores for the leaderboard specified by
leaderboardId.
|
| abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> |
loadTopScores(String
leaderboardId, int span, int leaderboardCollection, int maxResults)
Returns a
Task
which asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents the top page of
scores for a given leaderboard specified byleaderboardId.
|
| abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> |
loadTopScores(String
leaderboardId, int span, int leaderboardCollection, int maxResults, boolean
forceReload)
Returns a
Task
which asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents the top page of
scores for the leaderboard specified byleaderboardId.
|
| abstract void |
submitScore(String
leaderboardId, long score,StringscoreTag)
Submit a score to a leaderboard for the currently signed-in player.
|
| abstract void |
submitScore(String
leaderboardId, long score)
Submit a score to a leaderboard for the currently signed-in player.
|
| abstractTask<ScoreSubmissionData> |
submitScoreImmediate(String
leaderboardId, long score,StringscoreTag)
Returns a
Task
which asynchronously submits thescoreto the leaderboard for the
currently signed-in player.
|
| abstractTask<ScoreSubmissionData> |
submitScoreImmediate(String
leaderboardId, long score)
Returns a
Task
which asynchronously submits thescoreto the leaderboard for the
currently signed-in player.
|
Public Methods
public abstractTask<Intent> getAllLeaderboardsIntent()
Returns aTaskwhich
asynchronously loads anIntentto
show the list of leaderboards for a game. Note that this must be invoked with
Activity.startActivityForResult(Intent, int),so that the identity of the
calling package can be established.
The returnedTaskcan fail with aRemoteException.
public abstractTask<Intent> getLeaderboardIntent(String leaderboardId, int timeSpan)
Returns aTaskwhich
asynchronously loads anIntentto
show a leaderboard for a game specified by aleaderboardId.Note that the
Intentreturned from theTaskmust be invoked with
Activity.startActivityForResult(Intent, int),so that the identity of the
calling package can be established.
The returnedTaskcan fail with aRemoteException.
Parameters
| leaderboardId | The ID of the leaderboard to view. |
|---|---|
| timeSpan | Time span to retrieve data for. Valid values are
LeaderboardVariant.TIME_SPAN_DAILY,
LeaderboardVariant.TIME_SPAN_WEEKLY,or
LeaderboardVariant.TIME_SPAN_ALL_TIME. |
public abstractTask<Intent> getLeaderboardIntent(String leaderboardId)
Returns aTaskwhich
asynchronously loads anIntentto
show a leaderboard for a game specified by aleaderboardId.Note that the
Intentreturned from theTaskmust be invoked with
Activity.startActivityForResult(Intent, int),so that the identity of the
calling package can be established.
The returnedTaskcan fail with aRemoteException.
Parameters
| leaderboardId | The ID of the leaderboard to view. |
|---|
public abstractTask<Intent> getLeaderboardIntent(String leaderboardId, int timeSpan, int collection)
Returns aTaskwhich
asynchronously loads anIntentto
show a leaderboard for a game specified by aleaderboardId.Note that the
Intentreturned from theTaskmust be invoked with
Activity.startActivityForResult(Intent, int),so that the identity of the
calling package can be established.
The returnedTaskcan fail with aRemoteException.
Parameters
| leaderboardId | The ID of the leaderboard to view. |
|---|---|
| timeSpan | Time span to retrieve data for. Valid values are
LeaderboardVariant.TIME_SPAN_DAILY,
LeaderboardVariant.TIME_SPAN_WEEKLY,or
LeaderboardVariant.TIME_SPAN_ALL_TIME. |
| collection | The collection to show by default. Valid values are
LeaderboardVariant.COLLECTION_PUBLICor
LeaderboardVariant.COLLECTION_FRIENDS. |
public abstractTask<AnnotatedData<LeaderboardScore>> loadCurrentPlayerLeaderboardScore(String leaderboardId, int span, int leaderboardCollection)
Returns aTaskwhich
asynchronously loads an annotated
LeaderboardScorethat represents the signed-in player's score for the
leaderboard specified byleaderboardId.
For
LeaderboardVariant.COLLECTION_FRIENDS,this call will fail with
FriendsResolutionRequiredExceptionif the user has not granted the game
access to their friends list. The exception result can be used to ask for consent.
Parameters
| leaderboardId | ID of the leaderboard to load the score from. |
|---|---|
| span | Time span to retrieve data for. Valid values are
LeaderboardVariant.TIME_SPAN_DAILY,
LeaderboardVariant.TIME_SPAN_WEEKLY,or
LeaderboardVariant.TIME_SPAN_ALL_TIME. |
| leaderboardCollection | The leaderboard collection to retrieve scores for. Valid values are either
LeaderboardVariant.COLLECTION_PUBLICor
LeaderboardVariant.COLLECTION_FRIENDS. |
public abstractTask<AnnotatedData<LeaderboardBuffer>> loadLeaderboardMetadata(boolean forceReload)
Returns aTaskwhich
asynchronously loads an annotated
LeaderboardBufferthat represents a list of leaderboards metadata for this
game.
AbstractDataBuffer.release()should be called to release resources after
usage.
Parameters
| forceReload | Iftrue,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 tofalse
to gain advantages of data caching. |
|---|
public abstractTask<AnnotatedData<Leaderboard>> loadLeaderboardMetadata(String leaderboardId, boolean forceReload)
Returns aTaskwhich
asynchronously loads an annotated
Leaderboardspecified byleaderboardId.
Parameters
| leaderboardId | ID of the leaderboard to load metadata for. |
|---|---|
| forceReload | Iftrue,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 tofalse
to gain advantages of data caching. |
public abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadMoreScores(LeaderboardScoreBuffer buffer, int maxResults, int pageDirection)
Returns aTaskwhich
asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents an additional page of
score data for the given score buffer. A new score buffer will be delivered that
replaces the given buffer.
LeaderboardsClient.LeaderboardScores.release()should be called to release
resources after usage.
For
LeaderboardVariant.COLLECTION_FRIENDS,this call will fail with
FriendsResolutionRequiredExceptionif the user has not granted the game
access to their friends list. The exception result can be used to ask for consent.
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 inPageDirection. |
public abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadPlayerCenteredScores(String leaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)
Returns aTaskwhich
asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents the player-centered
page of scores for the leaderboard specified byleaderboardId.If the
player does not have a score on this leaderboard, this call will return the top page
instead.
LeaderboardsClient.LeaderboardScores.release()should be called to release
resources after usage.
For
LeaderboardVariant.COLLECTION_FRIENDS,this call will fail with
FriendsResolutionRequiredExceptionif the user has not granted the game
access to their friends list. The exception result can be used to ask for consent.
Parameters
| leaderboardId | ID of the leaderboard. |
|---|---|
| span | Time span to retrieve data for. Valid values are
LeaderboardVariant.TIME_SPAN_DAILY,
LeaderboardVariant.TIME_SPAN_WEEKLY,or
LeaderboardVariant.TIME_SPAN_ALL_TIME. |
| leaderboardCollection | The leaderboard collection to retrieve scores for. Valid values are either
LeaderboardVariant.COLLECTION_PUBLICor
LeaderboardVariant.COLLECTION_FRIENDS. |
| maxResults | The maximum number of scores to fetch per page. Must be between 1 and 25. |
| forceReload | Iftrue,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 tofalse
to gain advantages of data caching. |
public abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadPlayerCenteredScores(String leaderboardId, int span, int leaderboardCollection, int maxResults)
Returns aTaskwhich
asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents the player-centered
page of scores for the leaderboard specified byleaderboardId.If the
player does not have a score on this leaderboard, this call will return the top page
instead.
LeaderboardsClient.LeaderboardScores.release()should be called to release
resources after usage.
For
LeaderboardVariant.COLLECTION_FRIENDS,this call will fail with
FriendsResolutionRequiredExceptionif the user has not granted the game
access to their friends list. The exception result can be used to ask for consent.
Parameters
| leaderboardId | ID of the leaderboard. |
|---|---|
| span | Time span to retrieve data for. Valid values are
LeaderboardVariant.TIME_SPAN_DAILY,
LeaderboardVariant.TIME_SPAN_WEEKLY,or
LeaderboardVariant.TIME_SPAN_ALL_TIME. |
| leaderboardCollection | The leaderboard collection to retrieve scores for. Valid values are either
LeaderboardVariant.COLLECTION_PUBLICor
LeaderboardVariant.COLLECTION_FRIENDS. |
| maxResults | The maximum number of scores to fetch per page. Must be between 1 and 25. |
public abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadTopScores(StringleaderboardId, int span, int leaderboardCollection, int maxResults)
Returns aTaskwhich
asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents the top page of scores
for a given leaderboard specified byleaderboardId.
LeaderboardsClient.LeaderboardScores.release()should be called to release
resources after usage.
For
LeaderboardVariant.COLLECTION_FRIENDS,this call will fail with
FriendsResolutionRequiredExceptionif the user has not granted the game
access to their friends list. The exception result can be used to ask for consent.
Parameters
| leaderboardId | ID of the leaderboard. |
|---|---|
| span | Time span to retrieve data for. Valid values are
LeaderboardVariant.TIME_SPAN_DAILY,
LeaderboardVariant.TIME_SPAN_WEEKLY,or
LeaderboardVariant.TIME_SPAN_ALL_TIME. |
| leaderboardCollection | The leaderboard collection to retrieve scores for. Valid values are either
LeaderboardVariant.COLLECTION_PUBLICor
LeaderboardVariant.COLLECTION_FRIENDS. |
| maxResults | The maximum number of scores to fetch per page. Must be between 1 and 25. |
public abstractTask<AnnotatedData<LeaderboardsClient.LeaderboardScores>> loadTopScores(StringleaderboardId, int span, int leaderboardCollection, int maxResults, boolean forceReload)
Returns aTaskwhich
asynchronously loads an annotated
LeaderboardsClient.LeaderboardScoresthat represents the top page of scores
for the leaderboard specified byleaderboardId.
LeaderboardsClient.LeaderboardScores.release()should be called to release
resources after usage.
For
LeaderboardVariant.COLLECTION_FRIENDS,this call will fail with
FriendsResolutionRequiredExceptionif the user has not granted the game
access to their friends list. The exception result can be used to ask for consent.
Parameters
| leaderboardId | ID of the leaderboard. |
|---|---|
| span | Time span to retrieve data for. Valid values are
LeaderboardVariant.TIME_SPAN_DAILY,
LeaderboardVariant.TIME_SPAN_WEEKLY,or
LeaderboardVariant.TIME_SPAN_ALL_TIME. |
| leaderboardCollection | The leaderboard collection to retrieve scores for. Valid values are either
LeaderboardVariant.COLLECTION_PUBLICor
LeaderboardVariant.COLLECTION_FRIENDS. |
| maxResults | The maximum number of scores to fetch per page. Must be between 1 and 25. |
| forceReload | Iftrue,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 tofalse
to gain advantages of data caching. |
public abstract voidsubmitScore(StringleaderboardId, 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:
scorerepresents 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:
scorerepresents an elapsed time in milliseconds. The value will be formatted as an appropriate time value. - Currency:
scorerepresents 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 seeLeaderboard Concepts.
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 abstract voidsubmitScore(StringleaderboardId, 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:
scorerepresents 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:
scorerepresents an elapsed time in milliseconds. The value will be formatted as an appropriate time value. - Currency:
scorerepresents 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 seeLeaderboard Concepts.
Parameters
| leaderboardId | The leaderboard to submit the score to. |
|---|---|
| score | The raw score value. |
public abstractTask<ScoreSubmissionData> submitScoreImmediate(String leaderboardId, long score,StringscoreTag)
Returns aTaskwhich
asynchronously submits thescoreto 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 for the same player.
This form of the API will attempt to submit the score to the server immediately
within the task, returning a
ScoreSubmissionDataon 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:
scorerepresents 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:
scorerepresents an elapsed time in milliseconds. The value will be formatted as an appropriate time value. - Currency:
scorerepresents 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 seethis page.
The returnedTaskwill fail with anIllegalArgumentException
ifscoreTagis malformed.
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 abstractTask<ScoreSubmissionData> submitScoreImmediate(String leaderboardId, long score)
Returns aTaskwhich
asynchronously submits thescoreto 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 for the same player.
This form of the API will attempt to submit the score to the server immediately
within the task, returning a
ScoreSubmissionDataon 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:
scorerepresents 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:
scorerepresents an elapsed time in milliseconds. The value will be formatted as an appropriate time value. - Currency:
scorerepresents 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 seethis page.
Parameters
| leaderboardId | The leaderboard to submit the score to. |
|---|---|
| score | The raw score value. |