iOS Developer Library

Developer

GameKit Framework Reference GKAchievement Class Reference

Options
Deployment Target:

On This Page
Language:

GKAchievement

Inheritance


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later.

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

Achievements are a great way to provide your players with feedback and a sense of accomplishment. However, you can’t just add an achievement to your game programmatically. There are several steps that you must accomplish to add achievements to your game:

  1. Before you add achievements, add code to authenticate the local player. See Working with Players in Game Center.

  2. Design your game’s achievements. See Designing an Achievement.

  3. Go to iTunes Connect and configure the achievements for your game. You provide all of the data needed to display achievements to the player. See Configuring Achievements in iTunes Connect.

  4. Add code to report the local player’s progress to Game Center. By storing the progress on Game Center, you also make the player’s progress visible in the Game Center app. 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 reportAchievements:withCompletionHandler: class method. Use this method when reporting one or multiple achievements.

  5. Add code to load the local player’s previous progress on achievements from Game Center. To request the local player’s progress on achievements, call the loadAchievementsWithCompletionHandler: class method. Load the local player’s progress shortly after the player is successfully authenticated.

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 NOfalse before reporting the player’s progress.

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

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

    Declaration

    Swift

    class func loadAchievementsWithCompletionHandler(_ completionHandler: (([AnyObject]!, NSError!) -> Void)!)

    Objective-C

    + (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. Listing 1 shows an example of how to load the local player’s achievements.

    Listing 1Loading achievement progress
    • - (void) loadAchievements
    • { [GKAchievement loadAchievementsWithCompletionHandler:^(NSArray *achievements, NSError *error) {
    • if (error != nil)
    • {
    • NSLog(@"Error in loading achievements: %@", error);
    • }
    • if (achievements != nil)
    • {
    • // Process the array of achievements.
    • }
    • }];
    • }

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • Initializes a new achievement object for the local player.

    Declaration

    Swift

    init!(identifier identifier: String!)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • Initializes an achievement object for a specific player.

    Declaration

    Swift

    init!(identifier identifier: String!, player player: GKPlayer!)

    Objective-C

    - (instancetype)initWithIdentifier:(NSString *)identifier player:(GKPlayer *)player

    Parameters

    identifier

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

    player

    A GKPlayer object that identifies the player associated with the specified achievement.

    Return Value

    An initialized achievement object associated with a specific GKPlayer object, or nil if an error occurred.

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var identifier: String!

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var percentComplete: Double

    Objective-C

    @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. You decide how that percentage is calculated and when it changes. For example, if the player earns an achievement simply for discovering a location in your game, then you would simply report the achievement as 100 percent complete the first time you report progress to Game Center. On the other hand, for an achievement like “Capture 10 pirates”, your reporting mechanism increments by 10 percent each time the player captures a pirate.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • completed completed Property

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

    Declaration

    Swift

    var completed: Bool { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    @NSCopying var lastReportedDate: NSDate! { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • Reports progress on an array of achievements.

    Declaration

    Swift

    class func reportAchievements(_ achievements: [AnyObject]!, withCompletionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    + (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

    Use this class method whenever you need to submit one or more achievement updates at the same time. Calling this method reports each of the achievements in the array. Processing multiple achievements at once allows the entire operation to be processed more efficiently using this method as the completion handler is only called once. Reporting progress on an achievement shows an example of how to report a single achievement.

    Listing 2Reporting progress on an achievement
    • - (void) reportAchievementIdentifier: (NSString*) identifier percentComplete: (float) percent
    • {
    • GKAchievement *achievement = [[GKAchievement alloc] initWithIdentifier: identifier];
    • if (achievement)
    • {
    • achievement.percentComplete = percent;
    • [GKAchievement reportAchievements:@[achievement] withCompletionHandler:^(NSError *error)
    • {
    • if (error != nil)
    • {
    • NSLog(@"Error in reporting achievements: %@", error);
    • }
    • }];
    • }
    • }

    Listing 3 shows an example of how to report multiple achievements for the local player.

    Listing 3Reporting progress on multiple achievements
    • - (void) completeMultipleAchievements
    • {
    • GKAchievement *achievement1 = [[GKAchievement alloc] initWithIdentifier: @"DefeatedFinalBoss"];
    • GKAchievement *achievement2 = [[GKAchievement alloc] initWithIdentifier: @"FinishedTheGame"];
    • GKAchievement *achievement3 = [[GKAchievement alloc] initWithIdentifier: @"PlayerIsAwesome"];
    • achievement1.percentComplete = 100.0;
    • achievement2.percentComplete = 100.0;
    • achievement3.percentComplete = 100.0;
    • NSArray *achievementsToComplete = @[achievement1,achievement2,achievement3];
    • [GKAchievement reportAchievements: achievementsToComplete withCompletionHandler:^(NSError *error)
    • {
    • if (error != nil)
    • {
    • NSLog(@"Error in reporting achievements: %@", error);
    • }
    • }];
    • }
    • }

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    class func reportAchievements(_ achievements: [AnyObject]!, withEligibleChallenges challenges: [AnyObject]!, withCompletionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var showsCompletionBanner: Bool

    Objective-C

    @property(assign, nonatomic) BOOL showsCompletionBanner

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 5.0 and later.

  • Resets all achievement progress for the local player.

    Declaration

    Swift

    class func resetAchievementsWithCompletionHandler(_ completionHandler: ((NSError!) -> Void)!)

    Objective-C

    + (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. Listing 4 shows an example of how to reset your game’s achievements.

    Listing 4Resetting achievement progress
    • - (void) resetAchievements
    • {
    • [GKAchievement resetAchievementsWithCompletionHandler:^(NSError *error)
    • {
    • if (error != nil)
    • NSLog(@"Could not reset achievements due to %@", error);
    • }];
    • }

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later.

  • Provides a challenge compose view controller with a preformatted message for the achievement and pre-selected GKPlayer objects.

    Declaration

    Swift

    func challengeComposeControllerWithMessage(_ message: String!, players players: [AnyObject]!, completionHandler completionHandler: GKChallengeComposeCompletionBlock!) -> UIViewController!

    Objective-C

    - (UIViewController *)challengeComposeControllerWithMessage:(NSString *)message players:(NSArray *)players completionHandler:(GKChallengeComposeCompletionBlock)completionHandler

    Parameters

    message

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

    players

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

    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

    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.

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • Finds the subset of players that can earn an achievement.

    Declaration

    Swift

    func selectChallengeablePlayers(_ players: [AnyObject]!, withCompletionHandler completionHandler: (([AnyObject]!, NSError!) -> Void)!)

    Objective-C

    - (void)selectChallengeablePlayers:(NSArray *)players withCompletionHandler:(void (^)(NSArray *challengeablePlayers, NSError *error))completionHandler

    Parameters

    players

    An array of GKPlayer objects containing a list of players. 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:

    challengeablePlayers

    An array of GKPlayer objects 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. Listing 5 shows how to find the players eligible to be challenged to complete an achievement.

    Listing 5Determining the list of players who can complete an achievement challenge
    • - (void) challengePlayersToCompleteAchievement: (GKAchievement*) achievement
    • {
    • [achievement selectChallengeablePlayers:[GKLocalPlayer localPlayer].friends withCompletionHandler:^(NSArray *challengeablePlayers, NSError *error) {
    • if (challengeablePlayers)
    • {
    • //send a challenge to each of the eligible players.
    • }
    • }];
    • }

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • player player Property

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

    Declaration

    Swift

    var player: GKPlayer! { get }

    Objective-C

    @property(readonly, retain, nonatomic) GKPlayer *player

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    func challengeComposeControllerWithPlayers(_ playerIDs: [AnyObject]!, message message: String!, completionHandler completionHandler: GKChallengeComposeCompletionBlock!) -> UIViewController!

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

    Deprecated in iOS 8.0.

  • hidden hidden (iOS 6.0) Property

    A Boolean value that states whether this achievement is normally kept secret from the player. (read-only)

    Deprecation Statement

    Use the hidden property on the GKAchievementDescription class instead.

    Declaration

    Objective-C

    @property(assign, getter=isHidden, readonly, nonatomic) BOOL hidden

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 6.0.

  • Initializes an achievement for a specific player.

    Declaration

    Swift

    init!(identifier identifier: String!, forPlayer player_ID: String!)

    Objective-C

    - (instancetype)initWithIdentifier:(NSString *)identifier forPlayer:(NSString *)player_ID

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

    Deprecated in iOS 8.0.

  • Issue an achievement challenge to a list of players.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 6.0 and later.

    Deprecated in iOS 7.0.

  • playerID playerID (iOS 8.0) Property

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

    Declaration

    Swift

    var playerID: String! { get }

    Objective-C

    @property(readonly, copy, nonatomic) NSString *playerID

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

    Deprecated in iOS 8.0.

  • Reports the player’s progress to Game Center.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 7.0.

  • Finds the subset of players that can earn an achievement.

    Declaration

    Swift

    func selectChallengeablePlayerIDs(_ playerIDs: [AnyObject]!, withCompletionHandler completionHandler: (([AnyObject]!, NSError!) -> Void)!)

    Objective-C

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

    Parameters

    playerIDs

    An array of NSString objects containing a list of players. 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

    Deprecated in iOS 8.0.