Android 游戏中的排行榜

在 Google 登录 API 弃用后，我们将在 2026 年移除 games v1 SDK。2025 年 2 月后，您将无法在 Google Play 上发布新集成了 games v1 SDK 的游戏。我们建议您改用 games v2 SDK。
虽然现有使用先前 games v1 集成的游戏将继续运行几年，但建议您从 2025 年 6 月开始迁移到 v2。
本指南适用于使用 Play Games Services v1 SDK。有关最新 SDK 版本的信息，请参阅v2 文档。

本指南介绍如何在 Android 应用中使用排行榜 API 来创建可视化排行榜、记录玩家得分以及将得分与玩家之前游戏会话的得分进行比较。这些 API 位于 com.google.android.gms.games 和 com.google.android.gms.games.leaderboards 软件包中。

准备工作

如果您尚未这样做，建议您查看排行榜游戏概念。

在使用排行榜 API 编码之前

• 按照设置 Google Play Services SDK 指南中的说明安装和设置应用以使用 Google Play 游戏服务。
• 按照Google Play 管理中心指南中的说明定义游戏要显示或更新的排行榜。
• 下载并查看Android 示例页面中的排行榜代码示例。
• 熟悉质量核对清单中描述的建议。

获取排行榜客户端

要开始使用排行榜 API，您的游戏必须先获取一个 LeaderboardsClient 对象。您可以通过调用 Games.getLeadeboardsClient() 方法并传入 Activity 和当前玩家的 GoogleSignInAccount 来实现此目的。要了解如何检索玩家帐号信息，请参阅在 Android 游戏中登录。

更新玩家得分

当玩家得分改变时（例如，当玩家结束游戏时），您的游戏可以通过调用 LeaderboardsClient.submitScore()，并传入排行榜 ID 和原始得分值，来更新他们在排行榜上的得分。

以下代码段展示了您的应用如何更新玩家得分

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

一种好的做法是在 strings.xml 文件中定义排行榜 ID，以便您的游戏可以通过资源 ID 引用排行榜。在调用更新和加载玩家得分时，请务必同时遵循这些最佳实践，以避免超出您的 API 配额。

显示排行榜

要显示排行榜，请调用 LeaderboardsClient.getLeaderboardIntent() 获取一个 Intent 来创建默认的排行榜用户界面。然后您的游戏可以通过调用 startActivityForResult 来调出该界面。

以下代码段展示了您的应用如何更新玩家得分。在该代码段中，RC_LEADERBOARD_UI 是用于请求代码的任意整数。

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

请注意，即使没有返回结果，我们也必须使用 startActivityForResult，以便 API 可以获取调用软件包的身份。默认排行榜 UI 的示例如下所示。