Android 遊戲中的排行榜

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

事前準備

建議您先複習排行榜遊戲概念，這會對您很有幫助。

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

• 按照設定 Google Play Services SDK 指南中的操作說明，安裝及設定您的應用程式以使用 Google Play 遊戲服務。
• 按照 Google Play 管理中心指南中的操作說明，定義您希望遊戲顯示或更新的排行榜。
• 前往 Android 範例頁面下載並查看排行榜程式碼範例。
• 熟讀品質檢查清單說明的推薦事項。

取得排行榜用戶端

遊戲必須先取得 LeaderboardsClient 物件才能使用排行榜 API。您可以藉由呼叫 Games.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 的範例。