Play 게임즈 서비스 v2로 이전 (Unity)

이 문서에서는 기존 게임을 게임 v1 SDK 에서 게임 v2 SDK로 이전하는 방법을 설명합니다. Unity용 Play 게임즈 플러그인 버전 10 이하에서는 게임 v1 SDK를 사용합니다.

시작하기 전에

• Play Console을 이미 설정하고 Unity 편집기를 설치했는지 확인합니다.

Unity용 Google Play 게임즈 플러그인 다운로드

Play 게임즈 서비스의 최신 기능을 활용하려면 최신 플러그인 버전을 다운로드하여 설치하세요. gitHub 저장소에서 다운로드합니다.

이전 플러그인 삭제

Unity 편집기에서 다음 폴더 또는 파일을 삭제합니다.

Assets/GooglePlayGames

Assets/GeneratedLocalRepo/GooglePlayGames

Assets/Plugins/Android/GooglePlayGamesManifest.androidlib

Assets/Plugins/Android

Unity 프로젝트로 새 플러그인 가져오기

Unity 프로젝트로 플러그인을 가져오려면 다음 단계를 따르세요.

1. 게임 프로젝트를 엽니다.
2. Unity 편집기에서 Assets > Import Package > Custom Package 를 클릭하여 다운로드한 unitypackage 파일을 프로젝트의 애셋으로 가져옵니다.

3. 현재 빌드 플랫폼이 Android 로 설정되어 있는지 확인합니다.

   1. 기본 메뉴에서 File > Build Settings 를 클릭합니다.

   2. Android 를 선택하고 Switch Platform 을 클릭합니다.

   3. Window > Google Play Games 아래에 새 메뉴 항목이 있습니다. 표시되지 않으면 Assets > Refresh 를 클릭하여 애셋을 새로고침한 다음 빌드 플랫폼을 다시 설정해 봅니다.

4. Unity 편집기에서 File > Build Settings > Player Settings > Other Settings 를 클릭합니다.

5. 대상 API 수준 상자에서 버전을 선택합니다.

6. Scripting backend 상자에 IL2CPP를 입력합니다.

7. Target architectures 상자에서 값을 선택합니다.

8. 패키지 이름 package_name을 기록해 둡니다.이 정보는 나중에 사용할 수 있습니다.

   

9. Play Console에서 Android 리소스 복사

10. Unity 프로젝트에 Android 리소스 추가

이전 경로

게임의 올바른 마이그레이션 경로는 Play Games 서비스 v1을 구현하고 플레이어 ID를 처리하는 방식에 따라 다릅니다. 원활한 전환을 보장하고 플레이어 데이터 손실을 방지하려면 기존 설정과 가장 일치하는 시나리오를 파악하고 해당 단계를 따르세요.

옵션 1: IGA가 Play 게임즈 서비스 플레이어 ID에 바인딩된 게임

이 시나리오는 Play 게임즈 서비스 Player ID를 플레이어의 게임 내 계정 (IGA)에 대한 유일한 식별자로 사용하고 이전에 OpenID를 요청하거나 저장하지 않은 게임에 적용됩니다. 가장 큰 과제는 플레이어 진행 상황과의 연결을 끊지 않고 기존 IGA를 기본 식별자 (OpenID)에 연결하는 것입니다.

이전 흐름에는 다음 단계가 포함됩니다.

1. 게임이 출시되면 Play Games 서비스 v2 SDK가 자동으로 백그라운드에서 플랫폼을 인증합니다.

