Zu Play Spieledienste V2 (Java oder Kotlin) migrieren

In diesem Dokument wird beschrieben, wie Sie vorhandene Spiele vom Games SDK v1 zum Games SDK v2 migrieren.

Hinweis

Sie können eine beliebige IDE wie Android Studio verwenden, um Ihr Spiel zu migrieren. Führen Sie die folgenden Schritte aus, bevor Sie zu Games v2 migrieren:

Abhängigkeiten aktualisieren

  1. Suchen Sie in der Datei build.gradle Ihres Moduls in den Abhängigkeiten auf Modulebene nach dieser Zeile.

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

    Ersetzen Sie ihn durch den folgenden Code:

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

    Ersetzen Sie version durch die neueste Version des Games SDK.

  2. Führen Sie nach dem Aktualisieren der Abhängigkeiten alle Schritte in diesem Dokument aus.

Von der eingestellten Google-Anmeldung migrieren

Ersetzen Sie die Klasse GoogleSignInClient durch die Klasse GamesSignInClient.

Java

Suchen Sie die Dateien mit der Klasse 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);
}

und aktualisieren Sie sie auf Folgendes:

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

Suchen Sie die Dateien mit der Klasse 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)
}

und aktualisieren Sie sie auf Folgendes:

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)
}

GoogleSignIn-Code aktualisieren

Die GoogleSignIn API und die zugehörigen Bereiche werden im Games v2 SDK nicht unterstützt. Ersetzen Sie den GoogleSignIn API-Code für OAuth 2.0-Bereiche durch die GamesSignInClient API, wie im folgenden Beispiel gezeigt:

Java

Suchen Sie die Dateien mit der GoogleSignIn-Klasse und den Bereichen.

// 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");
            }
        });
  }

und aktualisieren Sie sie auf Folgendes:

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

Suchen Sie die Dateien mit der GoogleSignIn-Klasse und den Bereichen.

// 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")
        }
    }
}

und aktualisieren Sie sie auf Folgendes:

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

GamesSignInClient-Code hinzufügen

Wenn der Spieler angemeldet ist, entfernen Sie die Schaltfläche für die Anmeldung über Play-Spieldienste aus Ihrem Spiel. Wenn sich der Nutzer beim Starten des Spiels nicht anmeldet, muss weiterhin eine Schaltfläche mit dem Symbol für Play-Spieldienste angezeigt werden. Der Anmeldevorgang muss dann mit GamesSignInClient.signIn() gestartet werden.

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
            }
        }
  }

Abmeldecode entfernen

Entfernen Sie den Code für GoogleSignInClient.signOut.

Entfernen Sie den im folgenden Beispiel gezeigten Code:

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.
    }
}

Erfolgreiche automatische Anmeldung prüfen

Fügen Sie den folgenden Code ein, um zu prüfen, ob Sie automatisch angemeldet wurden, und fügen Sie die benutzerdefinierte Logik hinzu, falls verfügbar.

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
        }
    }
}

Namen und Methoden der Clientklasse aktualisieren

Bei der Migration zu Games v2 werden die Namen der Clientklassen mit anderen Methoden abgerufen. Verwenden Sie die entsprechenden PlayGames.getxxxClient()-Methoden anstelle der Games.getxxxClient()-Methoden.

Verwenden Sie beispielsweise für LeaderboardsClient PlayGames.getLeaderboardsClient() anstelle der Methode Games.getLeaderboardsClient().

Java

Suchen Sie den Code für 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));
}

und aktualisieren Sie sie auf Folgendes:

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

Suchen Sie den Code für 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))
}

und aktualisieren Sie sie auf Folgendes:

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)
}

Verwenden Sie die entsprechenden Methoden auch für die folgenden Kunden: AchievementsClient, EventsClient, GamesSignInClient, PlayerStatsClient, RecallClient, SnapshotsClient oder PlayersClient.

Serverseitige Zugriffsklassen aktualisieren

Wenn du ein serverseitiges Zugriffstoken anfordern möchtest, verwende die Methode GamesSignInClient.requestServerSideAccess() anstelle der Methode GoogleSignInAccount.getServerAuthCode().

Im folgenden Beispiel wird gezeigt, wie ein serverseitiges Zugriffstoken angefordert wird.

Java

Suchen Sie den Code für den Kurs 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();
        }
      }
    }

und aktualisieren Sie sie auf Folgendes:

  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

Suchen Sie den Code für den Kurs 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()
            }
        }
  }

und aktualisieren Sie sie auf Folgendes:

  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.
              }
        });
  }

Von GoogleApiClient migrieren

