Android 遊戲的排行榜

本指南說明如何在 Android 應用程式中使用排行榜 API 製作視覺排行榜、記錄玩家分數，並比較分數 與上一場遊戲工作階段的分數比較。您可以在 com.google.android.gms.games 和 com.google.android.gms.games.leaderboards 等套件中取得 API。

事前準備

如果您還沒有這樣做，建議您詳閱 排行榜遊戲概念。

開始使用排行榜 API 編寫程式碼之前：

• 按照操作說明安裝及設定應用程式來使用服務 Google Play 遊戲服務 「設定 Google Play 服務 SDK」指南。
• 定義遊戲要顯示或更新的排行榜，方法是 按照 Google Play 管理中心指南的說明操作。
• 下載並查看排行榜程式碼範例： Android 範例頁面。
• 請熟讀 品質檢查清單。

取得排行榜用戶端

遊戲必須先取得 LeaderboardsClient 物件，才能使用排行榜 API。要取得此物件，您可以呼叫 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。

以下程式碼片段說明應用程式如何更新玩家分數。在 程式碼片段，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 如下所示。