Overview

Apple Game Center allows iOS users to log in with their Apple ID's Game Center profile. Game Center is composed of two separate authentication platforms which we refer to as Game Center Legacy and Game Center WWDC2020. These two platforms have separate player IDs and may be used concurrently. Game Center WWDC2020 requires iOS 13.5+.

Setup

To use Apple Game Center, you need to:

1. Configure Game Center in App Store Connect.

   Follow instructions at https://help.apple.com/app-store-connect/#/devb42a686f5

2. Configure the Game Server to accept and validate Game Center sign-in requests.

   In the relevant Options.<env>.yaml, set:

   AppleStore:
     EnableAppleAuthentication: true
     IosBundleId: <bundle id of the app>

3. Implement the client-side logic.

   Automatically log in during app launch. Login may start before the initial connection has been established. After a successful login, send a SocialAuthenticationClaimGameCenter and/or SocialAuthenticationClaimGameCenter2020 claim for the respective Legacy and/or WWDC2020 Platform.

DANGER

Mix-up Warning: Legacy and WWDC2020 Game Center authentication claims use identical token verification schemes, and as such, it is possible to accidentally send a valid legacy claim with a WWDC2020 token and a valid WWDC2020 claim with a legacy token. To mitigate the mix-up risk, and due to limitations described in App Transfer Considerations, it's recommended to log in with both login methods.

Example Client Integration

1. Listen for authentication events.

   GKLocalPlayer* localPlayer = [GKLocalPlayer localPlayer];
   localPlayer.authenticateHandler = ^(UIViewController *viewController, NSError *error)
   {
       if (viewController != nil)
       {
           // present the viewController so that user can log in
       }
       else if (localPlayer.isAuthenticated)
       {
           FetchGameCenterAuthenticationToken();
       }
       else
       {
           GameCenterLoggedOut();
       }
   };

2. After connecting to Game Center, get authentication tokens using the MetaplayGameCenterPlugin helper.

   void FetchGameCenterAuthenticationToken()
   {
       MetaplayGameCenterPlugin.GetVerificationSignature(HandleGameCenterVerificationSignature);
   }

   Note that using the MetaplayGameCenterPlugin is not required and the game may opt to fetch the authentication manually with generateIdentityVerificationSignatureWithCompletionHandler (for legacy IDs) and fetchItemsForIdentityVerificationSignature (for WWDC2020 IDs) native methods.

   DANGER

   Race Condition Warning: Native completion handlers are not executed on the Unity thread. If the helper is not used, manual synchronization is required when delivering the result to Unity Thread.

   DANGER

   Bug Warning: In certain versions of Unity, Unity Social API Social.localUser.id returns the TeamPlayerId, i.e. the WWDC2020 Player Id, and in certain versions, the PlayerId, i.e. the Legacy Player Id. Due to this unreliability, the use of Unity Social API is not recommended for accessing Player IDs.

3. Handle passing the pending login state to the Game Server.

   static void HandleGameCenterVerificationSignature(MetaplayGameCenterPlugin.VerificationSignatureResult result)
   {
       if (result.ErrorString != null)
           Log.Warning("GameCenter verification signature fetch failed with {ErrorString}", result.ErrorString);
   
       if (result.LegacySignature != null && result.TeamScopedSignature != null)
       {
           // Both claims available. Login with legacy and attach wwdc2020 as its forward migration claim.
           SocialAuthenticationClaimGameCenter2020 wwdc2020Claim = result.TeamScopedSignature.Value.ToSocialLoginClaim();
           SocialAuthenticationClaimGameCenter legacyAndMigrationClaim = result.LegacySignature.Value.ToSocialLoginClaim(optionalMigrationClaim: wwdc2020Claim);
           SocialAuthManager.StartValidation(legacyAndMigrationClaim);
       }
       else if (result.LegacySignature != null)
       {
           // Just legacy available
           SocialAuthenticationClaimGameCenter legacyClaim = result.LegacySignature.Value.ToSocialLoginClaim(optionalMigrationClaim: null);
           SocialAuthManager.StartValidation(legacyClaim);
       }
       else if (result.TeamScopedSignature != null)
       {
           // Just new available
           SocialAuthenticationClaimGameCenter2020 wwdc2020Claim = result.TeamScopedSignature.Value.ToSocialLoginClaim();
           SocialAuthManager.StartValidation(wwdc2020Claim);
       }
   }

Considerations on App Transfers

Game Center WWDC2020 teamPlayerId and validation token are scoped to the app's Apple development team ID. This means their value depends on the team ID of the app. If the app is transferred from one team to another, the existing Game Center WWDC2020 authentication records are lost.

After this event, when a player logs in to the game with their Game Center account, either of the following happens (assuming state management is implemented as defined earlier in this document):

• If the player has played the game with their current device, the authentication record is refreshed and there are no visible changes to the player.
• If the player has not played the game with their current device or has uninstalled the game, their new Game Center authentication key cannot be used to find their existing account. The Player will see that their existing account was not restored, and a new account is created instead. The new account uses a refreshed authentication token.

If the player now opens the game on a device that has been used to play the game, an account conflict will occur. Upon resolution, the old or the new account will be orphaned.

TIP

Protip: Lost authentication records could be restored by using unauthenticated, unsafe GamePlayerId but this mode of operation is not yet implemented in Metaplay SDK. Contact us for more information.