GKAchievement Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 4.1 and later.
Companion guide
Declared in
GKAchievement.h
GKChallenge.h
Related sample code

Overview

Your game uses a GKAchievement object to communicate with Game Center about the local player’s progress towards completing an achievement.

To request the local player’s progress on achievements, call the loadAchievementsWithCompletionHandler: class method.

To report the local player’s progress on an achievement, your game updates the percentComplete property of an achievement object and calls the object’s reportAchievementWithCompletionHandler: method. To report progress on multiple achievements at once, use the reportAchievements:withCompletionHandler: class method.

By default, when an achievement is completed, Game Kit displays a notification banner to the player. If your game wants to display its own achievement user interface, you can prevent the banner from being displayed by setting the showsCompletionBanner property of the achievement object to NO before reporting the player’s progress.

To clear all progress the local player has made on achievements, call the resetAchievementsWithCompletionHandler: class method.

Tasks

Retrieving Achievement Progress from Game Center

Initializing an Achievement Object

Configuring an Achievement

Reading the State of an Achievement

Reporting Progress on an Achievement

Displaying a Notification Banner For an Achievement

Resetting the Player’s Progress on Achievements

Issuing Achievement Challenges

Identifying a Player

Properties

completed

A Boolean value that states whether the player has completed the achievement. (read-only)

@property(readonly, getter=isCompleted, nonatomic) BOOL completed
Discussion

The value of this property is YES if the percentComplete property is equal to 100.0; otherwise, it is NO.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
GKAchievement.h

identifier

A string used to uniquely identify the specific achievement the object refers to.

@property(copy, nonatomic) NSString *identifier
Discussion

The identifier property must match the identifier string for an achievement you created for your game on iTunes Connect.

Availability
  • Available in iOS 4.0 and later.
Declared In
GKAchievement.h

lastReportedDate

The last time that progress on the achievement was successfully reported to Game Center. (read-only)

@property(copy, readonly, nonatomic) NSDate *lastReportedDate
Discussion

On a newly initialized achievement object, this property holds the current date.

Availability
  • Available in iOS 4.0 and later.
Declared In
GKAchievement.h

percentComplete

A percentage value that states how far the player has progressed on this achievement.

@property(assign, nonatomic) double percentComplete
Discussion

The default value for a newly initialized achievement object is 0.0. The range of legal values is between 0.0 and 100.0, inclusive.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
GKAchievement.h

playerID

A string used to identify the player who earned the achievement. (read-only)

@property(readonly, copy, nonatomic) NSString *playerID
Availability
  • Available in iOS 7.0 and later.
Declared In
GKAchievement.h

showsCompletionBanner

A Boolean value that states whether a banner is displayed when the achievement is completed.

@property(assign, nonatomic) BOOL showsCompletionBanner
Discussion

When an achievement is completed and the value of this property is YES, a notification banner is displayed to the player to inform them of the completed achievement. If the value of this property is NO, there is no visual indication that the achievement is completed. Your game should set this property to NO only when it wants to provide its own visual indicator that the achievement was earned. The default value is NO.

Availability
  • Available in iOS 5.0 and later.
Declared In
GKAchievement.h

Class Methods

loadAchievementsWithCompletionHandler:

Loads previously submitted achievement progress for the local player from Game Center.

