iOS Developer Library

Developer

GameKit Framework Reference GKLeaderboard Class Reference

Options
Deployment Target:

On This Page
Language:

GKLeaderboard

Inherits From


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later

A GKLeaderboard object is used to read data from a leaderboard stored on Game Center. Your game uses GKLeaderboard objects when it wants to retrieve localized information about a specific leaderboard or to retrieve scores from a leaderboard. Typically, you do this when you want the data needed to implement your own custom leaderboard user interface.

During the development process, you create the leaderboards for your game on iTunes Connect.

To retrieve information about the available leaderboards, use the loadLeaderboardsWithCompletionHandler: class method.

To request score data from Game Center, your game allocates and initializes a GKLeaderboard object, configures its search properties, and then calls the object’s loadScoresWithCompletionHandler: method. Game Kit retrieves the score data from Game Center and calls your completion handler.

The search properties are used to filter the score data returned to your game:

  • The category property allows you to choose which leaderboard on iTunes Connect is searched.

  • The playerScope property allows you to restrict the search to a local player’s friends. Optionally, you can also explicitly initialize a leaderboard object to search for scores for a specific group of players.

  • The timeScope property allows you to filter based on when the score was earned.

  • The range property allows you to pick scores within a specific range. For example, the range [1,10] returns the best ten scores.

