Ce document explique comment migrer des jeux existants du SDK games v1 vers le SDK games v2.
Avant de commencer
Vous pouvez utiliser l'IDE de votre choix, comme Android Studio, pour migrer votre jeu. Avant de migrer vers la version 2 de Games, procédez comme suit :
- Télécharger et installer Android Studio
- Votre jeu doit utiliser le SDK Jeux v1.
Mettre à jour les dépendances
Dans le fichier
build.gradle
de votre module, recherchez cette ligne dans les dépendances au niveau du module.implementation "com.google.android.gms:play-services-games-v1:+"
Remplacez-la par le code suivant :
implementation "com.google.android.gms:play-services-games-v2:version"
Remplacez version par la dernière version du SDK Games.
Une fois les dépendances mises à jour, assurez-vous de suivre toutes les étapes de ce document.
Définir l'ID du projet
Pour ajouter l'ID de projet du SDK des services de jeux Play à votre application, procédez comme suit :
Dans le fichier
AndroidManifest.xml
, ajoutez l'élément<meta-data>
et les attributs suivants à l'élément<application>
:<manifest> <application> <meta-data android:name="com.google.android.gms.games.APP_ID" android:value="@string/game_services_project_id"/> </application> </manifest>
Définissez la référence de la ressource de chaîne
@string/game_services_project_id
en indiquant l'ID de projet des services de jeux correspondant à votre jeu. L'ID de projet des services de jeux se trouve sous le nom de votre jeu sur la page Configuration de la Google Play Console.Dans le fichier
res/values/strings.xml
, ajoutez une référence de ressource de chaîne et définissez l'ID du projet comme valeur. Exemple :<!-- res/values/strings.xml --> <resources> <!-- Replace 0000000000 with your game’s project id. Example value shown above. --> <string translatable="false" name="game_services_project_id"> 0000000000 </string> </resources>
Migrer depuis l'ancienne version de Google Sign-In
Remplacez la classe GoogleSignInClient
par la classe GamesSignInClient
.
Java
Localisez les fichiers avec 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
GoogleSignInOptions signInOption =
new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN).build();
// Client used to sign in to Google services
GoogleSignInClient googleSignInClient =
GoogleSignIn.getClient(this, signInOptions);
}
Apportez-lui la modification suivante :
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();
PlayGamesSdk.initialize(this);
// Client used to sign in to Google services
GamesSignInClient gamesSignInClient =
PlayGames.getGamesSignInClient(getActivity());
}
Kotlin
Localisez les fichiers avec 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)
}
Apportez-lui la modification suivante :
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)
}
Mettre à jour le code GoogleSignIn
L'API GoogleSignIn
n'est pas compatible avec le SDK v2 pour les jeux. Remplacez le code de l'API GoogleSignIn
par l'API GamesSignInClient
, comme indiqué dans l'exemple suivant.
Pour demander un jeton d'accès côté serveur, utilisez la méthode GamesSignInClient.requestServerSideAccess()
.
Pour en savoir plus, consultez Mettre à jour les classes d'accès côté serveur.
Java
Localisez les fichiers avec la classe 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");
}
});
}
Apportez-lui la modification suivante :
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
Localisez les fichiers avec la classe 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")
}
}
}
Apportez-lui la modification suivante :
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()
}
Ajouter le code GamesSignInClient
Si le joueur est connecté, supprimez le bouton de connexion aux services de jeux Play de votre jeu. Si l'utilisateur choisit de ne pas se connecter au lancement du jeu, continuez à afficher un bouton avec l'icône des services de jeux Play et lancez le processus de connexion avec 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
}
}
}
Supprimer le code de déconnexion
Supprimez le code pour GoogleSignInClient.signOut
.
Supprimez le code indiqué dans l'exemple suivant :
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.
}
}
Vérifier la réussite de la connexion automatique
Incluez le code suivant pour vérifier si vous êtes automatiquement connecté et ajoutez la logique personnalisée si vous en avez une.
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
}
}
}
Mettre à jour les noms et les méthodes des classes de clients
Lorsque vous migrez vers games v2, les méthodes utilisées pour obtenir les noms de classe du client sont différentes.
Utilisez plutôt les méthodes PlayGames.getxxxClient()
correspondantes au lieu des méthodes Games.getxxxClient()
.
Par exemple, pour LeaderboardsClient
, utilisez PlayGames.getLeaderboardsClient()
au lieu de la méthode Games.getLeaderboardsClient()
.
Supprimez tout code associé aux classes GamesClient
et GamesMetadataClient
, car nous n'avons pas de classes de remplacement dans games v2.
Java
Localisez le code pour 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));
}
Apportez-lui la modification suivante :
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
Localisez le code pour 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))
}
Apportez-lui la modification suivante :
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)
}
De même, utilisez les méthodes correspondantes pour les clients suivants : AchievementsClient
, EventsClient
, GamesSignInClient
, PlayerStatsClient
, RecallClient
, SnapshotsClient
ou PlayersClient
.
Mettre à jour les classes d'accès côté serveur
Pour demander un jeton d'accès côté serveur, utilisez la méthode GamesSignInClient.requestServerSideAccess()
au lieu de la méthode GoogleSignInAccount.getServerAuthCode()
.
Pour en savoir plus, consultez Envoyer le code d'autorisation du serveur.
L'exemple suivant montre comment demander un jeton d'accès côté serveur.
Java
Recherchez le code de la classe 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();
}
}
}
Apportez-lui la modification suivante :
private void startRequestServerSideAccess() {
GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(this);
gamesSignInClient
.requestServerSideAccess(OAUTH_2_WEB_CLIENT_ID,
/* forceRefreshToken= */ false, /* additional AuthScope */ scopes)
.addOnCompleteListener(task -> {
if (task.isSuccessful()) {
AuthResponse authresp = task.getResult();
// Send the authorization code as a string and a
// list of the granted AuthScopes that were granted by the
// user. Exchange for an access token.
// Verify the player with Play Games Services REST APIs.
} else {
// Authentication code retrieval failed.
}
});
}
Kotlin
Recherchez le code de la classe 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()
}
}
}
Apportez-lui la modification suivante :
private void startRequestServerSideAccess() {
GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(this);
gamesSignInClient
.requestServerSideAccess(OAUTH_2_WEB_CLIENT_ID, /* forceRefreshToken= */ false,
/* additional AuthScope */ scopes)
.addOnCompleteListener(task -> {
if (task.isSuccessful()) {
AuthResponse authresp = task.getResult();
// Send the authorization code as a string and a
// list of the granted AuthScopes that were granted by the
// user. Exchange for an access token.
// Verify the player with Play Games Services REST APIs.
} else {
// Authentication code retrieval failed.
}
});
}
Migrer depuis GoogleApiClient
Pour les anciennes intégrations, il se peut que votre jeu dépende de la variante d'API GoogleApiClient
du SDK des services de jeux Play. Cette solution est obsolète depuis 2017 et a été remplacée par des clients "sans connexion".
Pour effectuer la migration, vous pouvez remplacer la classe GoogleApiClient
par un équivalent "sans connexion".
Le tableau suivant répertorie les mappages de classes courants de games v1 à games v2 :
games v2 (actuel) | games v1 (ancienne version) |
---|---|
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 |
Compiler et exécuter le jeu
Pour compiler et exécuter l'application sur Android Studio, consultez Créer et exécuter votre application.
Tester votre jeu
Assurez-vous que votre jeu fonctionne comme prévu en le testant. Les tests que vous effectuez dépendent des fonctionnalités de votre jeu.
Voici une liste des tests courants à exécuter.
Connexion établie
La connexion automatique fonctionne. L'utilisateur doit être connecté aux services de jeux Play au lancement du jeu.
Le pop-up de bienvenue s'affiche.
Exemple de pop-up de bienvenue (cliquez pour agrandir). Les messages de journaux de réussite s'affichent. Exécutez la commande suivante dans le terminal :
adb logcat | grep com.google.android.
Voici un exemple de message de journalisation réussi :
[
$PlaylogGamesSignInAction$SignInPerformerSource@e1cdecc number=1 name=GAMES_SERVICE_BROKER>], returning true for shouldShowWelcomePopup. [CONTEXT service_id=1 ]
Assurez-vous de la cohérence des composants de l'UI.
Les pop-ups, les classements et les succès s'affichent correctement et de manière cohérente sur différentes tailles et orientations d'écran dans l'interface utilisateur (UI) des services de jeux Play.
L'option de déconnexion n'est pas visible dans l'UI des services de jeux Play.
Assurez-vous de pouvoir récupérer l'ID du joueur et, le cas échéant, que les fonctionnalités côté serveur fonctionnent comme prévu.
Si le jeu utilise l'authentification côté serveur, testez minutieusement le flux
requestServerSideAccess
. Assurez-vous que le serveur reçoit le code d'autorisation et peut l'échanger contre un jeton d'accès. Testez les scénarios de réussite et d'échec pour les erreurs réseau et les scénariosclient ID
non valides.
Si votre jeu utilisait l'une des fonctionnalités suivantes, testez-les pour vous assurer qu'elles fonctionnent de la même manière qu'avant la migration :
- Classements : envoyez des scores et consultez les classements. Vérifiez que le classement, ainsi que les noms et les scores des joueurs sont corrects.
- Succès : déverrouillez des succès et vérifiez qu'ils sont correctement enregistrés et affichés dans l'UI Play Jeux.
- Jeux enregistrés : si le jeu utilise des jeux enregistrés, assurez-vous que l'enregistrement et le chargement de la progression du jeu fonctionnent parfaitement. Il est particulièrement important de tester cette fonctionnalité sur plusieurs appareils et après les mises à jour de l'application.
Tâches à effectuer après la migration
Procédez comme suit après avoir migré vers games v2.
Publier le jeu
Créez le ou les APK et publiez le jeu dans la Play Console.
- Dans le menu Android Studio, sélectionnez Build > Build Bundle(s) / APK(s) > Build APK(s) (Compiler > Compiler des bundle(s)/APK > Compiler des APK).
- Publiez votre jeu. Pour en savoir plus, consultez Publier des applications privées depuis la Play Console.