GKLeaderboard 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
GKLeaderboard.h

Overview

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

Tasks

Determining the Available Leaderboards to Display

Initialization

Customizing the Leaderboard Request

Retrieving High Scores

Changing a Local Player’s Default Leaderboard

Retrieving Group Information

Properties

category

The named leaderboard to retrieve information from. (Deprecated. Use identifier property instead.)

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

groupIdentifier

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

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

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

loading

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

@property(readonly, getter=isLoading) BOOL loading
Discussion

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

localPlayerScore

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

maxRange

The size of the leaderboard. (read-only)

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

playerScope

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

range

The numerical score rankings to return from the search.

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

scores

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

timeScope

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

title

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

Class Methods

loadLeaderboardsWithCompletionHandler:

Loads the list of leaderboards from Game Center

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

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
GKLeaderboard.h

setDefaultLeaderboard:withCompletionHandler:

Sets the default leaderboard for the local player.

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

Instance Methods

init

Initializes a default leaderboard request.

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

initWithPlayerIDs:

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

loadImageWithCompletionHandler:

The the image associated with the default leaderboard.

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

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

loadScoresWithCompletionHandler:

Retrieves a set of scores from Game Center.

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

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

Constants

Leaderboard Time Scope

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

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

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

Available in OS X v10.8 and later.

Declared in GKLeaderboard.h.

GKLeaderboardTimeScopeWeek

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

Available in OS X v10.8 and later.

Declared in GKLeaderboard.h.

GKLeaderboardTimeScopeAllTime

Each player’s best score is returned.

Available in OS X v10.8 and later.

Declared in GKLeaderboard.h.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h

Leaderboard Player Scope

The scope of players to be searched for scores.

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

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

Available in OS X v10.8 and later.

Declared in GKLeaderboard.h.

GKLeaderboardPlayerScopeFriendsOnly

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

Available in OS X v10.8 and later.

Declared in GKLeaderboard.h.

Availability
  • Available in OS X v10.8 and later.
Declared In
GKLeaderboard.h