2. 게임에 로그인 화면이 표시됩니다. 이 화면에는 Google Play 버튼을 대체하는 Google로 로그인 (SiWG) 버튼이 있어야 합니다. 통합하려면 다음 단계를 따르세요.

   1. CredManBridge.java를 폴더에 다운로드합니다. 이 Java 클래스는 Unity와 androidx.credentials 라이브러리 간의 브리지 역할을 합니다.

      CredManBridge.java

      
      package com.wickedcube.trivialkart;
      import android.accounts.Account;
      import android.content.Context;
      import android.util.Log;
      import android.os.CancellationSignal;
      import androidx.credentials.CredentialManager;
      import androidx.credentials.GetCredentialRequest;
      import androidx.credentials.GetCredentialResponse;
      import androidx.credentials.exceptions.GetCredentialException;
      import androidx.credentials.exceptions.NoCredentialException;
      import com.google.android.libraries.identity.googleid.GetGoogleIdOption;
      import com.google.android.libraries.identity.googleid.GoogleIdTokenCredential;
      import com.google.android.gms.auth.api.identity.AuthorizationClient;
      import com.google.android.gms.auth.api.identity.AuthorizationRequest;
      import com.google.android.gms.auth.api.identity.AuthorizationResult;
      import com.google.android.gms.common.api.ApiException;
      import com.google.android.gms.auth.api.identity.Identity;
      import com.google.android.gms.common.api.Scope;
      import com.unity3d.player.UnityPlayer;
      import java.util.Collections;
      import java.util.List;
      import java.util.concurrent.Executor;
      import java.util.concurrent.Executors;
      
      
      public class CredManBridge {
      
      // --- MODE 1: SILENT SIGN-IN (Called on Awake) ---
      // Tries to auto-select an authorized account. If it fails, it does NOT show UI.
      public static void signInSilent(Context context, String webClientId) {
        CredentialManager credentialManager = CredentialManager.create(context);
        CancellationSignal cancellationSignal = new CancellationSignal();
        Executor executor = Executors.newSingleThreadExecutor();
      
      Log.d("CredMan", "Attempting Silent Sign-In...");
      
      GetGoogleIdOption silentOption = new GetGoogleIdOption.Builder()
          .setFilterByAuthorizedAccounts(true) // Strict: Only authorized accounts
          .setServerClientId(webClientId)
          .setAutoSelectEnabled(true)          // Auto-select if possible
          .build();
      
      GetCredentialRequest silentRequest = new GetCredentialRequest.Builder()
          .addCredentialOption(silentOption)
          .build();
      
      credentialManager.getCredentialAsync(
          context,
          silentRequest,
          cancellationSignal,
          executor,
          new androidx.credentials.CredentialManagerCallback<GetCredentialResponse, GetCredentialException>() {
              @Override
              public void onResult(GetCredentialResponse result) {
                  Log.d("CredMan", "Silent Sign-In Successful!");
                  handleSignInResult(context, result, webClientId);
              }
          @Override
          public void onError(GetCredentialException e) {
              // Send a specific error code so Unity knows to just stay on the Start Screen
              Log.d("CredMan", "Silent sign-in failed. Keeping UI hidden.");
              UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "SilentFailed");
          }
      }
      
      );
      }
      
      // --- MODE 2: INTERACTIVE SIGN-IN (Called on Button Click) ---
      // Forces the Account Selection / "Add Account" sheet to appear.
      public static void signInInteractive(Context context, String webClientId) {
        CredentialManager credentialManager = CredentialManager.create(context);
        CancellationSignal cancellationSignal = new CancellationSignal();
        Executor executor = Executors.newSingleThreadExecutor();
      
      Log.d("CredMan", "Starting Interactive Sign-In...");
      
      GetGoogleIdOption interactiveOption = new GetGoogleIdOption.Builder()
          .setFilterByAuthorizedAccounts(false) // Show ALL accounts (and "Add Account")
          .setServerClientId(webClientId)
          .setAutoSelectEnabled(false)          // Force the UI to show
          .build();
      
      GetCredentialRequest interactiveRequest = new GetCredentialRequest.Builder()
          .addCredentialOption(interactiveOption)
          .build();
      
      credentialManager.getCredentialAsync(
          context,
          interactiveRequest,
          cancellationSignal,
          executor,
          new androidx.credentials.CredentialManagerCallback<getcredentialresponse, getcredentialexception="">() {
              @Override
              public void onResult(GetCredentialResponse result) {
                  Log.d("CredMan", "Interactive Sign-In Successful!");
                  handleSignInResult(context, result, webClientId);
              }</getcredentialresponse,>
          @Override
          public void onError(GetCredentialException e) {
              Log.e("CredMan", "Interactive Sign-In Canceled or Failed", e);
              UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "Canceled");
          }
      }
      
      );
      }
      
      private static void handleSignInResult(Context context, GetCredentialResponse result, String webClientId) {
        try {
          GoogleIdTokenCredential credential = GoogleIdTokenCredential.createFrom(result.getCredential().getData());
          String email = credential.getId();
      Account account = new Account(email, "com.google");
      // Requesting GAMES_LITE scope to check for pre-existing V1 grants
      List<Scope> requestedScopes = Collections.singletonList(new Scope("https://www.googleapis.com/auth/games_lite"));
      
      AuthorizationRequest authRequest = new AuthorizationRequest.Builder()
          .setRequestedScopes(requestedScopes)
          .setAccount(account)
          .requestOfflineAccess(webClientId)
          .build();
      
      AuthorizationClient authClient = Identity.getAuthorizationClient(context);
      
      authClient.authorize(authRequest)
          .addOnSuccessListener(authorizationResult -> {
              if (authorizationResult.getServerAuthCode() != null) {
                  // CASE 1: RETURNING USER (Success)
                  // The user has already granted GAMES_LITE in the past.
                  // We got the code directly without showing UI.
                  Log.i("CredMan", "PGS v1: Existing grant found. Returning user detected. Auth Code retrieved.");
                  UnityPlayer.UnitySendMessage("AuthManager", "OnSignInSuccess", authorizationResult.getServerAuthCode());
              }
              else if (authorizationResult.hasResolution()) {
                  // CASE 2: NEW USER (PendingIntent)
                  // The user has NOT granted GAMES_LITE before. The API returned a PendingIntent
                  // (authorizationResult.getPendingIntent()) to show the consent screen.
                  // As per your flow, we DISCARD this intent and do not show UI.
                  Log.i("CredMan", "PGS v1: No existing grant (PendingIntent returned). This is a NEW user or they revoked access.");
                  Log.i("CredMan", "PGS v1: Discarding PendingIntent. Proceeding as New User.");
      
                  // Notify Unity that this is a "New User" so it can trigger V2 logic instead of failing
                  UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "NewUser_NoGrant");
              }
              else {
                  // Edge Case: No code and no resolution?
                  Log.e("CredMan", "PGS v1: Authorization success but no Auth Code or Resolution returned.");
                  UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "No Auth Code returned");
              }
          })
          .addOnFailureListener(e -> {
              // CASE 3: GENERIC FAILURE
              Log.e("CredMan", "PGS v1: Authorization failed completely.", e);
              UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "Authorization Failed: " + e.getMessage());
          });
      
      } catch (Exception e) {
          UnityPlayer.UnitySendMessage("AuthManager", "OnSignInError", "Parsing Error: " + e.getMessage());
      }
      }
      }
      
      
      
      

   2. 인증 관리자 통합:

      • 이전에 앱을 승인한 사용자만 로그인하도록 자동 로그인에 setFilterByAuthorizedAccounts(true)와 함께 GetGoogleIdOption을 사용합니다.
      • 사용자가 계정을 선택하거나 새 계정을 추가할 수 있도록 대화형 로그인에 setFilterByAuthorizedAccounts(false)를 사용합니다.

   3. 범위 요청:

      • 기본 Google 사용자 인증 정보를 가져온 후 특정 기존 범위인 AuthorizationRequest https://www.googleapis.com/auth/games_lite를 요청하는 `AuthorizationRequest`를 만듭니다.
      • 이 범위는 서버에 사용자의 기존 PlayerID를 조회할 수 있는 권한을 부여하므로 매우 중요합니다.

   4. 결과 처리:

      • 사용자가 권한을 부여하거나 이전에 권한을 부여한 경우 브리지가 ServerAuthCode를 Unity에 반환합니다.
      • 사용자가 권한을 부여하지 않은 경우 (신규 사용자 시나리오) API가 PendingIntent를 반환합니다. 이 샘플에서는 흐름을 간소화하기 위해 인텐트가 삭제되고 사용자가 신규 사용자로 처리됩니다.

