Instance Property

authenticateHandler

A handler called to process an authentication-related event.

Declaration

iOS, Mac Catalyst, tvOS
var authenticateHandler: ((UIViewController?, Error?) -> Void)? { get set }
macOS
var authenticateHandler: ((NSViewController?, Error?) -> Void)? { get set }
watchOS
var authenticateHandler: ((Error?) -> Void)? { get set }

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 isAuthenticated property is set to true 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 isAuthenticated property is set to false and the object’s other properties are cleared.

Listing 1 shows an example of how to authenticate the local player.

Listing 1

Setting an authentication handler

- (void) authenticateLocalPlayer
{
    GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];
    localPlayer.authenticateHandler = ^(UIViewController *viewController, NSError *error){
         if (viewController != nil)
         {
             //showAuthenticationDialogWhenReasonable: is an example method name. Create your own method that displays an authentication view when appropriate for your app.
             [self showAuthenticationDialogWhenReasonable: viewController];
         }
         else if (localPlayer.isAuthenticated)
         {
             //authenticatedPlayer: is an example method name. Create your own method that is called after the local player is authenticated.
             [self authenticatedPlayer: localPlayer];
         }
         else
         {
             [self disableGameCenter];
         }
     };
}

Two common errors that can be received by your game are worth describing in more detail:

  • Receiving a GKError.Code.gameUnrecognized error means that you have not enabled Game Center for your app in App Store Connect. Sign in to your App Store Connect account and verify that your app has Game Center enabled. Also, confirm that the bundle identifier in your Xcode project matches the bundle identifier you assigned to your app in App Store Connect.

  • Receiving a GKError.Code.notSupported error means that the device your game is running on does not support Game Center. You should disable all Game Center related features.

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.

See Also

Authentication

var isAuthenticated: Bool

A Boolean value that indicates whether a local player is currently signed in to Game Center.

func generateIdentityVerificationSignature(completionHandler: ((URL?, Data?, Data?, UInt64, Error?) -> Void)?)

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