Migrar para os serviços relacionados a jogos do Google Play v2 (Unity)

Este documento descreve como migrar jogos do games v1 SDK para o games v2 SDK. O plug-in do Play Games para Unity, versões 10 e anteriores, usa o SDK games v1.

Antes de começar

• Verifique se você já configurou o Play Console e instalou o Unity Editor.

Baixar o plug-in do Google Play Games para Unity

Para aproveitar os recursos mais recentes dos serviços do Google Play Games, baixe e instale a versão mais recente do plug-in. Faça o download no repositório do GitHub.

Remover o plug-in antigo

No Unity Editor, remova as seguintes pastas ou arquivos:

Assets/GooglePlayGames

Assets/GeneratedLocalRepo/GooglePlayGames

Assets/Plugins/Android/GooglePlayGamesManifest.androidlib

Assets/Plugins/Android

Importe o novo plug-in para seu projeto do Unity.

Para importar o plug-in para seu projeto do Unity, siga estas etapas:

1. Abra o projeto de jogo.
2. No editor do Unity, clique em Assets > Import Package > Custom Package para importar o arquivo unitypackage baixado para os recursos do projeto.

3. Confira se a plataforma de build atual está definida como Android.

   1. No menu principal, clique em Arquivo > Configurações de build.

   2. Selecione Android e clique em Switch Platform.

   3. Um novo item de menu vai aparecer em Window > Google Play Games. Se isso não acontecer, clique em Assets > Refresh para atualizar os recursos e tente definir a plataforma de build novamente.

4. No editor do Unity, clique em File > Build Settings > Player Settings > Other Settings.

5. Na caixa nível desejado da API, selecione uma versão.

6. Na caixa Backend de script, insira IL2CPP.

7. Na caixa Arquiteturas de destino, selecione um valor.

8. Observe o nome do pacote package_name.Você pode usar essas informações mais tarde.

   

9. Copiar os recursos do Android do Play Console

10. Adicione os recursos do Android ao seu projeto do Unity

Caminhos de migração

O caminho de migração correto para seu jogo depende de como ele implementa os serviços do Google Play Games v1 e processa a identidade do jogador. Para garantir uma transição tranquila e evitar a perda de dados dos jogadores, identifique o cenário que melhor corresponde à sua configuração atual e siga as etapas correspondentes.

Opção 1: para jogos em que a IGA está vinculada ao ID do jogador dos serviços do Google Play Games

Esse cenário se aplica a jogos que usaram os Player ID serviços do Google Play Games como o único identificador de uma conta no jogo (IGA, na sigla em inglês) de um jogador e não solicitaram nem armazenaram um OpenID antes. O principal desafio é vincular o IGA atual a um identificador principal (o OpenID) sem perder a conexão com o progresso do jogador.

O fluxo de migração inclui as seguintes etapas:

1. Quando o jogo é iniciado, o SDK dos serviços do Google Play Games v2 autentica a plataforma de forma automática e silenciosa.

2. O jogo mostra a tela de login. Essa tela precisa ter um botão Fazer login com o Google (SiWG) em vez do botão Google Play. Para integrar:

   1. Faça o download de CredManBridge.java na sua pasta. Essa classe Java funciona como uma ponte entre o Unity e a biblioteca 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. Integração do Credential Manager:

      • Use GetGoogleIdOption com setFilterByAuthorizedAccounts(true) para fazer logins silenciosos apenas de usuários que já autorizaram o app.
      • Use setFilterByAuthorizedAccounts(false) para logins interativos e permita que os usuários selecionem uma conta ou adicionem uma nova.

   3. Solicitação de escopo:

      • Depois de receber a credencial base do Google, ela cria um AuthorizationRequest solicitando o escopo legado específico: https://www.googleapis.com/auth/games_lite.
      • Esse escopo é fundamental porque concede ao servidor permissão para pesquisar o PlayerID legado do usuário.

   4. Tratamento de resultados:

      • Se o usuário conceder permissão (ou já tiver concedido), a ponte vai retornar o ServerAuthCode para o Unity.
      • Se o usuário não tiver concedido permissão (cenário de novo usuário), a API retornará um PendingIntent. Neste exemplo, a intent é descartada, e o usuário é tratado como um novo usuário para simplificar o fluxo.

3. Para oferecer suporte ao Credential Manager e aos serviços de identidade do Google, verifique se as seguintes dependências foram adicionadas à configuração mainTemplate.gradle do 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'
   }

   • Credential Manager:processa a orquestração de identidade principal e a interface do usuário para seleção de contas.
   • Biblioteca GoogleID:fornece especificamente GetGoogleIdOption para recuperar tokens do OpenID Connect.
   • Autenticação do Google Play Services:necessária para manter a compatibilidade e solicitar o escopo GAMES_LITE para recuperação legada de Player ID.

4. Quando o jogador toca no botão SiWG e seleciona uma Conta do Google, o jogo precisa recuperar dois identificadores distintos:

   • O OpenID, o identificador principal para vincular a IGA.
   • O Player ID dos serviços do Google Play Games, recuperado usando o escopo GAMES_LITE, para pesquisar o IGA do jogador no sistema de back-end e realizar a vinculação.

5. Em lançamentos de jogos subsequentes, os jogadores podem acessar o IGA pelo fluxo SiWG, sem exigir que os jogos usem Player ID como um identificador principal.

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