iOS Developer Library

Developer

GameKit Framework Reference GKLocalPlayer Class Reference

Options
Deployment Target:

On This Page
Language:

GKLocalPlayer

Inheritance


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later.

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

  • Retrieves the shared instance of the local player.

    Declaration

    Swift

    class func localPlayer() -> GKLocalPlayer!

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • A handler called to process an authentication-related event.

    Declaration

    Swift

    var authenticateHandler: ((UIViewController!, NSError!) -> Void)!

    Objective-C

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

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    var authenticated: Bool { get }

    Objective-C

    @property(readonly, getter=isAuthenticated, nonatomic) BOOL authenticated

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later.

  • Authenticates the local player on the device.

    Deprecation Statement

    Set the authenticateHandler property instead.

    Declaration

    Objective-C

    - (void)authenticateWithCompletionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called when the player has authenticated or when an error occurs.

    The block takes the following parameter:

    error

    This parameter is nil if the player successfully authenticated. Otherwise, it contains an error object that describes the error that occurred.

    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.

    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.

    If there is not an authenticated player on the device when your game calls this method, Game Kit displays a user interface that allows the player to sign in with their credentials (or to create a new account if he or she has never used Game Center). Your game should pause other activities that require user interaction (such as a real time game loop) before attempting to authenticate the local player.

    Game Kit maintains a strong reference to your completion handler even after successfully authenticating a local player. If your game moves into the background, Game Kit automatically authenticates the player again whenever your game moves back to the foreground. Game Kit calls your same completion handler each time it authenticates the local player. Be mindful that in block programming, any Objective-C object referenced inside a block is also strongly referenced by the block until the block is released. Because Game Kit maintains a strong reference to your completion handler until your game terminates, any objects referenced from within your authentication handler are also held indefinitely.

    Each time the completion 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.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 6.0.

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

    Declaration

    Swift

    func generateIdentityVerificationSignatureWithCompletionHandler(_ completionHandler: ((NSURL!, NSData!, NSData!, UInt64, NSError!) -> Void)!)

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

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

    Objective-C

    - (void)loadFriendPlayersWithCompletionHandler:(void (^)(NSArray *friendPlayers, NSError *error))completionHandler

    Parameters

    completionHandler

    A block to be called when the request completes.

    The block receives the following parameters:

    friendPlayers

    An array of GKPlayer 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

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

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 8.0.

    See Also

    friends

  • friends friends (iOS 8.0) Property

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

    Declaration

    Swift

    var friends: [AnyObject]! { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later.

    Deprecated in iOS 8.0.

  • underage underage Property

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

    Declaration

    Swift

    var underage: Bool { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later.

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

    Declaration

    Swift

    func loadDefaultLeaderboardIdentifierWithCompletionHandler(_ completionHandler: ((String!, NSError!) -> Void)!)

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

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

    Deprecation Statement

    Use the loadDefaultLeaderboardIdentifierWithCompletionHandler: method instead.

    Declaration

    Objective-C

    - (void)loadDefaultLeaderboardCategoryIDWithCompletionHandler:(void (^)(NSString *categoryID, 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.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 6.0 and later.

    Deprecated in iOS 7.0.

  • Sets the category identifier for the local player’s default leaderboard.

    Deprecation Statement

    Use the setDefaultLeaderboardIdentifier:completionHandler: method instead.

    Declaration

    Objective-C

    - (void)setDefaultLeaderboardCategoryID:(NSString *)categoryID completionHandler:(void (^)(NSError *error))completionHandler

    Parameters

    categoryID

    The category ID string for one of your game’s leaderboards.

    completionHandler

    A block to be called when the request completes.

    The block receives the following parameter:

    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.

    Import Statement

    Objective-C

    @import GameKit;

    Availability

    Available in iOS 6.0 and later.

    Deprecated in iOS 7.0.

  • Sets the default leaderboard for the current game.

    Declaration

    Swift

    func setDefaultLeaderboardIdentifier(_ leaderboardIdentifier: String!, completionHandler completionHandler: ((NSError!) -> Void)!)

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

  • Register a listener for a particular event.

    Declaration

    Swift

    func registerListener(_ listener: GKLocalPlayerListener!)

    Objective-C

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

  • Unregister all listeners in your game.

    Declaration

    Swift

    func unregisterAllListeners()

    Objective-C

    - (void)unregisterAllListeners

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

  • Unregister a specific listener.

    Declaration

    Swift

    func unregisterListener(_ listener: GKLocalPlayerListener!)

    Objective-C

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

    Parameters

    listener

    A GKLocalPlayerListener object containing the listener to unregister.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 7.0 and later.

  • Deletes a specific saved game file.

    Declaration

    Swift

    func deleteSavedGamesWithName(_ name: String!, completionHandler handler: ((NSError!) -> Void)!)

    Objective-C

    - (void)deleteSavedGamesWithName:(NSString *)name completionHandler:(void (^)(NSError *error))handler

    Parameters

    name

    A string that identifies the saved game data to be deleted.

    handler

    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, indicating a successful delete.

    Discussion

    This method deletes saved game files asynchronously.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • Retrieves all available saved games.

    Declaration

    Swift

    func fetchSavedGamesWithCompletionHandler(_ handler: (([AnyObject]!, NSError!) -> Void)!)

    Objective-C

    - (void)fetchSavedGamesWithCompletionHandler:(void (^)(NSArray *savedGames, NSError *error))handler

    Parameters

    handler

    A block to be called when the request completes.

    The block receives the following parameters:

    savedGames

    An array of GKSavedGame objects containing the retrieved games.

    error

    If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter is nil.

    Discussion

    This method retrieves saved game files asynchronously. When there is more than one saved game with the same name, a conflict occurs. The app must determine which saved game file is correct and call the resolveConflictingSavedGames:withData:completionHandler: method.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • Resolves any conflicting saved games.

    Declaration

    Swift

    func resolveConflictingSavedGames(_ conflictingSavedGames: [AnyObject]!, withData data: NSData!, completionHandler handler: (([AnyObject]!, NSError!) -> Void)!)

    Objective-C

    - (void)resolveConflictingSavedGames:(NSArray *)conflictingSavedGames withData:(NSData *)data completionHandler:(void (^)(NSArray *savedGames, NSError *error))handler

    Parameters

    conflictingSavedGames

    An array of GKSavedGame objects containing the conflicting saved games to be deleted.

    data

    An object that contains the saved game data.

    handler

    A block to be called when the request completes.

    The block receives the following parameters:

    savedGames

    An array of GKSavedGame objects containing a saved game list with all conflicts contained in the conflictingSavedGames parameter resolved. If there are any conflicting saved game files that were not in the conflictingSavedGames parameter, these objects will automatically be appended to the end of the savedGames array. For example, if there are five saved game files with the same name, but only three are in the conflictingSavedGames array, this array will contain the resolved saved game file and the two unresolved files.

    error

    If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter is nil.

    Discussion

    This method takes an array of GKSavedGame objects that contain conflicting saved game files and creates a new array that contains the resolved conflicts. All saved game conflicts are resolved and added to the savedGames array in the completion handler. Call this method separately for each set of saved game conflicts. For example, if you have multiple saved game files with the name of “savedgame1” and “savedgame2”, you need to call this method twice—once with an array containing the GKSavedGame objects with the “savedgame1” name and once for the “savedgame2” objects. All saved game conflicts are resolved asynchronously.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.

  • Saves game data under the specified name.

    Declaration

    Swift

    func saveGameData(_ data: NSData!, withName name: String!, completionHandler handler: ((GKSavedGame!, NSError!) -> Void)!)

    Objective-C

    - (void)saveGameData:(NSData *)data withName:(NSString *)name completionHandler:(void (^)(GKSavedGame *savedGame, NSError *error))handler

    Parameters

    data

    An object that contains the saved game data.

    name

    A string that identifies the saved game data.

    handler

    A block to be called when the request completes.

    The block receives the following parameters:

    savedGame

    A GKSavedGame object containing saved game information for the saved data.

    error

    If an error occurred, this parameter holds an error object that explains the error. Otherwise, the value of this parameter is nil.

    Discussion

    This method saves game data asynchronously. When a game is saved, if there is already a saved game with the same name, the new saved game data overwrites the old saved game data. If there is no saved game with the same name, a new saved game is created.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later.