Bảng xếp hạng trong trò chơi Android

Sau khi ngừng cung cấp API Đăng nhập bằng Google, chúng tôi sẽ xoá SDK games phiên bản 1 vào năm 2026. Sau tháng 2 năm 2025, bạn sẽ không thể xuất bản các trò chơi vừa tích hợp với SDK của games phiên bản 1 trên Google Play. Bạn nên sử dụng SDK của phiên bản 2.
Mặc dù các ứng dụng/trò chơi hiện có có tích hợp trò chơi phiên bản 1 trước đó vẫn tiếp tục hoạt động trong vài năm nữa, nhưng bạn nên di chuyển sang phiên bản 2 kể từ tháng 6 năm 2025.
Hướng dẫn này dành cho việc sử dụng SDK Dịch vụ trò chơi của Play phiên bản 1. Để biết thông tin về phiên bản SDK mới nhất, hãy xem tài liệu phiên bản 2.

Tài liệu này sẽ hướng dẫn bạn cách sử dụng API bảng xếp hạng trong một ứng dụng Android để tạo bảng xếp hạng hình ảnh, ghi lại điểm số của người chơi và so sánh điểm số đó với điểm số của người chơi trong các phiên chơi trước đó. Bạn có thể tìm thấy các API trong các gói com.google.android.gms.games và com.google.android.gms.games.leaderboards.

Trước khi bắt đầu

Nếu chưa từng có kinh nghiệm, bạn có thể xem lại các khái niệm về bảng xếp hạng của trò chơi.

Trước khi bắt đầu lập trình bằng API bảng xếp hạng, bạn hãy:

Tải ứng dụng bảng xếp hạng

Để có thể sử dụng API bảng xếp hạng, trước tiên, trò chơi của bạn phải có được một đối tượng LeaderboardsClient. Bạn có thể thực hiện việc này bằng cách gọi phương thức Games.getLeadeboardsClient() và truyền vào hoạt động cũng như GoogleSignInAccount cho trình phát hiện tại. Để tìm hiểu cách truy xuất thông tin tài khoản người chơi, hãy xem phần Đăng nhập vào trò chơi trên Android.

Cập nhật điểm số của người chơi

Khi điểm số của người chơi thay đổi (ví dụ: khi người chơi kết thúc trò chơi), trò chơi của bạn có thể cập nhật điểm số của họ trên bảng xếp hạng bằng cách gọi LeaderboardsClient.submitScore(), đồng thời truyền mã bảng xếp hạng cũng như giá trị điểm thô.

Đoạn mã sau đây cho thấy cách ứng dụng của bạn có thể cập nhật điểm số của người chơi:

Games.getLeaderboardsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .submitScore(getString(R.string.leaderboard_id), 1337);

Bạn nên xác định mã bảng xếp hạng trong tệp strings.xml để trò chơi của bạn có thể tham chiếu đến bảng xếp hạng theo mã tài nguyên. Khi thực hiện lệnh gọi để cập nhật và tải điểm số của người chơi, bạn phải nhớ làm theo các phương pháp hay nhất này để tránh vượt quá định mức API.

Hiển thị bảng xếp hạng

Để hiển thị bảng xếp hạng, hãy gọi LeaderboardsClient.getLeaderboardIntent() để lấy Intent tạo giao diện người dùng của bảng xếp hạng mặc định. Sau đó, trò chơi của bạn có thể hiển thị giao diện người dùng bằng cách gọi startActivityForResult.

Đoạn mã sau đây cho thấy cách ứng dụng của bạn có thể cập nhật điểm số của người chơi. Trong đoạn mã, RC_LEADERBOARD_UI là một số nguyên tùy ý cho mã yêu cầu.

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);
        }
      });
}

Xin lưu ý rằng mặc dù không có kết quả nào được trả về, chúng ta vẫn phải sử dụng startActivityForResult để API có thể lấy thông tin nhận dạng của gói gọi. Dưới đây là một ví dụ về giao diện người dùng của bảng xếp hạng mặc định.