Eseguire la migrazione a Play Games Services v2 (Java o Kotlin)

Questo documento descrive come eseguire la migrazione dei giochi esistenti dall'SDK Games v1 all'SDK Games v2.

Prima di iniziare

Per eseguire la migrazione del tuo gioco, puoi utilizzare qualsiasi IDE preferito, ad esempio Android Studio. Completa i seguenti passaggi prima di eseguire la migrazione a giochi v2:

Aggiorna le dipendenze

  1. Nel file build.gradle del modulo, trova questa riga nelle dipendenze a livello di modulo.

    implementation "com.google.android.gms:play-services-games-v1:+"

    Sostituiscilo con il seguente codice:

    implementation "com.google.android.gms:play-services-games-v2:version"

    Sostituisci version con la versione più recente dell'SDK per i giochi.

  2. Dopo aver aggiornato le dipendenze, assicurati di completare tutti i passaggi descritti in questo documento.

Eseguire la migrazione da Accesso Google deprecato

Sostituisci la classe GoogleSignInClient con la classe GamesSignInClient.

Java

Individua i file con la classe GoogleSignInClient.

import com.google.android.gms.auth.api.signin.GoogleSignIn;
import com.google.android.gms.auth.api.signin.GoogleSignInClient;
import com.google.android.gms.auth.api.signin.GoogleSignInOptions;

// ... existing code

@Override
public void onCreate(@Nullable Bundle bundle) {
    super.onCreate(bundle);

    // ... existing code

    val signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
    // Client used to sign in to Google services
    GoogleSignInClient googleSignInClient =
        GoogleSignIn.getClient(this, signInOptions);
}

E aggiornala come segue:

import com.google.android.gms.games.PlayGamesSdk;
import com.google.android.gms.games.PlayGames;
import com.google.android.gms.games.GamesSignInClient;

// ... existing code

@Override
public void onCreate(){
    super.onCreate();
    // Client used to sign in to Google services
    GamesSignInClient gamesSignInClient =
        PlayGames.getGamesSignInClient(getActivity());
}

Kotlin

Individua i file con la classe GoogleSignInClient.

import com.google.android.gms.auth.api.signin.GoogleSignIn
import com.google.android.gms.auth.api.signin.GoogleSignInClient
import com.google.android.gms.auth.api.signin.GoogleSignInOptions

// ... existing code

val signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN

// ... existing code

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    val googleSignInClient: GoogleSignInClient =
        GoogleSignIn.getClient(this, signInOptions)
}

E aggiornala come segue:

import com.google.android.gms.games.PlayGames
import com.google.android.gms.games.PlayGamesSdk
import com.google.android.gms.games.GamesSignInClient

// ... existing code

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    PlayGamesSdk.initialize(this)
    // client used to sign in to Google services
    val gamesSignInClient: GamesSignInClient =
        PlayGames.getGamesSignInClient(this)
}

Aggiorna il codice GoogleSignIn

L'API e gli ambiti GoogleSignIn non sono supportati nell'SDK v2 per i giochi. Sostituisci il codice dell'API GoogleSignIn per gli ambiti OAuth 2.0 con l'API GamesSignInClient come mostrato nell'esempio seguente:

Java

Individua i file con la classe e gli ambiti GoogleSignIn.

// Request code used when invoking an external activity.
private static final int RC_SIGN_IN = 9001;

private boolean isSignedIn() {
    GoogleSignInAccount account = GoogleSignIn.getLastSignedInAccount(this);
    GoogleSignInOptions signInOptions =
    GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
    return GoogleSignIn.hasPermissions(account, signInOptions.getScopeArray());
}

private void signInSilently() {
    GoogleSignInOptions signInOptions =
        GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
    GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOptions);
    signInClient
        .silentSignIn()
        .addOnCompleteListener(
            this,
            task -> {
            if (task.isSuccessful()) {
                // The signed-in account is stored in the task's result.
                GoogleSignInAccount signedInAccount = task.getResult();
                showSignInPopup();
            } else {
                // Perform interactive sign in.
                startSignInIntent();
            }
        });
}

