Android 游戏中的排行榜

注意： 本指南适用于 Play 游戏服务 v2 SDK。如需了解此 SDK 的旧版本，请参阅 Play 游戏服务 v1 文档。

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

准备工作

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

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

• 按照设置 Google Play 服务 SDK 指南中的说明安装并设置应用，以使用 Google Play 游戏服务。

• 按照 Google Play 管理中心指南中的说明，定义您希望在游戏中显示或更新的排行榜。

• 在 GitHub 的 Android 示例页面中下载并查看排行榜代码示例。

• 熟悉质量核对清单中所述的建议。

获取排行榜客户端

如需开始使用排行榜 API，您的游戏必须先获取一个 LeaderboardsClient 对象。为此，您可以调用 PlayGames.getLeadeboardsClient() 方法并传入 activity。

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

更新玩家得分

当玩家得分发生变化时（例如，玩家完成游戏时），游戏可以在排行榜上更新玩家得分，具体做法是调用 LeaderboardsClient.submitScore() 并传入排行榜 ID 和原始得分值。

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

PlayGames.getLeaderboardsClient(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() {
  PlayGames.getLeaderboardsClient(this)
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

即使系统未返回任何结果，您也必须使用 startActivityForResult，以便 API 获取发出调用的软件包的身份。默认排行榜界面的示例如下所示。