Bei älteren Integrationen hängt Ihr Spiel möglicherweise von der GoogleApiClient API-Variante des Play Games Services SDK ab. Dieser Dienst wurde Ende 2017 eingestellt und durch „verbindungslose“ Clients ersetzt. Zur Migration können Sie die Klasse GoogleApiClient durch ein verbindungsloses Äquivalent ersetzen. In der folgenden Tabelle sind die gängigen Klassenzuordnungen von „Spiele“ v1 zu „Spiele“ v2 aufgeführt:

games v2 (aktuell) games v1 (alt)
com.google.android.gms.games.AchievementsClient com.google.android.gms.games.achievement.Achievements
com.google.android.gms.games.LeaderboardsClient com.google.android.gms.games.leaderboard.Leaderboard
com.google.android.gms.games.SnapshotsClient com.google.android.gms.games.snapshot.Snapshots
com.google.android.gms.games.PlayerStatsClient com.google.android.gms.games.stats.PlayerStats
com.google.android.gms.games.PlayersClient com.google.android.gms.games.Players
com.google.android.gms.games.GamesClientStatusCodes com.google.android.gms.games.GamesStatusCodes

Spiel erstellen und ausführen

Informationen zum Erstellen und Ausführen in Android Studio finden Sie unter App erstellen und ausführen.

Spiel testen

Testen Sie Ihr Spiel, um sicherzustellen, dass es wie vorgesehen funktioniert. Welche Tests Sie durchführen, hängt von den Funktionen Ihres Spiels ab.

Im Folgenden finden Sie eine Liste gängiger Tests.

  1. Erfolgreiche Anmeldung

    1. Die automatische Anmeldung funktioniert. Der Nutzer sollte beim Starten des Spiels in den Play-Spieldiensten angemeldet sein.

    2. Das Willkommens-Pop-up wird angezeigt.

      Beispiel für ein Willkommens-Pop-up
      Beispiel für ein Begrüßungs-Pop-up (zum Vergrößern anklicken)

    3. Es werden Erfolgsmeldungen angezeigt. Führen Sie im Terminal den folgenden Befehl aus:

      adb logcat | grep com.google.android.

      Im folgenden Beispiel wird eine erfolgreiche Protokollmeldung angezeigt:

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

  2. Achten Sie auf Einheitlichkeit bei den UI-Komponenten.

    1. Pop-ups, Bestenlisten und Erfolge werden in der Benutzeroberfläche der Play-Spieldienste korrekt und konsistent bei verschiedenen Bildschirmgrößen und -ausrichtungen angezeigt.

    2. Die Option zum Abmelden ist in der Benutzeroberfläche der Play-Spieldienste nicht sichtbar.

    3. Achte darauf, dass du die Player-ID abrufen kannst und dass die serverseitigen Funktionen gegebenenfalls wie erwartet funktionieren.

    4. Wenn das Spiel die serverseitige Authentifizierung verwendet, testen Sie den requestServerSideAccess-Vorgang gründlich. Der Server muss den Autorisierungscode erhalten und gegen ein Zugriffstoken eintauschen können. Testen Sie sowohl Erfolgs- als auch Fehlerszenarien auf Netzwerkfehler und ungültige client ID-Szenarien.

Wenn Sie in Ihrem Spiel eine der folgenden Funktionen verwendet haben, testen Sie sie, um sicherzustellen, dass sie wie vor der Migration funktionieren:

  • Bestenlisten: Hier können Sie Ihre Punktzahlen einreichen und Bestenlisten aufrufen. Prüfen Sie, ob die Spielernamen und -ergebnisse korrekt angezeigt werden.
  • Erfolge: Sie können Erfolge freischalten und prüfen, ob sie korrekt aufgezeichnet und in der Play Spiele-Benutzeroberfläche angezeigt werden.
  • Gespeicherte Spiele: Wenn das Spiel gespeicherte Spiele verwendet, muss das Speichern und Laden des Spielfortschritts einwandfrei funktionieren. Dies ist besonders wichtig, wenn Sie auf mehreren Geräten und nach App-Updates testen.

Aufgaben nach der Migration

Führen Sie die folgenden Schritte aus, nachdem Sie zu games v2 migriert sind.

Spiel veröffentlichen

Erstellen Sie die APKs und veröffentlichen Sie das Spiel in der Play Console.

  1. Wählen Sie im Android Studio-Menü Build > Build Bundles/APKs > Build APKs aus.
  2. Veröffentlichen Sie Ihr Spiel. Weitere Informationen finden Sie unter Private Apps über die Play Console veröffentlichen.