private void startSignInIntent() {
    GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
        GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
    Intent intent = signInClient.getSignInIntent();
    startActivityForResult(intent, RC_SIGN_IN);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == RC_SIGN_IN) {
        GoogleSignInResult result =
        Auth.GoogleSignInApi.getSignInResultFromIntent(data);
        if (result.isSuccess()) {
            // The signed-in account is stored in the result.
            GoogleSignInAccount signedInAccount = result.getSignInAccount();
            showSignInPopup();
        } else {
            String message = result.getStatus().getStatusMessage();
            if (message == null || message.isEmpty()) {
                message = getString(R.string.signin_other_error);
        }
        new AlertDialog.Builder(this).setMessage(message)
            .setNeutralButton(android.R.string.ok, null).show();
        }
    }
}

private void showSignInPopup() {
Games.getGamesClient(requireContext(), signedInAccount)
    .setViewForPopups(contentView)
    .addOnCompleteListener(
        task -> {
            if (task.isSuccessful()) {
                logger.atInfo().log("SignIn successful");
            } else {
                logger.atInfo().log("SignIn failed");
            }
        });
  }

E aggiornala come segue:

private void signInSilently() {
    gamesSignInClient.isAuthenticated().addOnCompleteListener(isAuthenticatedTask -> {
    boolean isAuthenticated =
        (isAuthenticatedTask.isSuccessful() &&
            isAuthenticatedTask.getResult().isAuthenticated());
        if (isAuthenticated) {
            // Continue with Play Games Services
        } else {
            // If authentication fails, either disable Play Games Services
            // integration or
            // display a login button to prompt players to sign in.
            // Use`gamesSignInClient.signIn()` when the login button is clicked.
        }
    });
}

@Override
protected void onResume() {
    super.onResume();
    // When the activity is inactive, the signed-in user's state can change;
    // therefore, silently sign in when the app resumes.
    signInSilently();
}

Kotlin

Individua i file con la classe e gli ambiti GoogleSignIn.

// Request codes we use when invoking an external activity.
private val RC_SIGN_IN = 9001

// ... existing code

private fun isSignedIn(): Boolean {
    val account = GoogleSignIn.getLastSignedInAccount(this)
    val signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
    return GoogleSignIn.hasPermissions(account, *signInOptions.scopeArray)
}

private fun signInSilently() {
    val signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
    val signInClient = GoogleSignIn.getClient(this, signInOptions)
    signInClient.silentSignIn().addOnCompleteListener(this) { task ->
        if (task.isSuccessful) {
            // The signed-in account is stored in the task's result.
            val signedInAccount = task.result
            // Pass the account to showSignInPopup.
            showSignInPopup(signedInAccount)
        } else {
            // Perform interactive sign in.
            startSignInIntent()
        }
    }
}

private fun startSignInIntent() {
    val signInClient = GoogleSignIn.getClient(this, GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
    val intent = signInClient.signInIntent
    startActivityForResult(intent, RC_SIGN_IN)
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == RC_SIGN_IN) {
        val result = Auth.GoogleSignInApi.getSignInResultFromIntent(data)
        if (result.isSuccess) {
            // The signed-in account is stored in the result.
            val signedInAccount = result.signInAccount
            showSignInPopup(signedInAccount) // Pass the account to showSignInPopup.
        } else {
            var message = result.status.statusMessage
            if (message == null || message.isEmpty()) {
                message = getString(R.string.signin_other_error)
        }
        AlertDialog.Builder(this)
            .setMessage(message)
            .setNeutralButton(android.R.string.ok, null)
            .show()
        }
    }
}

private fun showSignInPopup(signedInAccount: GoogleSignInAccount) {
    // Add signedInAccount parameter.
    Games.getGamesClient(this, signedInAccount)
        .setViewForPopups(contentView) // Assuming contentView is defined.
        .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            logger.atInfo().log("SignIn successful")
        } else {
            logger.atInfo().log("SignIn failed")
        }
    }
}

E aggiornala come segue:

private fun signInSilently() {
    gamesSignInClient.isAuthenticated.addOnCompleteListener { isAuthenticatedTask ->
        val isAuthenticated = isAuthenticatedTask.isSuccessful &&
        isAuthenticatedTask.result.isAuthenticated
        if (isAuthenticated) {
            // Continue with Play Games Services
        } else {
            // To handle a user who is not signed in, either disable Play Games Services integration
            // or display a login button. Selecting this button calls `gamesSignInClient.signIn()`.
        }
    }
}

override fun onResume() {
    super.onResume()
    // Since the state of the signed in user can change when the activity is
    // not active it is recommended to try and sign in silently from when the
    // app resumes.
    signInSilently()
}

Aggiungi il codice GamesSignInClient