+ (void)loadAchievementsWithCompletionHandler:(void (^)(NSArray *achievements, NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the download is completed.

The block receives the following parameters:

achievements

An array of GKAchievement objects that represents all progress reported to Game Center for the local player. If an error occurred, this parameter may be non-nil, in which case the array holds whatever achievement information Game Kit was able to fetch.

error

If an error occurred, this object describes the error. If the operation completed successfully, this value is nil.

Discussion

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
GKAchievement.h

reportAchievements:withCompletionHandler:

Reports progress on an array of achievements.

+ (void)reportAchievements:(NSArray *)achievements withCompletionHandler:(void (^)(NSError *error))completionHandler
Parameters
achievements

An array of GKAchievement objects that contains the achievements whose progress is being updated.

completionHandler

A block to be called after the operation completes.

The block takes the following parameter:

error

If the operation was successful, this value is nil; otherwise, this parameter holds an object that describes the problem that occurred.

Discussion

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

Use this class method whenever you need to submit multiple achievement updates at the same time. Calling this method reports each of the achievements, exactly as if you called the reportAchievementWithCompletionHandler: method on each achievement object in the array. However, the entire operation can be processed more efficiently using this method, and the completion handler is only called once.

Availability
  • Available in iOS 6.0 and later.
Declared In
GKAchievement.h

reportAchievements:withEligibleChallenges:withCompletionHandler:

Reports a list of achievements and limits the challenges those achievements may complete.

+ (void)reportAchievements:(NSArray *)achievements withEligibleChallenges:(NSArray *)challenges withCompletionHandler:(void (^)(NSError *error))completionHandler
Parameters
achievements

An array of GKAchievement objects that represents all achievements that are being reported.

challenges

An array of GKChallenge objects that represents the limited challenges that are associated with the reported achievements. If an error occurred, this parameter may be non-nil, in which case the array holds whatever challenge information Game Kit was able to fetch.

completionHandler

A block to be called when the download is completed.

The block receives the following parameter:

error

If an error occurred, this object describes the error. If the operation completed successfully, this value is nil.

Discussion

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKChallenge.h

resetAchievementsWithCompletionHandler:

Resets all achievement progress for the local player.

+ (void)resetAchievementsWithCompletionHandler:(void (^)(NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the reset action is completed.

The block takes the following parameter:

error

If the operation was successful, this value is nil; otherwise, this parameter holds an object that describes the problem that occurred.

Discussion

Calling this class method deletes all progress towards achievements previously reported for the local player. Hidden achievements that were previously visible are now hidden again.

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

Availability
  • Available in iOS 4.1 and later.
Related Sample Code
Declared In
GKAchievement.h

Instance Methods

challengeComposeControllerWithPlayers:message:completionHandler:

Provides a challenge compose view controller with pre-selected player identifiers and a message.

- (UIViewController *)challengeComposeControllerWithPlayers:(NSArray *)playerIDs message:(NSString *)message completionHandler:(GKChallengeComposeCompletionBlock)completionHandler
Parameters
playerIDs

An array of NSString objects that contains the player identifiers that the challenge is to be sent to.

message

The message that is sent to other players. This message can be edited by the player.

completionHandler

A block to be called after the view controller has been displayed. Contains the reason the handler was called and all player identifiers that the challenge was sent to.

Return Value

A UIViewController view that contains the player identifiers and the challenge message.

Discussion

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

The view controller returned is presented modally from the top view controller. After the view controller is displayed and the player sends or cancels the challenge, the completion handler block is called.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKChallenge.h

initWithIdentifier:

Initializes a new achievement object.

- (id)initWithIdentifier:(NSString *)identifier
Parameters
identifier

A string that matches the identifier string for an achievement you created for your game on iTunes Connect.

Return Value

An initialized achievement object, or nil if an error occurred.

Discussion

Your game initializes a new achievement object only when it has not previously reported progress for that achievement. If your game has previously reported progress on an achievement, you should first retrieve the current progress by calling the loadAchievementsWithCompletionHandler: class method.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
GKAchievement.h

initWithIdentifier:forPlayer:

Initializes an achievement for a specific player.

- (id)initWithIdentifier:(NSString *)identifier forPlayer:(NSString *)playerID
Parameters
identifier

A string that matches the identifier string for an achievement you created for your game on iTunes Connect.

player_ID

The identifier for the player associated with the specified achievement.

Discussion

Your game initializes a new achievement object for a specific player only when it has not previously reported progress for that achievement. Use this method to submit a participant’s achievement when ending a turn-based match.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKAchievement.h

selectChallengeablePlayerIDs:withCompletionHandler:

Finds the subset of players that can earn an achievement.

- (void)selectChallengeablePlayerIDs:(NSArray *)playerIDs withCompletionHandler:(void (^)(NSArray *challengeablePlayerIDs, NSError *error))completionHandler
Parameters
playerIDs

An array of NSString objects containing a list of players that. The list of players is used to find those players that are eligible to earn the achievement.

completionHandler

A block to be called when the download is completed.

The block receives the following parameters:

challengeablePlayerIDs

An array of player identifiers representing the players in the original array that are able to complete the challenge. If an error occurred, this parameter may be non-nil, in which case the array holds whatever achievement information Game Kit was able to fetch.

error

If an error occurred, this object describes the error. If the operation completed successfully, this value is nil.

Discussion

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

Availability
  • Available in iOS 6.0 and later.
Declared In
GKChallenge.h