3. 인증 관리자 및 Google ID 서비스를 지원하려면 다음 종속 항목이 mainTemplate.gradle Gradle 구성에 추가되어 있는지 확인합니다.

   dependencies {
   // Standard Unity dependencies
   implementation fileTree(dir: 'libs', include: ['*.jar'])
   
   // Credential Manager and Identity Libraries
   implementation 'androidx.credentials:credentials:1.3.0'
   implementation 'androidx.credentials:credentials-play-services-auth:1.3.0'
   implementation 'com.google.android.libraries.identity.googleid:googleid:1.1.1'
   
   // Play Services Auth for legacy scope handling
   implementation 'com.google.android.gms:play-services-auth:21.2.0'
   }

   • 인증 관리자: 계정 선택을 위한 기본 ID 오케스트레이션 및 UI를 처리합니다.
   • GoogleID 라이브러리: OpenID Connect 토큰을 가져오기 위한 GetGoogleIdOption을 구체적으로 제공합니다.
   • Play 서비스 인증: 호환성을 유지하고 기존 Player ID 검색을 위한 GAMES_LITE 범위를 요청하는 데 필요합니다.

4. 플레이어가 SiWG 버튼을 탭하고 Google 계정을 선택하면 게임에서 두 가지 고유한 식별자를 가져와야 합니다.

   • IGA를 바인딩하기 위한 기본 식별자인 OpenID입니다.
   • GAMES_LITE 범위를 사용하여 가져온 Play Games 서비스 Player ID입니다. 백엔드 시스템에서 플레이어의 IGA를 조회하고 바인딩을 실행하는 데 사용됩니다.

