Android 游戏中的排行榜

注意： 本指南介绍了如何使用 Play 游戏服务 v1 SDK。如需了解最新的 SDK 版本，请参阅 v2 文档。

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

准备工作

请阅读排行榜游戏概念（如果您尚未执行此操作）。

开始使用排行榜 API 进行编码之前，请执行以下操作：

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

获取排行榜客户端

如需开始使用排行榜 API，您的游戏必须先获取一个 LeaderboardsClient 对象。为此，您可以调用 Games.getLeadeboardsClient() 方法，并传入 activity 和当前播放器的 GoogleSignInAccount。如需了解如何检索玩家的账号信息，请参阅 Android 游戏中的登录功能。

注意 ：LeaderboardsClient 类使用 Google Play 服务 Task 类异步返回结果。如需详细了解如何使用任务来管理线程工作，请参阅 Tasks API 开发者指南。

更新玩家得分

当玩家得分发生变化时（例如，玩家完成游戏时），游戏可以在排行榜上更新玩家得分，具体做法是调用 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 获取发出调用的软件包的身份。默认排行榜界面的示例如下所示。