Tablas de clasificación en juegos para Android

Después de la baja de la API de Acceso a Google, quitaremos el SDK de juegos v1 en 2026. Después de febrero de 2025, no podrás publicar títulos que se hayan integrado recientemente con el SDK de juegos v1 en Google Play. Te recomendamos que uses el SDK de juegos v2.
Si bien los títulos existentes con las integraciones de la versión 1 de los juegos anteriores seguirán funcionando durante un par de años, te recomendamos que migres a la versión 2 a partir de junio de 2025.
Esta guía se aplica al uso del SDK de la versión 1 de los Servicios de juego de Play. Si deseas obtener información sobre la versión más reciente del SDK, consulta la documentación de la versión 2.

En esta guía, se muestra cómo usar las APIs de tablas de clasificación en una aplicación para Android para crear tablas de clasificación visuales, registrar la puntuación de un jugador y compararla con la correspondiente a sus sesiones anteriores. Se pueden encontrar las APIs en los paquetes com.google.android.gms.games y com.google.android.gms.games.leaderboards.

Antes de comenzar

Si aún no lo hiciste, puede resultarte útil revisar los conceptos de juegos de tablas de clasificación.

Antes de comenzar a programar mediante las API de tablas de clasificación, haz lo siguiente:

Cómo obtener el cliente de tablas de clasificación

A fin de comenzar a usar la API de tablas de clasificación, el juego primero debe obtener un objeto LeaderboardsClient. Para ello, llama al método Games.getLeadeboardsClient() y pasa la actividad y el GoogleSignInAccount del reproductor actual. Si quieres saber cómo recuperar la información de la cuenta del jugador, consulta Información sobre el acceso a juegos para Android.

Cómo actualizar la puntuación del jugador

Cuando la puntuación del jugador cambia (por ejemplo, cuando se termina el juego), el juego puede actualizar la puntuación en la tabla de clasificación llamando a LeaderboardsClient.submitScore() y pasando el ID de la tabla de clasificación y el valor de la puntuación sin procesar.

En el siguiente fragmento de código, se muestra cómo la app puede actualizar la puntuación del jugador:

Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .submitScore(getString(R.string.leaderboard_id), 1337);

Una práctica recomendada consiste en definir el ID de la tabla de clasificación en el archivo strings.xml, de modo que el juego pueda hacer referencia a las tablas de clasificación por ID de recurso. Cuando realices llamadas para actualizar y cargar puntuaciones de jugadores, asegúrate de seguir también estas prácticas recomendadas a fin de evitar exceder tu cuota de API.

Cómo mostrar una tabla de clasificación

Si deseas mostrar la tabla de clasificación, llama a LeaderboardsClient.getLeaderboardIntent() para obtener un Intent y crear la interfaz de usuario de la tabla de clasificación predeterminada. Para que pueda abrir la IU, el juego podrá llamar a startActivityForResult.

En el siguiente fragmento de código, se muestra cómo la app puede actualizar la puntuación del jugador. En este fragmento, RC_LEADERBOARD_UI es un número entero arbitrario para el código de solicitud.

private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

Ten en cuenta que, aunque no se muestra ningún resultado, debemos usar startActivityForResult para que la API pueda obtener la identidad del paquete que realiza la llamada. A continuación, se muestra un ejemplo de la IU predeterminada de tablas de clasificación.