5. 이후 게임 실행에서 플레이어는 게임에서 Player ID를 기본 식별자로 사용하지 않고도 SiWG 흐름을 통해 IGA에 액세스할 수 있습니다.

using GooglePlayGames;
using GooglePlayGames.BasicApi;
using UnityEngine.SocialPlatforms;

public void Start() {
    PlayGamesClientConfiguration config =
        new PlayGamesClientConfiguration.Builder()
    // Enables saving game progress
    .EnableSavedGames()
    // Requests the email address of the player be available
    // will bring up a prompt for consent
    .RequestEmail()
    // Requests a server auth code be generated so it can be passed to an
    // associated backend server application and exchanged for an OAuth token
    .RequestServerAuthCode(false)
    // Requests an ID token be generated. This OAuth token can be used to
    // identify the player to other services such as Firebase.
    .RequestIdToken()
    .Build();

    PlayGamesPlatform.InitializeInstance(config);
    // recommended for debugging:
    PlayGamesPlatform.DebugLogEnabled = true;
    // Activate the Google Play Games platform
    PlayGamesPlatform.Activate();
}

using GooglePlayGames;

public void Start() {
    PlayGamesPlatform.Instance.Authenticate(ProcessAuthentication);
}

internal void ProcessAuthentication(SignInStatus status) {
    if (status == SignInStatus.Success) {
        // Continue with Play Games Services
    } else {
        // Disable your integration with Play Games Services or show a login
        // button to ask users to sign-in. Clicking it should call
        // PlayGamesPlatform.Instance.ManuallyAuthenticate(ProcessAuthentication).
    }
}

// sign out
PlayGamesPlatform.Instance.SignOut();