Se il giocatore ha eseguito correttamente l'accesso, rimuovi il pulsante di accesso ai servizi per i giochi di Play dal tuo gioco. Se l'utente sceglie di non accedere al momento dell'avvio del gioco, continua a mostrare un pulsante con l'icona di Play Giochi Services e avvia la procedura di accesso con GamesSignInClient.signIn().

Java

private void startSignInIntent() {
    gamesSignInClient
        .signIn()
        .addOnCompleteListener( task -> {
            if (task.isSuccessful() && task.getResult().isAuthenticated()) {
                // sign in successful
            } else {
                // sign in failed
            }
        });
  }

Kotlin

private fun startSignInIntent() {
    gamesSignInClient
        .signIn()
        .addOnCompleteListener { task ->
            if (task.isSuccessful && task.result.isAuthenticated) {
                // sign in successful
            } else {
                // sign in failed
            }
        }
  }

Rimuovere il codice di disconnessione

Rimuovi il codice per GoogleSignInClient.signOut.

Rimuovi il codice mostrato nell'esempio seguente:

Java

// ... existing code

private void signOut() {
    GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
    GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
    signInClient.signOut().addOnCompleteListener(this,
    new OnCompleteListener() {
        @Override
        public void onComplete(@NonNull Task task) {
           // At this point, the user is signed out.
        }
    });
}

Kotlin

// ... existing code

private fun signOut() {
    val signInClient = GoogleSignIn.getClient(this, GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
    signInClient.signOut().addOnCompleteListener(this) {
    // At this point, the user is signed out.
    }
}

Verificare l'accesso automatico riuscito

Includi il seguente codice per verificare se hai eseguito l'accesso automatico e aggiungi la logica personalizzata, se disponibile.

Java

private void checkIfAutomaticallySignedIn() {
gamesSignInClient.isAuthenticated().addOnCompleteListener(isAuthenticatedTask -> {
boolean isAuthenticated =
    (isAuthenticatedTask.isSuccessful() &&
    isAuthenticatedTask.getResult().isAuthenticated());

    if (isAuthenticated) {
        // Continue with Play Games Services
        // If your game requires specific actions upon successful sign-in,
        // you can add your custom logic here.
        // For example, fetching player data or updating UI elements.
    } else {
        // Disable your integration with Play Games Services or show a
        // login button to ask  players to sign-in. Clicking it should
        // call GamesSignInClient.signIn().
        }
    });
}

Kotlin

private void checkIfAutomaticallySignedIn() {
gamesSignInClient.isAuthenticated()
    .addOnCompleteListener { task ->
    val isAuthenticated = task.isSuccessful && task.result?.isAuthenticated ?: false

        if (isAuthenticated) {
            // Continue with Play Games Services
        } else {
            // Disable your integration or show a login button
        }
    }
}

Aggiorna i nomi e i metodi della classe client

Quando esegui la migrazione alla versione 2 di Google Play Giochi, i metodi utilizzati per ottenere i nomi delle classi client sono diversi. Utilizza i metodi corrispondente PlayGames.getxxxClient() instead of Games.getxxxClient().

Ad esempio, per LeaderboardsClient utilizza PlayGames.getLeaderboardsClient() anziché il metodo Games.getLeaderboardsClient().

Java

Individua il codice per LeaderboardsClient.

import com.google.android.gms.games.LeaderboardsClient;
import com.google.android.gms.games.Games;

@Override
public void onCreate(@Nullable Bundle bundle) {
    super.onCreate(bundle);
        // Get the leaderboards client using Play Games services.
    LeaderboardsClient leaderboardsClient = Games.getLeaderboardsClient(this,
        GoogleSignIn.getLastSignedInAccount(this));
}

E aggiornala come segue:

import com.google.android.gms.games.LeaderboardsClient;
import com.google.android.gms.games.PlayGames;

 @Override
public void onCreate(@Nullable Bundle bundle) {
    super.onCreate(bundle);
        // Get the leaderboards client using Play Games services.
        LeaderboardsClient leaderboardsClient = PlayGames.getLeaderboardsClient(getActivity());
}

Kotlin

Individua il codice per LeaderboardsClient.

import com.google.android.gms.games.LeaderboardsClient
import com.google.android.gms.games.Games
// Initialize the variables.
private lateinit var leaderboardsClient: LeaderboardsClient

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    leaderboardsClient = Games.getLeaderboardsClient(this,
        GoogleSignIn.getLastSignedInAccount(this))
}

E aggiornala come segue:

