iOS Developer Library

Developer

GameKit Framework Reference GKChallenge Class Reference

Options
Deployment Target:

On This Page
Language:

GKChallenge

A GKChallenge object represents a challenge issued by a player to another player.

Players use the Game Center app to issue and view challenges. However, your game can also customize its challenge behaviors in a number of ways:

  • You can load the list of challenges issued to the local player by calling the loadReceivedChallengesWithCompletionHandler: class method. For example, you might do this to display the challenges in your game’s user interface.

  • Your app can issue challenges using a GKScore or GKAchievement object. Your game should only issue challenges when the local player initiates the action in your user interface.

  • Your game can be notified when new challenge events are received. See GKChallengeEventHandlerDelegate.

Subclassing Notes

You never subclass the GKChallenge class directly. However, subclasses of GKChallenge represent specific kinds of challenges. Two challenge types exist:

  • A GKScoreChallenge is a challenge to beat a score the local player earned in a leaderboard.

  • A GKAchievementChallenge is a challenge to complete an achievement that the local player has already completed.

Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 6.0 and later.
  • Loads the list of outstanding challenges.

    Declaration

    Swift

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

    Objective-C

    + (void)loadReceivedChallengesWithCompletionHandler:(void (^)(NSArray *challenges, NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called when the download is completed.

    The block receives the following parameters:

    challenges

    An array of GKChallenge objects that represents all challenges made to the local player. 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.

    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.

  • issueDate issueDate Property

    The date the challenge was issued. (read-only)

    Declaration

    Swift

    var issueDate: NSDate! { get }

    Objective-C

    @property(nonatomic, readonly, retain) NSDate *issueDate

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

  • issuingPlayerID issuingPlayerID (iOS 8.0) Property

    The player who issued the challenge. (read-only)

    Declaration

    Swift

    var issuingPlayerID: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

    Deprecated in iOS 8.0.

  • The player who received the challenge. (read-only)

    Declaration

    Swift

    var receivingPlayerID: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

    Deprecated in iOS 8.0.

  • The GKPlayer object associated with the player who issued the challenge. (read-only)

    Declaration

    Swift

    @NSCopying var issuingPlayer: GKPlayer! { get }

    Objective-C

    @property(nonatomic, readonly, copy) GKPlayer *issuingPlayer

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • The GKPlayer object associated with the player who received the challenge. (read-only)

    Declaration

    Swift

    @NSCopying var receivingPlayer: GKPlayer! { get }

    Objective-C

    @property(nonatomic, readonly, copy) GKPlayer *receivingPlayer

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • message message Property

    A text message that describes the challenge. (read-only)

    Declaration

    Swift

    var message: String! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

  • state state Property

    The current state of the challenge. (read-only)

    Declaration

    Swift

    var state: GKChallengeState { get }

    Objective-C

    @property(nonatomic, readonly, assign) GKChallengeState state

    Discussion

    See Challenge State for possible values.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

  • The date the challenge was completed. (read-only)

    Declaration

    Swift

    var completionDate: NSDate! { get }

    Objective-C

    @property(nonatomic, readonly, retain) NSDate *completionDate

    Discussion

    If the challenge is not complete, this value is nil.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

  • Declines a challenge.

    Declaration

    Swift

    func decline()

    Objective-C

    - (void)decline

    Discussion

    If your game implements a custom user interface to display challenges, it should include controls that allow a player to decline a challenge. If the player uses your user interface to decline a challenge, call this method.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

Data Types

  • Completion block that determines if a challenge has been issued and if so, who it is sent to.

    Declaration

    Swift

    typealias GKChallengeComposeCompletionBlock = (UIViewController!, Bool, [AnyObject]!) -> Void

    Objective-C

    typedef void (^GKChallengeComposeCompletionBlock)(UIViewController *composeController, BOOL didIssueChallenge, NSArray *sentPlayerIDs);

    Discussion

    The block parameters are defined as follows:

    composeController

    View controller for the challenge.

    didIssueChallenge

    Boolean variable designating if the challenge was sent out.

    sentPlayerIDs

    An array of NSString objects containing the player identifiers that the challenge was sent to.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

  • Possible states that a challenge can live in.

    Declaration

    Swift

    enum GKChallengeState : Int { case Invalid case Pending case Completed case Declined }

    Objective-C

    typedef enum GKChallengeState { GKChallengeStateInvalid = 0, GKChallengeStatePending = 1, GKChallengeStateCompleted = 2, GKChallengeStateDeclined = 3, };

    Constants

    • Invalid

      GKChallengeStateInvalid

      An error occurred. The state of this challenge is not valid.

      Available in iOS 6.0 and later.

    • Pending

      GKChallengeStatePending

      The challenge has been issued, but is not yet completed nor declined.

      Available in iOS 6.0 and later.

    • Completed

      GKChallengeStateCompleted

      The receiving player successfully completed the challenge.

      Available in iOS 6.0 and later.

    • Declined

      GKChallengeStateDeclined

      The receiving player declined the challenge.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.