GKLocalPlayer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 4.1 and later.
Companion guide
Declared in
GKLocalPlayer.h
Related sample code

Overview

The GKLocalPlayer class is a special subclass of GKPlayer that represents the authenticated player running your game on the device. At any given time, only one player may be authenticated on the device; this player must log out before another player can log in.

Your game must authenticate the local player before using any Game Center features. Authenticating the player ensures that the player has created an account and is connected to Game Center. To authenticate the local player, retrieve the shared instance of the local player by calling the localPlayer class method and set its authenticateHandler property.

You can see whether the local player is authenticated by reading the authenticated property. If authenticated is YES, then the local player’s other properties are valid, and you can call other Game Center methods.

Call the loadFriendsWithCompletionHandler: method to retrieve the player identifiers for the local player’s friends.

Tasks

Accessing the Shared Local Player

Authentication

Accessing Friends

Determining If the Player Is Underage

Working with Leaderboards

Registering Listeners

Properties

authenticated

A Boolean value that indicates whether a local player is currently signed in to Game Center. (read-only)

@property(readonly, getter=isAuthenticated, nonatomic) BOOL authenticated
Availability
  • Available in iOS 4.0 and later.
Declared In
GKLocalPlayer.h

authenticateHandler

A handler called to process an authentication-related event.

@property(nonatomic, copy) void (^authenticateHandler)(UIViewController *viewController, NSError *error)
Parameters
viewController

This parameter is nil if the authentication process is complete. Otherwise, it contains a view controller that your game should display to the player.

Important: If you are targeting OS X, then this view controller is an NSViewController object.

error

This parameter contains an error object that describes any error that occurred.

Discussion

Your game should authenticate the player as early as possible after launching, ideally as soon as you can present a user interface to the player. For example, your game may be launched because the player accepted an invitation to join a match or to take a turn in a turn-based match, so you want your game to authenticate the player and process the match invitation as quickly as possible. After you set a handler, authentication begins automatically and is repeated when your game moves to the background and then back to the foreground.

During the authentication process, Game Kit calls your handler one or more times to handle specific authentication events. Your handler must handle three kinds of events:

  • If the device does not have an authenticated player, Game Kit passes a view controller to your authenticate handler. When presented, this view controller displays the authentication user interface. Your game should pause other activities that require user interaction (such as your game loop), present this view controller and then return. When the player finishes interacting with it, the view controller is dismissed automatically.

  • If the authentication process succeeded, the GKLocalPlayer singleton object’s authenticated property is set to YES and the object’s other properties are set to match those of the connected player.

  • If the authentication process failed, the GKLocalPlayer singleton object’s authenticated property is set to NO and the object’s other properties are cleared.

Each time the authentication handler is called, the data stored in the local player singleton object may have changed. A new player may have logged into the device or the player may have simply logged out from Game Center. Because of both of these possibilities, your authentication handler must be prepared to update any other objects that assume that a particular player is logged in. For more information, see “Authenticating the Local Player in a Multitasking App” in Game Center Programming Guide.

Availability
  • Available in iOS 6.0 and later.
Declared In
GKLocalPlayer.h

friends

An array of NSString objects containing the player identifiers for the local player’s friends. (read-only)

@property(nonatomic, readonly, retain) NSArray *friends
Discussion

This property is invalid until a call to loadFriendsWithCompletionHandler: succeeds.

Availability
  • Available in iOS 4.0 and later.
Declared In
GKLocalPlayer.h

underage

A Boolean value that declares whether the local player is underage. (read-only)

@property(readonly, getter=isUnderage, nonatomic) BOOL underage
Discussion

Some Game Center features are disabled if the local player is underage. Your game can also test this property if it wants to disable some of its own features based on the player’s age.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKLocalPlayer.h

Class Methods

localPlayer

Retrieves the shared instance of the local player.

+ (GKLocalPlayer *)localPlayer
Return Value

The local player object.

Discussion

You never directly create a local player object. Instead, you retrieve the singleton object by calling this class method.

Availability
  • Available in iOS 4.0 and later.
Declared In
GKLocalPlayer.h

Instance Methods

generateIdentityVerificationSignatureWithCompletionHandler:

Generates a signature that allows a third party server to authenticate the local player.

