Android 游戏中的排行榜

本指南向您展示如何在 Android 应用中使用排行榜 API 创建视觉排行榜、记录玩家的分数以及将分数与玩家来自先前游戏会话的分数进行比较。这些 API 位于 com.google.android.gms.games 和 com.google.android.gms.games.leaderboards 包中。

开始之前

如果您尚未这样做，您可能会发现查看排行榜游戏概念很有帮助。

在开始使用排行榜 API 编写代码之前

按照设置 Google Play 服务 SDK 指南中的说明安装和设置您的应用以使用 Google Play 游戏服务。
通过遵循 Google Play Console 指南中的说明，定义您希望游戏显示或更新的排行榜。
下载并查看 GiHub 上 Android 示例页面中的排行榜代码示例。
熟悉质量检查清单中描述的建议。

获取排行榜客户端

要开始使用排行榜 API，您的游戏必须首先获取 LeaderboardsClient 对象。您可以通过调用 PlayGames.getLeadeboardsClient() 方法并传入活动来执行此操作。

更新玩家的分数

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

以下代码片段显示了您的应用如何更新玩家的分数

PlayGames.getLeaderboardsClient(this)
    .submitScore(getString(R.string.leaderboard_id), 1337);

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

显示排行榜

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

以下代码片段显示了您的应用如何更新玩家的分数。在代码片段中，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 可以获取调用包的标识。下面显示了默认排行榜 UI 的示例。