GKAchievement Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in OS X v10.8 and later.
Companion guide
Declared in
GKAchievement.h
GKChallenge.h

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

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 OS X v10.8 and later.
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 OS X v10.8 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 OS X v10.8 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 OS X v10.8 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 OS X v10.8 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 OS X v10.8 and later.
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 OS X v10.9 and later.
Declared In
GKAchievement.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 OS X v10.8 and later.
Declared In
GKAchievement.h

Instance Methods

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 OS X v10.8 and later.
Declared In
GKAchievement.h

issueChallengeToPlayers:message:

Issue an achievement challenge to a list of players.

- (void)issueChallengeToPlayers:(NSArray *)playerIDs message:(NSString *)message
Parameters
playerIDs

An array of NSString objects containing the player identifiers of the players being challenged.

message

A text message to display to the challenged players.

Discussion

This method should be used only to implement your own custom challenge user interface. You should only issue challenges when the local player directs you to do so.

If the achievement is marked as hidden in iTunes Connect, or if the challenged player has already earned the achievement and it is not marked as replayable, then the challenge is not issued.

Availability
  • Available in OS X v10.9 and later.
Declared In
GKChallenge.h

reportAchievementWithCompletionHandler:

Reports the player’s progress to Game Center.

- (void)reportAchievementWithCompletionHandler:(void (^)(NSError *error))completionHandler
Parameters
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 the player makes progress towards completing an achievement, your game communicates the player’s progress to Game Center by calling this method. An achievement object is implicitly tied to the local player that was authenticated when the object was created; your game should only report progress when the same local player is still authenticated on the device.

When the progress is successfully reported, the achievement is made visible if it was previously hidden. The percentComplete and lastReportedDate property values stored on Game Center are updated if the new percentComplete value is greater than the value previously stored on Game Center. if the value of the percentComplete property was equal to 100.0, then the achievement is marked as completed and a banner may be shown to the player.

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. The background task automatically handles network errors, resending the data until the task completes. When the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

Availability
  • Available in OS X v10.8 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 OS X v10.9 and later.
Declared In
GKChallenge.h