import com.google.android.gms.games.LeaderboardsClient
import com.google.android.gms.games.PlayGames
    // Initialize the variables.
private lateinit var leaderboardsClient: LeaderboardsClient

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    leaderboardsClient = PlayGames.getLeaderboardsClient(this)
}

Analogamente, utilizza i metodi corrispondenti per i seguenti client: AchievementsClient, EventsClient, GamesSignInClient, PlayerStatsClient, RecallClient, SnapshotsClient o PlayersClient.

Aggiorna i classi di accesso lato server

Per richiedere un token di accesso lato server, utilizza il metodo GamesSignInClient.requestServerSideAccess() instead of the GoogleSignInAccount.getServerAuthCode().

L'esempio seguente mostra come richiedere un token di accesso lato server.

Java

Individua il codice del corso GoogleSignInOptions.

    private static final int RC_SIGN_IN = 9001;
    private GoogleSignInClient googleSignInClient;

    private void startSignInForAuthCode() {
        /** Client ID for your backend server. */
        String webClientId = getString(R.string.webclient_id);
        GoogleSignInOptions signInOption = new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
            .requestServerAuthCode(webClientId)
            .build();

        GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOption);
        Intent intent = signInClient.getSignInIntent();
        startActivityForResult(intent, RC_SIGN_IN);
    }

    /** Auth code to send to backend server */
    private String mServerAuthCode;

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        if (requestCode == RC_SIGN_IN) {
            GoogleSignInResult result = Auth.GoogleSignInApi.getSignInResultFromIntent(data);
        if (result.isSuccess()) {
            mServerAuthCode = result.getSignInAccount().getServerAuthCode();
        } else {
            String message = result.getStatus().getStatusMessage();
            if (message == null || message.isEmpty()) {
                message = getString(R.string.signin_other_error);
            }
            new AlertDialog.Builder(this).setMessage(message)
                .setNeutralButton(android.R.string.ok, null).show();
        }
      }
    }

E aggiornala come segue:

  private void startRequestServerSideAccess() {
      GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(this);
      gamesSignInClient
          .requestServerSideAccess(OAUTH_2_WEB_CLIENT_ID, /* forceRefreshToken= */ false)
          .addOnCompleteListener(task -> {
              if (task.isSuccessful()) {
                  String serverAuthToken = task.getResult();
                  // Send authentication code to the backend game server.
                  // Exchange for an access token.
                  // Verify the player with Play Games Services REST APIs.
              } else {
                // Authentication code retrieval failed.
              }
        });
  }

Kotlin

Individua il codice del corso GoogleSignInOptions.

  // ... existing code

  private val RC_SIGN_IN = 9001
  private lateinit var googleSignInClient: GoogleSignInClient

  // Auth code to send to backend server.
  private var mServerAuthCode: String? = null

  private fun startSignInForAuthCode() {
      // Client ID for your backend server.
      val webClientId = getString(R.string.webclient_id)

      val signInOption = GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
          .requestServerAuthCode(webClientId)
          .build()

      googleSignInClient = GoogleSignIn.getClient(this, signInOption)
      val intent = googleSignInClient.signInIntent
      startActivityForResult(intent, RC_SIGN_IN)
  }

  override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
      super.onActivityResult(requestCode, resultCode, data)
      if (requestCode == RC_SIGN_IN) {
          val result = Auth.GoogleSignInApi.getSignInResultFromIntent(data)
          if (result.isSuccess) {
              mServerAuthCode = result.signInAccount.serverAuthCode
          } else {
              var message = result.status.statusMessage
              if (message == null || message.isEmpty()) {
                  message = getString(R.string.signin_other_error)
              }
              AlertDialog.Builder(this).setMessage(message)
                  .setNeutralButton(android.R.string.ok, null).show()
            }
        }
  }

E aggiornala come segue:

  private void startRequestServerSideAccess() {
  GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(this);
      gamesSignInClient
          .requestServerSideAccess(OAUTH_2_WEB_CLIENT_ID, /* forceRefreshToken= */ false)
          .addOnCompleteListener(task -> {
              if (task.isSuccessful()) {
                  String serverAuthToken = task.getResult();
                  // Send authentication code to the backend game server.
                  // Exchange for an access token.
                  // Verify the player with Play Games Services REST APIs.
              } else {
                // Authentication code retrieval failed.
              }
        });
  }

Eseguire la migrazione da GoogleApiClient

