Eseguire la migrazione a Play Games Services v2 (Unity)

Questo documento descrive come eseguire la migrazione dei giochi esistenti dall'SDK games v1 all'SDK games v2. Il plug-in Play Games per Unity, versioni 10 e precedenti, utilizza l'SDK games v1.

Prima di iniziare

• Assicurati di aver già configurato Play Console e installato Unity Editor.

Scarica il plug-in Google Play Games per Unity

Per usufruire delle funzionalità più recenti di Play Games Services, scarica e installa l'ultima versione del plug-in. Scaricalo dal repository GitHub.

Rimuovi il vecchio plug-in

In Unity Editor, rimuovi le seguenti cartelle o i seguenti file.

Assets/GooglePlayGames

Assets/GeneratedLocalRepo/GooglePlayGames

Assets/Plugins/Android/GooglePlayGamesManifest.androidlib

Assets/Plugins/Android

Importa il nuovo plug-in nel progetto Unity

Per importare il plug-in nel progetto Unity:

1. Apri il progetto di gioco.
2. In Unity Editor, fai clic su Assets > Import Package > Custom Package per importare il file unitypackage nelle risorse del progetto.

3. Assicurati che la piattaforma di build corrente sia impostata su Android.

   1. Nel menu principale, fai clic su File > Build Settings (File > Impostazioni di build).

   2. Seleziona Android e fai clic su Switch Platform (Cambia piattaforma).

   3. Dovrebbe essere presente una nuova voce di menu in Window > Google Play Games (Finestra > Google Play Games). In caso contrario, aggiorna le risorse facendo clic su Assets > Refresh (Risorse > Aggiorna) e poi prova a impostare di nuovo la piattaforma di build.

4. In Unity Editor, fai clic su File > Build Settings > Player Settings > Other Settings (File > Impostazioni di build > Impostazioni del giocatore > Altre impostazioni).

5. Nella casella Target API level (Livello API target), seleziona una versione.

6. Nella casella Scripting backend (Backend di scripting), inserisci IL2CPP.

7. Nella casella Target architectures (Architetture target), seleziona un valore.

8. Prendi nota del nome del pacchetto package_name.Puoi utilizzare queste informazioni in un secondo momento.

   

9. Copia le risorse Android da Play Console

10. Aggiungi le risorse Android al progetto Unity

Percorsi di migrazione

Il percorso di migrazione corretto per il tuo gioco dipende da come implementa i servizi per i giochi di Play v1 e gestisce l'identità del giocatore. Per garantire una transizione senza problemi ed evitare la perdita di dati dei giocatori, identifica lo scenario che corrisponde meglio alla configurazione esistente e segui i passaggi corrispondenti.

Opzione 1: per i giochi in cui l'IGA è associato all'ID giocatore di Play Games Services

Questo scenario si applica ai giochi che hanno utilizzato i Play Games Services Player ID come unico identificatore per un account di gioco (IGA) di un giocatore e non hanno richiesto o memorizzato in precedenza un OpenID. La sfida principale è collegare l'IGA esistente a un identificatore principale (l'OpenID) senza perdere la connessione ai progressi del giocatore.

Il flusso di migrazione include i seguenti passaggi:

1. Quando il gioco viene avviato, l'SDK di Play Games Services v2 autentica automaticamente e in modo silenzioso la piattaforma.

2. Il gioco mostra la schermata di accesso. Questa schermata deve includere un pulsante Accedi con Google (SiWG) che sostituisce il pulsante Google Play. Per l'integrazione:

   1. Scarica CredManBridge.java nella tua cartella. Questa classe Java funge da bridge tra Unity e la libreria 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. Integrazione di Gestore delle credenziali:

      • Utilizza GetGoogleIdOption con setFilterByAuthorizedAccounts(true) per gli accessi silenziosi in modo da consentire l'accesso solo agli utenti che hanno autorizzato l'app in precedenza.
      • Utilizza setFilterByAuthorizedAccounts(false) per gli accessi interattivi in modo da consentire agli utenti di selezionare un account o aggiungerne uno nuovo.

   3. Richiesta di ambito:

      • Dopo aver ottenuto la credenziale Google di base, crea un AuthorizationRequest che richiede l'ambito legacy specifico: https://www.googleapis.com/auth/games_lite.
      • Questo ambito è fondamentale perché concede al server l'autorizzazione a cercare l'ID giocatore legacy dell'utente.

   4. Gestione dei risultati:

      • Se l'utente concede l'autorizzazione (o l'ha concessa in precedenza), il bridge restituisce il ServerAuthCode a Unity.
      • Se l'utente non ha concesso l'autorizzazione (scenario per i nuovi utenti), l'API restituisce un PendingIntent. In questo esempio, l'intent viene ignorato e l'utente viene trattato come un nuovo utente per semplificare il flusso.

3. Per supportare Gestore delle credenziali e i servizi di identità Google, assicurati che le seguenti dipendenze siano aggiunte alla configurazione Gradle mainTemplate.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'
   }

   • Gestore delle credenziali: gestisce l'orchestrazione dell'identità principale e l'interfaccia utente per la selezione dell'account.
   • Libreria GoogleID: fornisce in modo specifico GetGoogleIdOption per recuperare i token OpenID Connect.
   • Autenticazione di Play Services: necessaria per mantenere la compatibilità e richiedere l'ambito GAMES_LITE per il recupero dell'Player ID legacy.

4. Quando il giocatore tocca il pulsante SiWG e seleziona un Account Google, il gioco deve recuperare due identificatori distinti:

   • L'OpenID, l'identificatore principale per l'associazione dell'IGA.
   • I Play Games Services Player ID, recuperati utilizzando l'ambito GAMES_LITE, per cercare l'IGA del giocatore nel sistema di backend ed eseguire l'associazione.

5. Nei successivi avvii del gioco, i giocatori possono accedere al proprio IGA tramite il flusso SiWG, senza che i giochi debbano utilizzare Player ID come identificatore principale.

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();