- (void)generateIdentityVerificationSignatureWithCompletionHandler:(void (^)(NSURL *publicKeyUrl, NSData *signature, NSData *salt, uint64_t timestamp, NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the request completes.

The block receives the following parameters:

publicKeyUrl

The URL for the public encryption key.

signature

The verification signature data generated.

salt

A random NSString used to compute the hash and keep it randomized.

timestamp

The date and time that the signature was created.

error

If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter 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.

Invoke this method to verify the identity of the local player. Use the following steps to generate a signature on your server:

  1. Call [GKLocalPlayer generateIdentityVerificationSignatureWithCompletionHandler] in your app.

  2. Send the publicKeyURL, signature, salt, and timestamp parameters to the third party server used for authentication.

  3. Use the publicKeyURL on the third party server to download the public key.

  4. Verify with the appropriate signing authority that the public key is signed by Apple.

  5. Retrieve the player’s playerID and bundleID.

  6. Concatenate into a data buffer the following information, in the order listed:

    • The playerID parameter in UTF-8 format

    • The bundleID parameter in UTF-8 format

    • The timestamp parameter in Big-Endian UInt-64 format

    • The salt parameter

  7. Generate a SHA-1 hash value for the buffer.

  8. Using the public key downloaded in step 3, verify that the hash value generated in step 7 matches the signature parameter provided by the API.

If the generated and retrieved signatures match, the local player has been authenticated.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKLocalPlayer.h

loadDefaultLeaderboardIdentifierWithCompletionHandler:

Loads the category identifier for the local player’s default leaderboard.

- (void)loadDefaultLeaderboardIdentifierWithCompletionHandler:(void (^)(NSString *leaderboardIdentifier, NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the request completes.

The block receives the following parameters:

categoryID

The category ID string for the local player’s default leaderboard.

error

If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter 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 iOS 7.0 and later.
Declared In
GKLocalPlayer.h

loadFriendsWithCompletionHandler:

Retrieves a list of player identifiers for the local player’s friends.

- (void)loadFriendsWithCompletionHandler:(void (^)(NSArray *friendIDs, NSError *error))completionHandler
Parameters
completionHandler

A block to be called when the request completes.

The block receives the following parameters:

friendIDs

An array of NSString objects containing the player identifiers for the players that are friends of the local player. If an error occurred, this value can be non-nil. In that case, the array contains the data that Game Kit was able to download before the error occurred.

error

If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter 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.

Once this call is completed, the friends property of the shared local player object is set to the same list of players returned in the completion handler.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
GKLocalPlayer.h

registerListener:

Register a listener for a particular event.

- (void)registerListener:(id<GKLocalPlayerListener>)listener
Parameters
listener

The GKLocalPlayerListener object containing the selector information to listen to.

Discussion

Only register a listener a single time. Registering a listener multiple times will result in undefined behavior.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKLocalPlayer.h

setDefaultLeaderboardIdentifier:completionHandler:

Sets the default leaderboard for the current game.

- (void)setDefaultLeaderboardIdentifier:(NSString *)leaderboardIdentifier completionHandler:(void (^)(NSError *error))completionHandler
Parameters
leaderboardIdentifier

The identifier of the leaderboard to be set as the default leaderboard.

completionHandler

A block to be called when the request completes.

The block receives the following parameters:

error

If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter 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.

The default leaderboard is configured in iTunes Connect as part of configuring your game’s leaderboards. All players normally start with this leaderboard as the default leaderboard. Calling this method changes the default leaderboard only for the local player.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKLocalPlayer.h

unregisterAllListeners

Unregister all listeners in your game.

- (void)unregisterAllListeners
Availability
  • Available in iOS 7.0 and later.
Declared In
GKLocalPlayer.h

unregisterListener:

Unregister a specific listener.

- (void)unregisterListener:(id<GKLocalPlayerListener>)listener
Parameters
listener

A GKLocalPlayerListener object containing the listener to unregister.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKLocalPlayer.h

Notifications

GKPlayerAuthenticationDidChangeNotificationName

Posted after the authenticated property of the shared local player object changes. The object property for this notification is a GKLocalPlayer object. Passing nil provides standard Notification Center behavior which is to receive the notification for any object.
Availability
Declared In
GKLocalPlayer.h