Per le integrazioni esistenti precedenti, il tuo gioco potrebbe dipendere dalla GoogleApiClient variante dell'API dell'SDK dei servizi per i giochi di Play. Questo protocollo è stato ritirato alla fine del 2017 e sostituito da client "senza connessione". Per eseguire la migrazione, puoi sostituire la classe GoogleApiClient con un equivalente "senza connessione". Ecco una mappatura delle classi comuni:

giochi v2

  // Replace com.google.android.gms.games.achievement.Achievements
  com.google.android.gms.games.AchievementsClient
  // Replace com.google.android.gms.games.leaderboard.Leaderboard
  com.google.android.gms.games.LeaderboardsClient
  // Replace com.google.android.gms.games.snapshot.Snapshots
  com.google.android.gms.games.SnapshotsClient
  // Replace com.google.android.gms.games.stats.PlayerStats
  com.google.android.gms.games.PlayerStatsClient
  // Replace com.google.android.gms.games.Players
  com.google.android.gms.games.PlayersClient
  // Replace com.google.android.gms.games.GamesStatusCodes
  com.google.android.gms.games.GamesClientStatusCodes

games v1

  com.google.android.gms.games.achievement.Achievements
  com.google.android.gms.games.leaderboard.Leaderboard
  com.google.android.gms.games.snapshot.Snapshots
  com.google.android.gms.games.stats.PlayerStats
  com.google.android.gms.games.Players
  com.google.android.gms.games.GamesStatusCodes

Crea ed esegui il gioco

Per compilare ed eseguire su Android Studio, consulta Creare ed eseguire l'app.

Testare il gioco

Verifica che il gioco funzioni come previsto testando. I test che esegui dipendono dalle funzionalità del gioco.

Di seguito è riportato un elenco di test comuni da eseguire.

  1. Accesso riuscito.

    1. L'accesso automatico funziona. L'utente deve aver eseguito l'accesso ai servizi per i giochi di Play al momento dell'avvio del gioco.

    2. Viene visualizzato il popup di benvenuto.

      Popup di benvenuto di esempio.
      Finestra popup di benvenuto di esempio (fai clic per ingrandire).

    3. Vengono visualizzati i messaggi di log di esito positivo. Esegui il seguente comando nel terminale:

      adb logcat | grep com.google.android.

      Un messaggio di log di esito positivo è mostrato nell'esempio seguente:

      [$PlaylogGamesSignInAction$SignInPerformerSource@e1cdecc
number=1 name=GAMES_SERVICE_BROKER>], returning true for shouldShowWelcomePopup.
[CONTEXT service_id=1 ]

  2. Garantisci la coerenza dei componenti dell'interfaccia utente.

    1. I popup, le classifiche e gli obiettivi vengono visualizzati correttamente e in modo coerente su varie dimensioni e orientamenti dello schermo nell'interfaccia utente (UI) dei servizi per i giochi di Google Play.

    2. L'opzione di disconnessione non è visibile nell'interfaccia utente di Play Services.

    3. L'ID giocatore è coerente e può essere utilizzato per l'integrazione di backend.

    4. Se il gioco utilizza l'autenticazione lato server, testa attentamente il flussorequestServerSideAccess. Assicurati che il server riceva il codice di autenticazione e che possa scambiarlo con un token di accesso. Testa gli scenari di successo e di errore per errori di rete e scenari client ID non validi.

Se il tuo gioco utilizzava una delle seguenti funzionalità, testala per assicurarti che funzioni come prima della migrazione:

  • Classifiche: invia i punteggi e visualizza le classifiche. Verifica che il ranking e la visualizzazione dei nomi e dei punteggi dei giocatori siano corretti.
  • Obiettivi: sblocca gli obiettivi e verifica che vengano registrati e visualizzati correttamente nell'interfaccia utente di Play Giochi.
  • Partite salvate: se il gioco utilizza le partite salvate, assicurati che il salvataggio e il caricamento dei progressi del gioco funzionino perfettamente. Questo è particolarmente importante per eseguire test su più dispositivi e dopo gli aggiornamenti delle app.

Attività post-migrazione

Completa i seguenti passaggi dopo aver eseguito la migrazione alla versione 2 di Google Play.

Pubblicare il gioco

Compila gli APK e pubblica il gioco in Play Console.

  1. Nel menu di Android Studio, seleziona Compila > Compila pacchetti/APK > Compila APK.
  2. Pubblica il tuo gioco. Per ulteriori informazioni, consulta Pubblicare app private da Play Console.