En este documento, se describe cómo migrar juegos existentes del SDK de games v1 al SDK de games v2.
Antes de comenzar
Puedes usar cualquier IDE que prefieras, como Android Studio, para migrar tu juego. Completa los siguientes pasos antes de migrar a la versión 2 de la API de Games:
- Descarga e instala Android Studio
- Tu juego debe usar el SDK de juegos v1
Actualiza las dependencias
En el archivo
build.gradle
de tu módulo, busca esta línea en las dependencias a nivel del módulo.implementation "com.google.android.gms:play-services-games-v1:+"
Reemplázala por el siguiente código:
implementation "com.google.android.gms:play-services-games-v2:version"
Reemplaza version por la versión más reciente del SDK de juegos.
Después de actualizar las dependencias, asegúrate de completar todos los pasos de este documento.
Define el ID del proyecto
Para agregar el ID del proyecto del SDK de los Servicios de juego de Play a tu app, sigue estos pasos:
En el archivo
AndroidManifest.xml
, agrega el siguiente elemento<meta-data>
y los atributos al elemento<application>
:<manifest> <application> <meta-data android:name="com.google.android.gms.games.APP_ID" android:value="@string/game_services_project_id"/> </application> </manifest>
Define la referencia
@string/game_services_project_id
del recurso de cadenas usando como valor el ID del proyecto de los Servicios de juego. Puedes encontrar el ID del proyecto de los Servicios de juego debajo del nombre del juego en la página Configuración de Google Play Console.En el archivo
res/values/strings.xml
, agrega una referencia del recurso de cadenas y establece el ID del proyecto como el valor. Por ejemplo:<!-- 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>
Cómo migrar desde el Acceso con Google obsoleto
Reemplaza la clase GoogleSignInClient
por la clase GamesSignInClient
.
Java
Ubica los archivos con la clase 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);
}
Y actualízala a lo siguiente:
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
Ubica los archivos con la clase 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)
}
Y actualízala a lo siguiente:
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)
}
Actualiza el código de GoogleSignIn
La API de GoogleSignIn
no es compatible con el SDK de juegos v2. Reemplaza el código de la API de GoogleSignIn
por la API de GamesSignInClient
, como se muestra en el siguiente ejemplo.
Para solicitar un token de acceso del servidor, usa el método GamesSignInClient.requestServerSideAccess()
.
Para obtener más información, consulta Cómo actualizar las clases de acceso del servidor.
Java
Ubica los archivos con la clase 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");
}
});
}
Y actualízala a lo siguiente:
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
Ubica los archivos con la clase 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")
}
}
}
Y actualízala a lo siguiente:
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()
}
Agrega el código de GamesSignInClient
Si el jugador accedió correctamente, quita el botón de acceso a los Servicios de juego de Play de tu juego. Si el usuario decide no acceder cuando se inicia el juego, sigue mostrando un botón con el ícono de los Servicios de juego de Play y comienza el proceso de acceso 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
}
}
}
Cómo quitar el código de salida
Quita el código de GoogleSignInClient.signOut
.
Quita el código que se muestra en el siguiente ejemplo:
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.
}
}
Verifica que el acceso automático se haya realizado correctamente
Incluye el siguiente código para verificar si accediste automáticamente y agrega la lógica personalizada si la tienes disponible.
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
}
}
}
Actualiza los nombres y métodos de las clases de cliente
Cuando migres a la versión 2 de Games, los métodos que se usan para obtener los nombres de las clases de cliente serán diferentes.
En su lugar, usa los métodos PlayGames.getxxxClient()
correspondientes en lugar de los métodos Games.getxxxClient()
.
Por ejemplo, para LeaderboardsClient
, usa PlayGames.getLeaderboardsClient()
en lugar del método Games.getLeaderboardsClient()
.
Quita cualquier código relacionado con las clases GamesClient
y GamesMetadataClient
, ya que no tenemos ninguna clase de reemplazo en la versión 2 de los juegos.
Java
Ubica el código de 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));
}
Y actualízala a lo siguiente:
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
Ubica el código de 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))
}
Y actualízala a lo siguiente:
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)
}
Del mismo modo, usa los métodos correspondientes para los siguientes clientes: AchievementsClient
, EventsClient
, GamesSignInClient
, PlayerStatsClient
, RecallClient
, SnapshotsClient
o PlayersClient
.
Actualiza las clases de acceso del servidor
Para solicitar un token de acceso del servidor, usa el método GamesSignInClient.requestServerSideAccess()
en lugar del método GoogleSignInAccount.getServerAuthCode()
.
Para obtener más información, consulta Envía el código de autorización del servidor.
En el siguiente ejemplo, se muestra cómo solicitar un token de acceso del servidor.
Java
Busca el código de la clase 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();
}
}
}
Y actualízala a lo siguiente:
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
Busca el código de la clase 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()
}
}
}
Y actualízala a lo siguiente:
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.
}
});
}
Migración desde GoogleApiClient
En el caso de las integraciones existentes, es posible que tu juego dependa de la variante de API GoogleApiClient
del SDK de los Servicios de juego de Play. Esta función dejó de estar disponible a fines de 2017 y se reemplazó por clientes "sin conexión".
Para migrar, puedes reemplazar la clase GoogleApiClient
por un equivalente "sin conexión".
En la siguiente tabla, se enumeran las asignaciones de clases comunes de la versión 1 a la versión 2 de la API de Games:
games v2 (actual) | games v1 (heredado) |
---|---|
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 |
Compila y ejecuta el juego
Para compilar y ejecutar en Android Studio, consulta Cómo compilar y ejecutar tu app.
Cómo probar tu juego
Prueba tu juego para asegurarte de que funcione según lo previsto. Las pruebas que realices dependerán de las funciones del juego.
A continuación, se incluye una lista de pruebas comunes que se pueden ejecutar.
Acceso correcto.
El acceso automático funciona. El usuario debe acceder a los Servicios de juego de Play cuando inicie el juego.
Se muestra la ventana emergente de bienvenida.
Ejemplo de ventana emergente de bienvenida (haz clic para agrandar). Se muestran los mensajes de registro correctos. Ejecuta el siguiente comando en la terminal:
adb logcat | grep com.google.android.
En el siguiente ejemplo, se muestra un mensaje de registro exitoso:
[
$PlaylogGamesSignInAction$SignInPerformerSource@e1cdecc number=1 name=GAMES_SERVICE_BROKER>], returning true for shouldShowWelcomePopup. [CONTEXT service_id=1 ]
Garantiza la coherencia de los componentes de la IU.
Las ventanas emergentes, las tablas de clasificación y los logros se muestran de forma correcta y coherente en varios tamaños y orientaciones de pantalla en la interfaz de usuario (IU) de los Servicios de juego de Play.
La opción para salir no se ve en la IU de los Servicios de juego de Play.
Asegúrate de poder recuperar el ID de jugador correctamente y, si corresponde, de que las capacidades del servidor funcionen según lo esperado.
Si el juego usa la autenticación del servidor, prueba a fondo el flujo de
requestServerSideAccess
. Asegúrate de que el servidor reciba el código de autorización y pueda intercambiarlo por un token de acceso. Prueba las situaciones de éxito y de error para los errores de red y las situaciones declient ID
no válidas.
Si tu juego usaba alguna de las siguientes funciones, pruébalas para asegurarte de que funcionen igual que antes de la migración:
- Tablas de clasificación: Envía puntuaciones y consulta las tablas de clasificación. Verifica que la clasificación y la visualización de los nombres y las puntuaciones de los jugadores sean correctas.
- Logros: Desbloquea logros y verifica que se registren y muestren correctamente en la IU de Play Juegos.
- Juegos guardados: Si el juego usa juegos guardados, asegúrate de que el progreso del juego se guarde y cargue sin problemas. Esto es especialmente importante para probar en varios dispositivos y después de las actualizaciones de la app.
Tareas posteriores a la migración
Completa los siguientes pasos después de migrar a la versión 2 de la API de Games.
Publica el juego
Crea los APKs y publica el juego en Play Console.
- En el menú de Android Studio, selecciona Build > Build Bundles(s) / APK(s) > Build APK(s).
- Publicar tu juego. Para obtener más información, consulta Cómo publicar apps privadas desde Play Console.