The algorithm used by the GKLeaderboard object is as follows:

  1. Start with the set of all possible scores.

  2. Discard any scores that do not match the playerScope, timeScope and category properties.

  3. For each player, keep the best score that player has earned and discard the rest.

  4. Sort the scores from best to worst.

  5. Use the range property to determine which scores are returned.

  • Loads the list of leaderboards from Game Center

    Declaration

    Swift

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

    Objective-C

    + (void)loadLeaderboardsWithCompletionHandler:(void (^)(NSArray *leaderboards, NSError *error))completionHandler

    Parameters

    completionHandler

    A block that is called when the categories have been retrieved from the server.

    The block receives the following parameters:

    leaderboards

    An array of GKLeaderboard objects that provides the leaderboards for your game. If an error occurred, this value may be non-nil. In this case, the array holds whatever data Game Kit was able to download before the error occurred.

    error

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

    Discussion

    Use this class method to retrieve the list of leaderboards you configured on iTunes Connect. Use the properties of each leaderboard object, especially the category and title properties, to learn more about the leaderboard.

    Listing 1Retrieving information about available leaderboards
    • - (void) loadLeaderboardInfo
    • {
    • [GKLeaderboard loadLeaderboardsWithCompletionHandler:^(NSArray *leaderboards, NSError *error) {
    • self.leaderboards = leaderboards;
    • }];
    • }

    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

  • Loads the list of leaderboard categories along with their corresponding localized titles.

    Deprecation Statement

    Use the loadLeaderboardsWithCompletionHandler: method instead.

    Declaration

    Objective-C

    + (void)loadCategoriesWithCompletionHandler:(void (^)(NSArray *categories, NSArray *titles, NSError *error))completionHandler

    Parameters

    completionHandler

    A block that is called when the categories have been retrieved from the server.

    The block receives the following parameters:

    categories

    An array of NSString objects that provides the categories to your game. If an error occurred, this value may be non-nil. In this case, the array holds whatever data Game Kit was able to download before the error occurred.

    titles

    An array of NSString objects that provides localized titles for each category. If an error occurred, this value may be non-nil. In this case, the array holds whatever data Game Kit was able to download before the error occurred.

    error

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

    Discussion

    You use this class method to retrieve the category identifiers and titles you configured for your leaderboards on iTunes Connect. To create a leaderboard query that targets a particular category, set the category property to one of the strings returned by this method.

    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;

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 6.0

  • Initializes a default leaderboard request.

    Declaration

    Swift

    init!()

    Objective-C

    - (instancetype)init

    Return Value

    An initialized leaderboard request.

    Discussion

    A leaderboard object initialized with this method uses the playerScope, timeScope, and range properties to search Game Center for scores.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • Initializes a leaderboard request to retrieve the scores of a specific group of players.

    Declaration

    Swift

    init!(playerIDs playerIDs: [AnyObject]!)

    Objective-C

    - (instancetype)initWithPlayerIDs:(NSArray *)playerIDs

    Parameters

    playerIDs

    An array of NSString objects that holds the player identifier strings of the players to retrieve.

    Return Value

    An initialized leaderboard request.

    Discussion

    A leaderboard object initialized with this method ignores the playerScope and range properties. Instead, it retrieves scores for the specific list of players whose identifiers are included in the playerIDs parameter.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 8.0

  • Initializes a leaderboard request to retrieve the scores of a specific group of players.

    Declaration

    Swift

    init!(players players: [AnyObject]!)

    Objective-C

    - (instancetype)initWithPlayers:(NSArray *)players

    Parameters

    players

    An array of GKPlayer objects that holds the player identifiers to be retrieved.

    Return Value

    An initialized leaderboard request.

    Discussion

    A leaderboard object initialized with this method ignores the playerScope and range properties. Instead, it retrieves scores for the specific list of players whose GKPlayer objects are included in the players parameter.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • A filter used to restrict the search to a subset of the players on Game Center.

    Declaration

    Swift

    var playerScope: GKLeaderboardPlayerScope

    Objective-C

    @property(assign, nonatomic) GKLeaderboardPlayerScope playerScope

    Discussion

    The playerScope property is ignored if the leaderboard request was initialized using the initWithPlayerIDs: method. Otherwise, the playerScope property determines which players are included in the request for high scores. The default is GKLeaderboardPlayerScopeGlobal. See Leaderboard Player Scope for more information.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • range range Property

    The numerical score rankings to return from the search.

    Declaration

    Swift

    var range: NSRange

    Objective-C

    @property(assign, nonatomic) NSRange range

    Discussion

    The range property is ignored if the leaderboard request was initialized using the initWithPlayerIDs: method. Otherwise, the range property is used to filter which scores are returned to your game. For example, if you specified a range of [1,10], after the search is complete, your game receives the best ten scores. The default range is [1,25].

    The minimum index is 1. The maximum length is 100.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • timeScope timeScope Property

    A filter used to restrict the search to scores that were posted within a specific period of time.

    Declaration

    Swift

    var timeScope: GKLeaderboardTimeScope

    Objective-C

    @property(assign, nonatomic) GKLeaderboardTimeScope timeScope

    Discussion

    This property determines how far back in time to look for scores. The default value is GKLeaderboardTimeScopeAllTime. See Leaderboard Time Scope for more information.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • The named leaderboard to retrieve information from.

    Declaration

    Swift

    var identifier: String!

    Objective-C

    @property(copy, nonatomic) NSString *identifier

    Discussion

    If non-nil, Game Center only returns scores from the matching leaderboard. If nil, all scores previously reported by the game are searched. Default is nil.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later

  • category category (iOS 7.0) Property

    The named leaderboard to retrieve information from.

    Deprecation Statement

    Use identifier property instead.

    Declaration

    Objective-C

    @property(copy, nonatomic) NSString *category

    Discussion

    If non-nil, Game Center only returns scores from the matching leaderboard. If nil, all scores previously reported by the game are searched. Default is nil.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 7.0

  • The the image associated with the default leaderboard.

    Declaration

    Swift

    func loadImageWithCompletionHandler(_ completionHandler: ((UIImage!, NSError!) -> Void)!)

    Objective-C

    - (void)loadImageWithCompletionHandler:(void (^)(UIImage *image, NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called after the scores are retrieved from the server.

    The block receives the following parameters:

    image

    Contains the image associated with the leaderboard.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the 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

  • Retrieves a set of scores from Game Center.

    Declaration

    Swift

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

    Objective-C

    - (void)loadScoresWithCompletionHandler:(void (^)(NSArray *scores, NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called after the scores are retrieved from the server.

    The block receives the following parameters:

    scores

    An array of GKScore objects that holds the requested scores. If an error occurred, this value may be non-nil. In this case, the array holds whatever score data could be retrieved from Game Center before the error occurred.

    error

    If an error occurred, this error object describes the error. If the operation was completed successfully, the 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 2 shows an example leaderboard data query. The method for this query initializes a new leaderboard object and configures the playerScope, timeScope, and range properties to grab the top ten scores earned today.

    Listing 2Retrieving the top ten scores
    • - (void) retrieveTopTenScores
    • {
    • GKLeaderboard *leaderboardRequest = [[GKLeaderboard alloc] init];
    • if (leaderboardRequest != nil)
    • {
    • leaderboardRequest.playerScope = GKLeaderboardPlayerScopeGlobal;
    • leaderboardRequest.timeScope = GKLeaderboardTimeScopeToday;
    • leaderboardRequest.identifier = @"Combined.LandMaps"
    • leaderboardRequest.range = NSMakeRange(1,10);
    • [leaderboardRequest loadScoresWithCompletionHandler: ^(NSArray *scores, NSError *error) {
    • if (error != nil)
    • {
    • // Handle the error.
    • }
    • if (scores != nil)
    • {
    • // Process the score information.
    • }
    • }];
    • }
    • }

    You can create a leaderboard request that retrieves scores for a specific list of players you are interested in.

    Listing 3Retrieving the top scores for players in a match
    • - (void) receiveMatchBestScores: (GKMatch*) match
    • {
    • GKLeaderboard *leaderboardRequest = [[GKLeaderboard alloc] initWithPlayers: match.players];
    • leaderboardRequest.timeScope = GKLeaderboardTimeScopeAllTime;
    • leaderboardRequest.identifier = @"Combined.LandMaps"
    • leaderboardRequest.range = NSMakeRange(1,10);
    • if (query != nil)
    • {
    • [query loadScoresWithCompletionHandler: ^(NSArray *scores, NSError *error) {
    • if (error != nil)
    • {
    • // Handle the error.
    • }
    • if (scores != nil)
    • {
    • // Process the score information.
    • }
    • }];
    • }
    • }

    You can call this method multiple times; each call represents a different query against the scores stored on Game Center. If you post multiple load operations using the same leaderboard object, any properties that are updated by loading scores reflect the last query that completed. The order that achievement queries are processed is arbitrary.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • loading loading Property

    A Boolean value that indicates whether the leaderboard object is retrieving scores. (read-only)

    Declaration

    Swift

    var loading: Bool { get }

    Objective-C

    @property(readonly, getter=isLoading) BOOL loading

    Discussion

    The value of the loading property is YEStrue if the leaderboard object has any pending requests for scores.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

  • title title Property

    The localized title for the leaderboard. (read-only)

    Declaration

    Swift

    var title: String! { get }

    Objective-C

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

    Discussion

    If you initialized a new leaderboard object, this property is invalid until a call to loadScoresWithCompletionHandler: is complete. Afterward, it contains the localized title for the leaderboard identified by the category property.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

  • scores scores Property

    An array of GKScore objects that contains the scores returned by the search. (read-only)

    Declaration

    Swift

    var scores: [AnyObject]! { get }

    Objective-C

    @property(readonly, retain, nonatomic) NSArray *scores

    Discussion

    This property is invalid until a call to loadScoresWithCompletionHandler: is complete. Afterward, it contains the same score objects that were returned to the completion handler.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • The score earned by the local player. (read-only)

    Declaration

    Swift

    var localPlayerScore: GKScore! { get }

    Objective-C

    @property(readonly, retain, nonatomic) GKScore *localPlayerScore

    Discussion

    This property is invalid until a call to loadScoresWithCompletionHandler: is completed. Afterward, it contains a score object representing the local player’s score on the leaderboard given the filters you applied to the query.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • maxRange maxRange Property

    The size of the leaderboard. (read-only)

    Declaration

    Swift

    var maxRange: Int { get }

    Objective-C

    @property(readonly, assign, nonatomic) NSUInteger maxRange

    Discussion

    This property is invalid until a call to loadScoresWithCompletionHandler: is completed. Afterward, it contains the total number of entries available to return to your game given the filters you applied to the query.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • Sets the default leaderboard for the local player.

    Declaration

    Objective-C

    + (void)setDefaultLeaderboard:(NSString *)leaderboardIdentifier withCompletionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    leaderboardIdentifier

    The named leaderboard that should be the new default leaderboard for the local player.

    completionHandler

    A block to be called after the scores are retrieved from the server.

    The block receives the following parameter:

    error

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

    Discussion

    The default leaderboard is used whenever your game uses a GKScore object to report a score to Game Center without explicitly setting the score object’s category property. The default leaderboard is normally set in iTunes Connect. However, your game can use this class method to override the default leaderboard that appears for the local player. This information is stored for each player on Game Center.

    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.

    If an error occurs and was a network error, your game should periodically resend the request until it completes.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 5.0 and later

    Deprecated in iOS 7.0

  • The identifier for the group the leaderboard is part of. (read-only)

    Declaration

    Swift

    var groupIdentifier: String! { get }

    Objective-C

    @property(nonatomic, readonly, retain) NSString *groupIdentifier

    Discussion

    If your game was configured to be part of a group in iTunes Connect, this property holds the identifier you assigned to the group.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later

Data Types

  • The period of time to which a player’s best score is restricted.

    Declaration

    Swift

    enum GKLeaderboardTimeScope : Int { case Today case Week case AllTime }

    Objective-C

    enum { GKLeaderboardTimeScopeToday = 0, GKLeaderboardTimeScopeWeek, GKLeaderboardTimeScopeAllTime }; typedef NSInteger GKLeaderboardTimeScope;

    Constants

    • Today

      GKLeaderboardTimeScopeToday

      Each player is restricted to scores recorded in the past 24 hours.

      Available in iOS 4.0 and later

    • Week

      GKLeaderboardTimeScopeWeek

      Each player is restricted to scores recorded in the past week.

      Available in iOS 4.0 and later

    • AllTime

      GKLeaderboardTimeScopeAllTime

      Each player’s best score is returned.

      Available in iOS 4.0 and later

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • The scope of players to be searched for scores.

    Declaration

    Swift

    enum GKLeaderboardPlayerScope : Int { case Global case FriendsOnly }

    Objective-C

    enum { GKLeaderboardPlayerScopeGlobal = 0, GKLeaderboardPlayerScopeFriendsOnly }; typedef NSInteger GKLeaderboardPlayerScope;

    Constants

    • Global

      GKLeaderboardPlayerScopeGlobal

      All players on Game Center should be considered when generating the list of scores.

      Available in iOS 4.0 and later

    • FriendsOnly

      GKLeaderboardPlayerScopeFriendsOnly

      Only friends of the local player should be considered when generating the list of scores.

      Available in iOS 4.0 and later

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later