AchievementsClient

public interface AchievementsClient

A client to interact with achievements functionality.

Public Method Summary

abstract Task<Intent>
getAchievementsIntent()
Returns a Task which asynchronously loads an Intent to show the list of achievements for a game.
abstract void
increment(String id, int numSteps)
Increments an achievement by the given number of steps.
abstract Task<Boolean>
incrementImmediate(String id, int numSteps)
Returns a Task which asynchronously increments an achievement by the given number of steps.
abstract Task<AnnotatedData<AchievementBuffer>>
load(boolean forceReload)
Returns a Task which asynchronously loads an annotated AchievementBuffer that represents the achievement data for the currently signed-in player.
abstract void
reveal(String id)
Reveals a hidden achievement to the currently signed-in player.
abstract Task<Void>
revealImmediate(String id)
Returns a Task which asynchronously reveals a hidden achievement to the currently signed in player.
abstract void
setSteps(String id, int numSteps)
Sets an achievement to have at least the given number of steps completed.
abstract Task<Boolean>
setStepsImmediate(String id, int numSteps)
Returns a Task which asynchronously sets an achievement to have at least the given number of steps completed.
abstract void
unlock(String id)
Unlocks an achievement for the currently signed in player.
abstract Task<Void>
unlockImmediate(String id)
Returns a Task which asynchronously unlocks an achievement for the currently signed in player.

Public Methods

public abstract Task<Intent> getAchievementsIntent ()

Returns a Task which asynchronously loads an Intent to show the list of achievements for a game. 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 void increment (String id, int numSteps)

Increments an achievement by the given number of steps. The achievement must be an incremental achievement. Once an achievement reaches at least the maximum number of steps, it will be unlocked automatically. Any further increments will be ignored.

This is the fire-and-forget form of the API. Use this form if you don't need to know the status of the operation immediately. For most applications, this will be the preferred API to use, though note that the update may not be sent to the server until the next sync. See incrementImmediate(String, int) if you need the operation to attempt to communicate to the server immediately or need to have the status code delivered to your application.

Parameters
id The achievement ID to increment.
numSteps The number of steps to increment by. Must be greater than 0.

public abstract Task<Boolean> incrementImmediate (String id, int numSteps)

Returns a Task which asynchronously increments an achievement by the given number of steps. The achievement must be an incremental achievement. Once an achievement reaches at least the maximum number of steps, it will be unlocked automatically. Any further increments will be ignored.

This form of the API will attempt to update the user's achievement on the server immediately. The Boolean in a successful response indicates whether the achievement is now unlocked.

Parameters
id The ID of the achievement to increment.
numSteps The number of steps to increment by. Must be greater than 0.

public abstract Task<AnnotatedData<AchievementBuffer>> load (boolean forceReload)

Returns a Task which asynchronously loads an annotated AchievementBuffer that represents the achievement data for the currently signed-in player.

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

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 void reveal (String id)

Reveals a hidden achievement to the currently signed-in player. If the achievement has already been unlocked, this will have no effect.

This is the fire-and-forget form of the API. Use this form if you don't need to know the status of the operation immediately. For most applications, this will be the preferred API to use, though note that the update may not be sent to the server until the next sync. See revealImmediate(String) if you need the operation to attempt to communicate to the server immediately or need to have the status code delivered to your application.

Parameters
id The achievement ID to reveal.

public abstract Task<Void> revealImmediate (String id)

Returns a Task which asynchronously reveals a hidden achievement to the currently signed in player. If the achievement is already visible, this will have no effect.

This form of the API will attempt to update the user's achievement on the server immediately. The Task will complete successfully when the server has been updated.

Parameters
id The ID of the achievement to reveal.

public abstract void setSteps (String id, int numSteps)

Sets an achievement to have at least the given number of steps completed. Calling this method while the achievement already has more steps than the provided value is a no-op. Once the achievement reaches the maximum number of steps, the achievement will automatically be unlocked, and any further mutation operations will be ignored.

This is the fire-and-forget form of the API. Use this form if you don't need to know the status of the operation immediately. For most applications, this will be the preferred API to use, though note that the update may not be sent to the server until the next sync. See setStepsImmediate(String, int) if you need the operation to attempt to communicate to the server immediately or need to have the status code delivered to your application.

Parameters
id The ID of the achievement to modify.
numSteps The number of steps to set the achievement to. Must be greater than 0.

public abstract Task<Boolean> setStepsImmediate (String id, int numSteps)

Returns a Task which asynchronously sets an achievement to have at least the given number of steps completed. Calling this method while the achievement already has more steps than the provided value is a no-op. Once the achievement reaches the maximum number of steps, the achievement will automatically be unlocked, and any further mutation operations will be ignored.

This form of the API will attempt to update the user's achievement on the server immediately. The Boolean in a successful response indicates whether the achievement is now unlocked.

Parameters
id The ID of the achievement to modify.
numSteps The number of steps to set the achievement to. Must be greater than 0.

public abstract void unlock (String id)

Unlocks an achievement for the currently signed in player. If the achievement is hidden this will reveal it to the player.

This is the fire-and-forget form of the API. Use this form if you don't need to know the status of the operation immediately. For most applications, this will be the preferred API to use, though note that the update may not be sent to the server until the next sync. See unlockImmediate(String) if you need the operation to attempt to communicate to the server immediately or need to have the status code delivered to your application.

Parameters
id The achievement ID to unlock.

public abstract Task<Void> unlockImmediate (String id)

Returns a Task which asynchronously unlocks an achievement for the currently signed in player. If the achievement is hidden this will reveal it to the player.

This form of the API will attempt to update the user's achievement on the server immediately. The Task will complete successfully when the server has been updated.

Parameters
id The ID of the achievement to unlock.