Android 游戏排行榜

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

开始之前

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

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

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

获取排行榜客户端

要开始使用排行榜 API，您的游戏必须首先获取 LeaderboardsClient 对象。您可以通过调用 Games.getLeadeboardsClient() 方法并传入活动和当前玩家的 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 来显示 UI。

以下代码片段显示了您的应用如何更新玩家得分。在代码片段中，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 的示例。