Android 游戏中的排行榜

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

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

准备工作

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

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

• 按照说明安装和设置要使用的应用 Google Play 游戏服务 设置 Google Play 服务 SDK 指南。
• 指定您希望在游戏中显示或更新的排行榜 按照 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 可以获取发起调用的软件包的身份。默认排行榜界面的示例如下所示。